Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This article shows you how to customize the API and runtime versions of the built-in authentication and authorization in App Service.
There are two versions of the management API for App Service authentication. The V2 version is required for the "Authentication" experience in the Azure portal. An app already using the V1 API can upgrade to the V2 version once a few changes have been made. Specifically, secret configuration must be moved to slot-sticky application settings. This can be done automatically from the "Authentication" section of the portal for your app.
Warning
Migration to V2 will disable management of the App Service Authentication/Authorization feature for your application through some clients, such as its existing experience in the Azure portal, Azure CLI, and Azure PowerShell. This cannot be reversed.
The V2 API doesn't support creation or editing of Microsoft Account as a distinct provider as was done in V1. Rather, it uses the converged Microsoft identity platform to sign-in users with both Microsoft Entra and personal Microsoft accounts. When switching to the V2 API, the V1 Microsoft Entra configuration is used to configure the Microsoft identity platform provider. The V1 Microsoft Account provider will be carried forward in the migration process and continue to operate as normal, but you should move to the newer Microsoft identity platform model. See Support for Microsoft Account provider registrations to learn more.
The automated migration process will move provider secrets into application settings and then convert the rest of the configuration into the new format. To use the automatic migration:
The following steps will allow you to manually migrate the application to the V2 API if you don't wish to use the automatic version mentioned above.
Get your existing configuration by using the V1 API:
az webapp auth show -g <group_name> -n <site_name>
In the resulting JSON payload, make note of the secret value used for each provider you've configured:
clientSecret
googleClientSecret
facebookAppSecret
twitterConsumerSecret
microsoftAccountClientSecret
Important
The secret values are important security credentials and should be handled carefully. Do not share these values or persist them on a local machine.
Create slot-sticky application settings for each secret value. You may choose the name of each application setting. Its value should match what you obtained in the previous step or reference a Key Vault secret that you've created with that value.
To create the setting, you can use the Azure portal or run a variation of the following for each provider:
# For Web Apps, Google example
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
Note
The application settings for this configuration should be marked as slot-sticky, meaning that they will not move between environments during a slot swap operation. This is because your authentication configuration itself is tied to the environment.
Create a new JSON file named authsettings.json
. Take the output that you received previously and remove each secret value from it. Write the remaining output to the file, making sure that no secret is included. In some cases, the configuration may have arrays containing empty strings. Make sure that microsoftAccountOAuthScopes
doesn't, and if it does, switch that value to null
.
Add a property to authsettings.json
that points to the application setting name you created earlier for each provider:
clientSecretSettingName
googleClientSecretSettingName
facebookAppSecretSettingName
twitterConsumerSecretSettingName
microsoftAccountClientSecretSettingName
An example file after this operation might look similar to the following, in this case only configured for Microsoft Entra ID:
{
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
"name": "authsettings",
"type": "Microsoft.Web/sites/config",
"location": "Central US",
"properties": {
"enabled": true,
"runtimeVersion": "~1",
"unauthenticatedClientAction": "AllowAnonymous",
"tokenStoreEnabled": true,
"allowedExternalRedirectUrls": null,
"defaultProvider": "AzureActiveDirectory",
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"clientSecret": "",
"clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
"clientSecretCertificateThumbprint": null,
"issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
"allowedAudiences": [
"https://mywebapp.azurewebsites.net"
],
"additionalLoginParams": null,
"isAadAutoProvisioned": true,
"aadClaimsAuthorization": null,
"googleClientId": null,
"googleClientSecret": null,
"googleClientSecretSettingName": null,
"googleOAuthScopes": null,
"facebookAppId": null,
"facebookAppSecret": null,
"facebookAppSecretSettingName": null,
"facebookOAuthScopes": null,
"gitHubClientId": null,
"gitHubClientSecret": null,
"gitHubClientSecretSettingName": null,
"gitHubOAuthScopes": null,
"twitterConsumerKey": null,
"twitterConsumerSecret": null,
"twitterConsumerSecretSettingName": null,
"microsoftAccountClientId": null,
"microsoftAccountClientSecret": null,
"microsoftAccountClientSecretSettingName": null,
"microsoftAccountOAuthScopes": null,
"isAuthFromFile": "false"
}
}
Submit this file as the new Authentication/Authorization configuration for your app:
az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json
Validate that your app is still operating as expected after this gesture.
Delete the file used in the previous steps.
You've now migrated the app to store identity provider secrets as application settings.
If your existing configuration contains a Microsoft Account provider and doesn't contain a Microsoft Entra provider, you can switch the configuration over to the Microsoft Entra provider and then perform the migration. To do this:
/.auth/login/microsoftaccount/callback
. Copy this URI./.auth/login/aad/callback
. This will allow the registration to be used by the App Service Authentication / Authorization configuration.<authentication-endpoint>/<tenant-id>/v2.0
, and replace <authentication-endpoint> with the authentication endpoint for your cloud environment (e.g., "https://login.microsoftonline.com" for global Microsoft Entra ID), also replacing <tenant-id> with your Directory (tenant) ID./.auth/login/aad
endpoint on your site and complete the sign-in flow.Warning
It is possible to converge the two registrations by modifying the supported account types for the Microsoft Entra app registration. However, this would force a new consent prompt for Microsoft Account users, and those users' identity claims may be different in structure, sub
notably changing values since a new App ID is being used. This approach is not recommended unless thoroughly understood. You should instead wait for support for the two registrations in the V2 API surface.
Once the above steps have been performed, navigate to the app in the Azure portal. Select the "Authentication (preview)" section.
Alternatively, you may make a PUT request against the config/authsettingsv2
resource under the site resource. The schema for the payload is the same as captured in File-based configuration.
When you enable authentication/authorization, platform middleware is injected into your HTTP request pipeline as described in the feature overview. This platform middleware is periodically updated with new features and improvements as part of routine platform updates. By default, your web or function app will run on the latest version of this platform middleware. These automatic updates are always backwards compatible. However, in the rare event that this automatic update introduces a runtime issue for your web or function app, you can temporarily roll back to the previous middleware version. This article explains how to temporarily pin an app to a specific version of the authentication middleware.
You can pin your app to a specific version of the platform middleware by setting a runtimeVersion
setting for the app. Your app always runs on the latest version unless you choose to explicitly pin it back to a specific version. There will be a few versions supported at a time. If you pin to an invalid version that is no longer supported, your app will use the latest version instead. To always run the latest version, set runtimeVersion
to ~1.
You can change the runtime version used by your app. The new runtime version should take effect after restarting the app.
You can view the current version of the platform authentication middleware either using the Azure CLI or via one of the built-in version HTTP endpoints in your app.
Using the Azure CLI, view the current middleware version with the az webapp auth show command.
az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>
In this code, replace <my_app_name>
with the name of your app. Also replace <my_resource_group>
with the name of the resource group for your app.
You'll see the runtimeVersion
field in the CLI output. It will resemble the following example output, which has been truncated for clarity:
{
"additionalLoginParams": null,
"allowedAudiences": null,
...
"runtimeVersion": "1.3.2",
...
}
You can also hit /.auth/version endpoint on an app also to view the current middleware version that the app is running on. It will resemble the following example output:
{
"version": "1.3.2"
}
Using the Azure CLI, you can update the runtimeVersion
setting in the app with the az webapp auth update command.
az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>
Replace <my_app_name>
with the name of your app. Also replace <my_resource_group>
with the name of the resource group for your app. Also, replace <version>
with a valid version of the 1.x runtime or ~1
for the latest version. See the release notes on the different runtime versions to help determine the version to pin to.
You can run this command from the Azure Cloud Shell by choosing Try it in the preceding code sample. You can also use the Azure CLI locally to execute this command after executing az login to sign in.
Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register now