Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: File-Based Configuration of AuthN/AuthZ description: Configure authentication and authorization in App Service using a configuration file to enable certain preview capabilities. ms.topic: how-to ms.date: 07/15/2021 ms.custom: AppServiceIdentity author: cephalin ms.author: cephalin ms.service: azure-app-service # customer intent: As a developer, I want to configure authentication and authorization in App Service by using a configuration file so that I can enable preview capabilities. --- # Configure authentication in Azure App Service by using a configuration file With [App Service authentication](overview-authentication-authorization.md), the authentication settings can be configured with a file. You may need to use file-based configuration to use certain preview capabilities of App Service authentication / authorization before they're exposed via [Azure Resource Manager](../azure-resource-manager/management/overview.md) APIs. > [!IMPORTANT] > Remember that your app payload, and therefore this file, may move between environments, as with [slots](./deploy-staging-slots.md). It is likely you would want a different app registration pinned to each slot, and in these cases, you should continue to use the standard configuration method instead of using the configuration file. ## Enable file-based configuration 1. Create a new JSON file for your configuration at the root of your project (deployed to C:\home\site\wwwroot in your web / function app). Fill in your desired configuration according to the [file-based configuration reference](#configuration-file-reference). If modifying an existing Azure Resource Manager configuration, make sure to translate the properties captured in the `authsettings` collection into your configuration file. 2. Modify the existing configuration, which is captured in the [Azure Resource Manager](../azure-resource-manager/management/overview.md) APIs under `Microsoft.Web/sites/<siteName>/config/authsettingsV2`. To modify it, you can use an [Azure Resource Manager template](../azure-resource-manager/templates/overview.md) or a tool like [Azure Resource Explorer](https://resources.azure.com/). Within the authsettingsV2 collection, set two properties (you may remove others): 1. Set `platform.enabled` to "true" 2. Set `platform.configFilePath` to the name of the file (for example, "auth.json") > [!NOTE] > The format for `platform.configFilePath` varies between platforms. On Windows, both relative and absolute paths are supported. Relative is recommended. For Linux, only absolute paths are supported currently, so the value of the setting should be "/home/site/wwwroot/auth.json" or similar. Once you have made this configuration update, the contents of the file will be used to define the behavior of App Service Authentication / Authorization for that site. If you ever wish to return to Azure Resource Manager configuration, you can do so by removing changing the setting `platform.configFilePath` to null. ## Configuration file reference Any secrets that will be referenced from your configuration file must be stored as [application settings](./configure-common.md#configure-app-settings). You may name the settings anything you wish. Just make sure that the references from the configuration file use the same keys. The following exhausts possible configuration options within the file: ```json { "platform": { "enabled": <true|false> }, "globalValidation": { "unauthenticatedClientAction": "RedirectToLoginPage|AllowAnonymous|RejectWith401|RejectWith404", "redirectToProvider": "<default provider alias>", "excludedPaths": [ "/path1", "/path2", "/path3/subpath/*" ] }, "httpSettings": { "requireHttps": <true|false>, "routes": { "apiPrefix": "<api prefix>" }, "forwardProxy": { "convention": "NoProxy|Standard|Custom", "customHostHeaderName": "<host header value>", "customProtoHeaderName": "<proto header value>" } }, "login": { "routes": { "logoutEndpoint": "<logout endpoint>" }, "tokenStore": { "enabled": <true|false>, "tokenRefreshExtensionHours": "<double>", "fileSystem": { "directory": "<directory to store the tokens in if using a file system token store (default)>" }, "azureBlobStorage": { "sasUrlSettingName": "<app setting name containing the sas url for the Azure Blob Storage if opting to use that for a token store>" } }, "preserveUrlFragmentsForLogins": <true|false>, "allowedExternalRedirectUrls": [ "https://uri1.azurewebsites.net/", "https://uri2.azurewebsites.net/", "url_scheme_of_your_app://easyauth.callback" ], "cookieExpiration": { "convention": "FixedTime|IdentityProviderDerived", "timeToExpiration": "<timespan>" }, "nonce": { "validateNonce": <true|false>, "nonceExpirationInterval": "<timespan>" } }, "identityProviders": { "azureActiveDirectory": { "enabled": <true|false>, "registration": { "openIdIssuer": "<issuer url>", "clientId": "<app id>", "clientSecretSettingName": "APP_SETTING_CONTAINING_AAD_SECRET", }, "login": { "loginParameters": [ "paramName1=value1", "paramName2=value2" ] }, "validation": { "allowedAudiences": [ "audience1", "audience2" ] } }, "facebook": { "enabled": <true|false>, "registration": { "appId": "<app id>", "appSecretSettingName": "APP_SETTING_CONTAINING_FACEBOOK_SECRET" }, "graphApiVersion": "v3.3", "login": { "scopes": [ "public_profile", "email" ] }, }, "gitHub": { "enabled": <true|false>, "registration": { "clientId": "<client id>", "clientSecretSettingName": "APP_SETTING_CONTAINING_GITHUB_SECRET" }, "login": { "scopes": [ "profile", "email" ] } }, "google": { "enabled": true, "registration": { "clientId": "<client id>", "clientSecretSettingName": "APP_SETTING_CONTAINING_GOOGLE_SECRET" }, "login": { "scopes": [ "profile", "email" ] }, "validation": { "allowedAudiences": [ "audience1", "audience2" ] } }, "twitter": { "enabled": <true|false>, "registration": { "consumerKey": "<consumer key>", "consumerSecretSettingName": "APP_SETTING_CONTAINING TWITTER_CONSUMER_SECRET" } }, "apple": { "enabled": <true|false>, "registration": { "clientId": "<client id>", "clientSecretSettingName": "APP_SETTING_CONTAINING_APPLE_SECRET" }, "login": { "scopes": [ "profile", "email" ] } }, "openIdConnectProviders": { "<providerName>": { "enabled": <true|false>, "registration": { "clientId": "<client id>", "clientCredential": { "clientSecretSettingName": "<name of app setting containing client secret>" }, "openIdConnectConfiguration": { "authorizationEndpoint": "<url specifying authorization endpoint>", "tokenEndpoint": "<url specifying token endpoint>", "issuer": "<url specifying issuer>", "certificationUri": "<url specifying jwks endpoint>", "wellKnownOpenIdConfiguration": "<url specifying .well-known/open-id-configuration endpoint - if this property is set, the other properties of this object are ignored, and authorizationEndpoint, tokenEndpoint, issuer, and certificationUri are set to the corresponding values listed at this endpoint>" } }, "login": { "nameClaimType": "<name of claim containing name>", "scopes": [ "openid", "profile", "email" ], "loginParameterNames": [ "paramName1=value1", "paramName2=value2" ], } }, //... } } } ``` ## Related content - [Tutorial: Authenticate and authorize users end-to-end](tutorial-auth-aad.md) - [Environment variables and app settings for authentication](reference-app-settings.md#authentication--authorization)