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 preconfigured providers.
Note
Custom authentication is only available in the Azure Static Web Apps Standard plan.
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.
You can 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 a 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.
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_APP_SETTING_NAME |
The name of the application setting that holds the client secret generated by the authentication provider's custom registration for your static web app. |
If you register other 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.
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.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_APP_SETTING_NAME" }, "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, log in parameters, or custom claims.
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.
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.
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.
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.
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.
- Go to a Static Web Apps resource in the Azure portal.
- Under Settings, select Role Management.
- Select Invite.
- Select an Authorization provider from the list of options.
- 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.
- 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.
- Add a comma-separated list of role names in the Role box.
- Enter the maximum number of hours you want the invitation to remain valid.
- The maximum possible limit is 168 hours, which is seven days.
- Select Generate.
- Copy the link from the Invite link box.
- 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.
- Go to a Static Web Apps resource in the Azure portal.
- Under Settings, select Role Management.
- Select the user in the list.
- Edit the list of roles in the Role box.
- Select Update.
- Go to a Static Web Apps resource in the Azure portal.
- Under Settings, select Role Management.
- Locate the user in the list.
- Check the checkbox on the user's row.
- 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.