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 |
---|---|
AZURE_CLIENT_ID |
The Application (client) ID for the Azure AD app registration. |
AZURE_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": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_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": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_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.
To configure which accounts can sign in, see Modify the accounts supported by an application and Restrict your Azure AD app to a set of users in an Azure AD tenant.
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 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 are using Azure Active Directory, 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 |
---|---|
Azure AD | email address |
GitHub | username |
username |
Do 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 Twitter, 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.
Update role assignments
- 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.
Remove user
- 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 may take a few minutes.
- If the user is added back to the app, the
userId
changes.
Next steps
Feedback
Submit and view feedback for