Zuplo
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:

  1. Requests an access token from Azure AD using the configured client credentials
  2. Caches the token for subsequent requests until it nears expiration
  3. Adds the token to the Authorization header as a Bearer token
  4. 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:

  1. Create an Azure AD app registration for your Zuplo gateway
  2. Generate a client secret for the app registration
  3. Configure your backend service (e.g., Azure Functions, App Service) to use Azure AD authentication
  4. 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

Read more about how policies work

Last modified on