Upstream Authentication

Upstream Azure AD Service Auth Policy

Secure your origin server with Azure Active Directory authentication by automatically adding an Authorization header to upstream requests. This policy enables your Zuplo gateway to authenticate with Azure AD-protected services using client credentials flow.

With this policy, you'll benefit from:

Enhanced Backend Security: Restrict access to your origin servers to only your Zuplo gateway
Simplified Authentication: Delegate authentication and authorization to your gateway without backend code changes
Automatic Token Management: Handle token acquisition, caching, and renewal automatically
Azure Integration: Seamlessly connect with Azure App Services, Functions, and other Azure AD-protected resources
Credential Security: Store sensitive Azure AD credentials securely in your Zuplo environment

For instructions on configuring Azure AD authentication, see Configure your App Service or Azure Functions app to use Azure AD login.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

Code(json)
 
{
  "name": "my-upstream-azure-ad-service-auth-inbound-policy",
  "policyType": "upstream-azure-ad-service-auth-inbound",
  "handler": {
    "export": "UpstreamAzureAdServiceAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "activeDirectoryClientId": "20edbb34-13e9-42d0-a63c-1b6a0a20d02d",
      "activeDirectoryClientSecret": "$env(ACTIVE_DIRECTORY_CLIENT_SECRET)",
      "activeDirectoryTenantId": "b8e4141e-31f4-43e3-9a96-f97f3eba1eea",
      "expirationOffsetSeconds": 300,
      "tokenRetries": 3
    }
  }
}

Policy Configuration

name <string> - The name of your policy instance. This is used as a reference in your routes.
policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be upstream-azure-ad-service-auth-inbound.
handler.export <string> - The name of the exported type. Value should be UpstreamAzureAdServiceAuthInboundPolicy.
handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

activeDirectoryTenantId (required) <string> - Azure Active Directory Tenant ID.
activeDirectoryClientId (required) <string> - The Application (client) ID of the Azure AD App Registration.
activeDirectoryClientSecret (required) <string> - The client secret of the Azure AD App Registration.
tokenRetries <number> - The number of times to retry fetching the token in the event of a failure.. Defaults to 3.
expirationOffsetSeconds <number> - The number of seconds less than the token expiration to cache the token. Defaults to 300.

Using the Policy

This policy authenticates your Zuplo gateway to Azure AD-protected backend services by automatically adding an OAuth 2.0 Bearer token to the Authorization header of upstream requests. It uses the Azure AD client credentials flow to obtain access tokens.

How It Works

The policy performs the following operations:

Requests an access token from Azure AD using the configured client credentials
Caches the token for subsequent requests until it nears expiration
Adds the token to the Authorization header as a Bearer token
Automatically handles token renewal when needed

Policy Configuration

Configure the policy with your Azure AD application credentials:

Code(json)
 
{
  "name": "azure-ad-service-auth",
  "export": "UpstreamAzureAdServiceAuthInboundPolicy",
  "module": "$import(@zuplo/runtime)",
  "options": {
    "activeDirectoryTenantId": "YOUR_TENANT_ID",
    "activeDirectoryClientId": "YOUR_CLIENT_ID",
    "activeDirectoryClientSecret": "$env(AZURE_CLIENT_SECRET)",
    "tokenRetries": 3,
    "expirationOffsetSeconds": 300
  }
}

Usage Example

Securing Azure Function App Access

Apply the policy to routes that need to access your Azure Function App:

Code(json)
 
{
  "paths": {
    "/api/data": {
      "get": {
        "x-zuplo-route": {
          "policies": {
            "inbound": ["jwt-auth", "azure-ad-service-auth"]
          },
          "handler": {
            "export": "forwardToOrigin",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "https://your-function-app.azurewebsites.net"
            }
          }
        }
      }
    }
  }
}

Azure AD Configuration

To use this policy, you need to:

Create an Azure AD app registration for your Zuplo gateway
Generate a client secret for the app registration
Configure your backend service (e.g., Azure Functions, App Service) to use Azure AD authentication
Grant the necessary permissions for your app registration to access your backend service

Security Considerations

Store the client secret as an environment variable using $env(VARIABLE_NAME) syntax
Ensure your Azure AD app has the minimum required permissions to access your backend services
Consider using managed identities for Azure resources when possible
Regularly rotate your client secrets according to your security policies