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.

Note

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

Configure a custom identity provider

Custom identity providers 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.

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.

Next, use the following sample to configure the provider in the configuration file.

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.

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 on using an existing registration.

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 authorization section for more information.

Authentication callbacks

Identity providers require a redirect URL to complete the login or logout request. Most providers require that you add the callback URLs to an allowlist. 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 <PROVIDER_NAME_IN_CONFIG> 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.

Login, logout, and purging user details

To use a custom identity 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 <PROVIDER_NAME_IN_CONFIG> placeholder.

Next steps