Manage the API and runtime versions of App Service authentication

This article describes 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 after a few changes are made. Specifically, secret configuration must be moved to slot-sticky application settings. You can move secret configuration automatically from the Authentication section of your app on the portal.

Pin your app to a specific authentication runtime version

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 runs on the latest version of this platform middleware. These automatic updates are always backward 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 section explains how to temporarily pin an app to a specific version of the authentication middleware.

Automatic and manual version updates

You can pin your app to a specific version of the platform middleware by configuring a runtimeVersion setting for the app. Your app always runs on the latest version unless you choose to explicitly pin it to a specific version. There are a few versions supported at a time. If you pin to an invalid version that's no longer supported, your app uses the latest version instead. To always run the latest version, set runtimeVersion to ~1.

View and update the current runtime version

You can change the runtime version used by your app. The new runtime version should take effect after you restart the app.

View the current runtime version

You can view the current version of the platform authentication middleware by using the Azure CLI or via one of the built-in version HTTP endpoints in your app.

From the Azure CLI

By 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. 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 resembles the following example output, which is truncated for clarity:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}

From the version endpoint

You can also hit the /.auth/version endpoint on an app to view the current middleware version that the app is running on. The output will look similar to the following:

{
"version": "1.3.2"
}

Update the current runtime version

With Azure CLI, you can update the runtimeVersion setting in an app by using 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. Replace <my_resource_group> with the name of the resource group for your app. Replace <version> with a valid version of the 1.x runtime, or use ~1 for the latest version. To determine the version to pin to for Azure Functions, see Azure Functions runtime versions overview.

You can use the Azure CLI locally to execute this command after executing az login to sign in.