Edit

Share via

Custom authentication in Azure Static Web Apps

  • Article

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 preconfigured 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 might also choose to store your secrets in Azure Key Vault.

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

Setting Name Value
AZURE_CLIENT_ID The Application (client) ID for the Microsoft Entra app registration.
`AZURE_CLIENT_SECRET_APP_SETTING_NAME The name of the application setting that holds the client secret for the Microsoft Entra app registration.

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

Microsoft Entra 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.

Microsoft Entra 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": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Make sure to replace <TENANT_ID> with your Microsoft Entra tenant ID.

Microsoft Entra Version 2

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

Make sure to replace <TENANT_ID> with your Microsoft Entra tenant ID.

For more information on how to configure Microsoft Entra ID, see the App Service Authentication/Authorization documentation on using an existing registration.

To configure which accounts can sign in, see Modify the accounts supported by an application and Restrict your Microsoft Entra app to a set of users in a Microsoft Entra tenant.

Note

While the configuration section for Microsoft Entra ID 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.

Custom certificate

Use the following steps to add a custom certificate to your Microsoft Entra ID app registration.

  1. If it isn't already, upload your certificate to a Microsoft Key Vault.

  2. Add a managed identity on your Static Web App.

    For user assigned managed identities, set keyVaultReferenceIdentity property on your static site object to the resourceId of the user assigned managed identity.

    Skip this step if your managed identity is system assigned.

  3. Grant the managed identity the following access policies:

    • Secrets: Get/List
    • Certificates: Get/List

  4. Update the auth config section of the azureActiveDirectory configuration section with a clientSecretCertificateKeyVaultReference value as shown in the following example:

    {
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}

    Make sure to replace your values in for the placeholders surrounded by <>.

    In the secret URI, specify the key vault name and certificate name. If you want to pin to a version, include the certificate version, otherwise omit the version to allow the runtime to select the newest version of the certificate.

    Set clientSecretCertificateThumbprint equal to * to always pull the latest version of the certificates thumbprint.

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're using Microsoft Entra ID, 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 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
User details /.auth/me
Purge user details /.auth/purge/<PROVIDER_NAME_IN_CONFIG>

If you're using Microsoft Entra ID, use aad as the value for the <PROVIDER_NAME_IN_CONFIG> placeholder.

Manage roles

Every user who accesses a static web app belongs to one or more roles. There are two built-in roles that users can belong to:

  • anonymous: All users automatically belong to the anonymous role.
  • authenticated: All users who are signed in belong to the authenticated role.

Beyond the built-in roles, you can assign custom roles to users, and reference them in the staticwebapp.config.json file.

Add a user to a role

To add a user to a role, you generate invitations that allow you to associate users to specific roles. Roles are defined and maintained in the staticwebapp.config.json file.

Create an invitation

Invitations are specific to individual authorization-providers, so consider the needs of your app as you select which providers to support. Some providers expose a user's email address, while others only provide the site's username.

Authorization provider Exposes
Microsoft Entra ID email address
GitHub username
X username

Use the following steps to create an invitation.

  1. Go to a Static Web Apps resource in the Azure portal.
  2. Under Settings, select Role Management.
  3. Select Invite.
  4. Select an Authorization provider from the list of options.
  5. Add either the username or email address of the recipient in the Invitee details box.
    • For GitHub and X, enter the username. For all others, enter the recipient's email address.
  6. Select the domain of your static site from the Domain drop-down menu.
    • The domain you select is the domain that appears in the invitation. If you have a custom domain associated with your site, choose the custom domain.
  7. Add a comma-separated list of role names in the Role box.
  8. Enter the maximum number of hours you want the invitation to remain valid.
    • The maximum possible limit is 168 hours, which is seven days.
  9. Select Generate.
  10. Copy the link from the Invite link box.
  11. Email the invitation link to the user that you're granting access to.

When the user selects the link in the invitation, they're prompted to sign in with their corresponding account. Once successfully signed in, the user is associated with the selected roles.

Caution

Make sure your route rules don't conflict with your selected authentication providers. Blocking a provider with a route rule prevents users from accepting invitations.

Update role assignments

  1. Go to a Static Web Apps resource in the Azure portal.
  2. Under Settings, select Role Management.
  3. Select the user in the list.
  4. Edit the list of roles in the Role box.
  5. Select Update.

Remove user

  1. Go to a Static Web Apps resource in the Azure portal.
  2. Under Settings, select Role Management.
  3. Locate the user in the list.
  4. Check the checkbox on the user's row.
  5. Select Delete.

As you remove a user, keep in mind the following items:

  • Removing a user invalidates their permissions.
  • Worldwide propagation might take a few minutes.
  • If the user is added back to the app, the userId changes.

Next steps

Set user roles programmatically