Custom authentication in Azure Static Web Apps

Azure Static Web Apps provides managed authentication that uses provider registrations managed by Azure. To enable more flexibility over the registration, you can override the defaults with a custom registration.

  • Custom authentication also allows you to configure custom providers that support OpenID Connect. This configuration allows the registration of multiple external providers.

  • Using any custom registrations disables all pre-configured providers.

  • Specifically for Azure Active Directory (AAD) registrations, you have the option of providing a tenant, which allows you to bypass the invitation flow for group management.

Note

Custom authentication is only available in the Azure Static Web Apps Standard plan.

Override pre-configured provider

The settings used to override a provider are configured in the auth section of the configuration file.

To avoid putting secrets in source control, the configuration looks into application settings for a matching name in the configuration file. You may also choose to store your secrets in Azure Key Vault.

Configuration

Setting up custom authentication requires that you reference a few secrets stored as application settings.

Azure Active Directory providers are available in two different versions. Version 1 explicitly defines the userDetailsClaim, which allows the payload to return user information. By contrast, version 2 returns user information by default, and is designated by v2.0 in the openIdIssuer URL.

To create the registration, begin by creating the following application settings:

Setting Name Value
AAD_CLIENT_ID The Application (client) ID for the Azure AD app registration.
AAD_CLIENT_SECRET The client secret for the Azure AD app registration.

Azure Active Directory Version 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AAD_CLIENT_ID",
          "clientSecretSettingName": "AAD_CLIENT_SECRET"
        }
      }
    }
  }
}

Make sure to replace <TENANT_ID> with your Azure Active Directory tenant ID.

Azure Active Directory Version 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AAD_CLIENT_ID",
          "clientSecretSettingName": "AAD_CLIENT_SECRET"
        }
      }
    }
  }
}

Make sure to replace <TENANT_ID> with your Azure Active Directory tenant ID.

For more information on how to configure Azure Active Directory, see the App Service Authentication/Authorization documentation.

Note

While the configuration section for Azure Active Directory is azureActiveDirectory, the platform aliases this to aad in the URL's for login, logout and purging user information. Refer to the authentication and authorisation section for more information.

Configure a custom OpenID Connect provider

This section shows you how to configure Azure Static Web Apps to use a custom authentication provider that adheres to the OpenID Connect (OIDC) specification. The following steps are required to use an custom OIDC provider.

  • One or more OIDC providers are allowed.
  • Each provider must have a unique name in the configuration.
  • Only one provider can serve as the default redirect target.

Register your application with the identity provider

You're required to register your application's details with an identity provider. Check with the provider regarding the steps needed to generate a client ID and client secret for your application.

Once the application is registered with the identity provider, create the following application secrets in the application settings of the Static Web App:

Setting Name Value
MY_PROVIDER_CLIENT_ID The client ID generated by the authentication provider for your static web app.
MY_PROVIDER_CLIENT_SECRET The client secret generated by the authentication provider's custom registration for your static web app.

If you register additional providers, each one needs an associated client ID and client secret store in application settings.

Important

Application secrets are sensitive security credentials. Do not share this secret with anyone, distribute it within a client application, or check into source control.

Once you have the registration credentials, use the following steps to create a custom registration.

  1. You need the OpenID Connect metadata for the provider. This information is often exposed via a configuration metadata document, which is the provider's Issuer URL suffixed with /.well-known/openid-configuration. Gather this configuration URL.

  2. Add an auth section of the configuration file with a configuration block for the OIDC providers, and your provider definition.

    {
      "auth": {
        "identityProviders": {
          "customOpenIdConnectProviders": {
            "myProvider": {
              "registration": {
                "clientIdSettingName": "MY_PROVIDER_CLIENT_ID",
                "clientCredential": {
                  "clientSecretSettingName": "MY_PROVIDER_CLIENT_SECRET"
                },
                "openIdConnectConfiguration": {
                  "wellKnownOpenIdConfiguration": "https://<PROVIDER_ISSUER_URL>/.well-known/openid-configuration"
                }
              },
              "login": {
                "nameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                "scopes": [],
                "loginParameterNames": []
              }
            }
          }
        }
      }
    }
    
  • The provider name, myProvider in this example, is the unique identifier used by Azure Static Web Apps.
  • Make sure to replace <PROVIDER_ISSUER_URL> with the path to the Issuer URL of the provider.
  • The login object allows you to provide values for: custom scopes, login parameters, or custom claims.

Login, logout, and purging user details

To use a custom OIDC provider, use the following URL patterns.

Action Pattern
Login /.auth/login/<PROVIDER_NAME_IN_CONFIG>
Logout /.auth/logout
Purge user details /.auth/purge/<PROVIDER_NAME_IN_CONFIG>

If you are using Azure Active Directory, use aad as the value for the <AUTHENTICATION_PROVIDER_NAME> placeholder.

Authentication callbacks

Custom OIDC providers require redirect URL to complete the login or logout request. The following endpoints are available as redirect destinations.

Type URL pattern
Login https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
Logout https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

If you are using Azure Active Directory, use aad as the value for the <AUTHENTICATION_PROVIDER_NAME> placeholder.

Note

These URLs are provided by Azure Static Web Apps to receive the response from the authentication provider, you don't need to create pages at these routes.

Next steps