You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Use the built-in authentication and authorization in App Service and at the same time customize the sign-in and sign-out behavior.
4
-
ms.topic: article
2
+
title: Customize Sign-ins and Sign-outs in App Service Authentication
3
+
description: Use the built-in authentication and authorization in Azure App Service and at the same time customize the sign-in and sign-out behavior.
4
+
ms.topic: how-to
5
5
ms.date: 07/08/2024
6
6
ms.custom: AppServiceIdentity
7
7
author: cephalin
8
8
ms.author: cephalin
9
9
---
10
10
11
-
# Customize sign-in and sign-out in Azure App Service authentication
11
+
# Customize sign-ins and sign-outs in Azure App Service authentication
12
12
13
-
This article shows you how to customize user sign-ins and sign-outs while using the built-in [authentication and authorization in App Service](overview-authentication-authorization.md).
13
+
This article shows you how to customize user sign-ins and sign-outs while using the built-in [authentication and authorization in Azure App Service](overview-authentication-authorization.md).
14
14
15
15
## Use multiple sign-in providers
16
16
17
-
The portal configuration doesn't offer a turn-key way to present multiple sign-in providers to your users (such as both Facebook and X). However, it isn't difficult to add the functionality to your app. The steps are outlined as follows:
17
+
The Azure portal configuration doesn't offer a turnkey way to present multiple sign-in providers to your users (such as both Facebook and X). To add the functionality of using multiple sign-in providers to your app:
18
18
19
-
First, in the **Authentication / Authorization** page in the Azure portal, configure each of the identity provider you want to enable.
19
+
1. In the Azure portal, on the **Authentication / Authorization** page, configure each identity provider that you want to enable.
20
20
21
-
In **Action to take when request is not authenticated**, select **Allow Anonymous requests (no action)**.
21
+
1.In **Action to take when request is not authenticated**, select **Allow Anonymous requests (no action)**.
22
22
23
-
In the sign-in page, or the navigation bar, or any other location of your app, add a sign-in link to each of the providers you enabled (`/.auth/login/<provider>`). For example:
23
+
1. On the sign-in page, or the navigation bar, or any other location of your app, add a sign-in link to each of the providers that you enabled (`/.auth/login/<provider>`). For example:
24
24
25
-
```html
26
-
<ahref="/.auth/login/aad">Log in with Microsoft Entra</a>
27
-
<ahref="/.auth/login/facebook">Log in with Facebook</a>
28
-
<ahref="/.auth/login/google">Log in with Google</a>
29
-
<ahref="/.auth/login/x">Log in with X</a>
30
-
<ahref="/.auth/login/apple">Log in with Apple</a>
31
-
```
25
+
```html
26
+
<ahref="/.auth/login/aad">Log in with Microsoft Entra</a>
27
+
<ahref="/.auth/login/facebook">Log in with Facebook</a>
28
+
<ahref="/.auth/login/google">Log in with Google</a>
29
+
<ahref="/.auth/login/x">Log in with X</a>
30
+
<ahref="/.auth/login/apple">Log in with Apple</a>
31
+
```
32
32
33
-
When the user clicks on one of the links, the respective sign-in page opens to sign in the user.
33
+
When the user selects one of the links, the respective page opens for sign-in.
34
34
35
-
To redirect the user post-sign-in to a custom URL, use the `post_login_redirect_uri` query string parameter (not to be confused with the Redirect URI in your identity provider configuration). For example, to navigate the user to `/Home/Index` after sign-in, use the following HTML code:
35
+
To redirect the user to a custom URL after sign-in, use the `post_login_redirect_uri` query string parameter. (Don't confuse this parameter with the redirect URI in your identity provider configuration.) For example, to move the user to `/Home/Index` after sign-in, use the following HTML code:
In a client-directed sign-in, the application signs in the user to the identity provider using a provider-specific SDK. The application code then submits the resulting authentication token to App Service for validation (see [Authentication flow](overview-authentication-authorization.md#authentication-flow)) using an HTTP POST request. This validation itself doesn't actually grant you access to the desired app resources, but a successful validation will give you a session token that you can use to access app resources.
43
+
In a client-directed sign-in, the application signs in the user to the identity provider by using a provider-specific SDK. The application code then submits the resulting authentication token to App Service for validation (see [Authentication flow](overview-authentication-authorization.md#authentication-flow)) by using an HTTP `POST` request. This validation itself doesn't grant users access to the desired app resources, but a successful validation gives users a session token that they can use to access app resources.
44
44
45
-
To validate the provider token, App Service app must first be configured with the desired provider. At runtime, after you retrieve the authentication token from your provider, post the token to `/.auth/login/<provider>` for validation. For example:
45
+
To validate the provider token, the App Service app must first be configured with the desired provider. At runtime, after you retrieve the authentication token from your provider, post the token to `/.auth/login/<provider>` for validation. For example:
46
46
47
47
```
48
48
POST https://<appname>.azurewebsites.net/.auth/login/aad HTTP/1.1
The token format varies slightly according to the provider. See the following table for details:
54
+
The token format varies slightly according to the provider:
55
55
56
56
| Provider value | Required in request body | Comments |
57
57
|-|-|-|
58
58
|`aad`|`{"access_token":"<access_token>"}`| The `id_token`, `refresh_token`, and `expires_in` properties are optional. |
59
-
|`microsoftaccount`|`{"access_token":"<access_token>"}` or `{"authentication_token": "<token>"`|`authentication_token` is preferred over `access_token`. The `expires_in` property is optional. <br/> When requesting the token from Live services, always request the `wl.basic` scope. |
60
-
|`google`|`{"id_token":"<id_token>"}`| The `authorization_code` property is optional. Providing an `authorization_code` value will add an access token and a refresh token to the token store. When specified, `authorization_code`can also optionally be accompanied by a `redirect_uri` property. |
59
+
|`microsoftaccount`|`{"access_token":"<access_token>"}` or `{"authentication_token": "<token>"`|`authentication_token` is preferred over `access_token`. The `expires_in` property is optional. <br/> When you're requesting the token from live services, always request the `wl.basic` scope. |
60
+
|`google`|`{"id_token":"<id_token>"}`| The `authorization_code` property is optional. Providing an `authorization_code` value adds an access token and a refresh token to the token store. When `authorization_code`specified, it can optionally be accompanied by a `redirect_uri` property. |
61
61
|`facebook`|`{"access_token":"<user_access_token>"}`| Use a valid [user access token](https://developers.facebook.com/docs/facebook-login/access-tokens) from Facebook. |
> The GitHub provider for App Service authentication does not support customized sign-in and sign-out.
67
67
68
-
If the provider token is validated successfully, the API returns with an `authenticationToken` in the response body, which is your session token. To get more information on the user claims, see [Work with user identities in Azure App Service authentication](configure-authentication-user-identities.md).
68
+
If the provider token is validated successfully, the API returns with an `authenticationToken`value in the response body. This value is your session token. To get more information on the user claims, see [Work with user identities in Azure App Service authentication](configure-authentication-user-identities.md).
69
69
70
70
```json
71
71
{
@@ -76,7 +76,7 @@ If the provider token is validated successfully, the API returns with an `authen
76
76
}
77
77
```
78
78
79
-
Once you have this session token, you can access protected app resources by adding the `X-ZUMO-AUTH` header to your HTTP requests. For example:
79
+
After you have this session token, you can access protected app resources by adding the `X-ZUMO-AUTH` header to your HTTP requests. For example:
80
80
81
81
```
82
82
GET https://<appname>.azurewebsites.net/api/products/1
Users can initiate a sign-out by sending a `GET` request to the app's `/.auth/logout` endpoint. The `GET` request does the following:
88
+
Users can initiate a sign-out by sending a `GET` request to the app's `/.auth/logout` endpoint. The `GET` request:
89
89
90
90
- Clears authentication cookies from the current session.
91
91
- Deletes the current user's tokens from the token store.
@@ -103,38 +103,40 @@ By default, a successful sign-out redirects the client to the URL `/.auth/logout
103
103
GET /.auth/logout?post_logout_redirect_uri=/index.html
104
104
```
105
105
106
-
It's recommended that you [encode](https://wikipedia.org/wiki/Percent-encoding) the value of `post_logout_redirect_uri`.
106
+
We recommend that you [encode](https://wikipedia.org/wiki/Percent-encoding) the value of `post_logout_redirect_uri`.
107
107
108
-
When using fully qualified URLs, the URL must be either hosted in the same domain or configured as an allowed external redirect URL for your app. In the following example, to redirect to `https://myexternalurl.com` that's not hosted in the same domain:
108
+
When you're using fully qualified URLs, the URL must be either hosted in the same domain or configured as an allowed external redirect URL for your app. The following example redirects to an `https://myexternalurl.com` URL that's not hosted in the same domain:
109
109
110
110
```
111
111
GET /.auth/logout?post_logout_redirect_uri=https%3A%2F%2Fmyexternalurl.com
112
112
```
113
113
114
-
Run the following command in the [Azure Cloud Shell](../cloud-shell/quickstart.md):
114
+
Run the following command in [Azure Cloud Shell](../cloud-shell/quickstart.md):
115
115
116
116
```azurecli-interactive
117
117
az webapp auth update --name <app_name> --resource-group <group_name> --allowed-external-redirect-urls "https://myexternalurl.com"
118
118
```
119
119
120
120
## Preserve URL fragments
121
121
122
-
After users sign in to your app, they usually want to be redirected to the same section of the same page, such as `/wiki/Main_Page#SectionZ`. However, because [URL fragments](https://wikipedia.org/wiki/Fragment_identifier) (for example, `#SectionZ`) are never sent to the server, they are not preserved by default after the OAuth sign-in completes and redirects back to your app. Users then get a suboptimal experience when they need to navigate to the desired anchor again. This limitation applies to all server-side authentication solutions.
122
+
After users sign in to your app, they usually want to be redirected to the same section of the same page, such as `/wiki/Main_Page#SectionZ`. However, because [URL fragments](https://wikipedia.org/wiki/Fragment_identifier) (for example, `#SectionZ`) are never sent to the server, they're not preserved by default after the OAuth sign-in finishes and redirects back to your app. Users then get a suboptimal experience when they need to go to the desired anchor again. This limitation applies to all server-side authentication solutions.
123
123
124
-
In App Service authentication, you can preserve URL fragments across the OAuth sign-in. To do this, set an app setting called `WEBSITE_AUTH_PRESERVE_URL_FRAGMENT` to `true`. You can do it in the [Azure portal](https://portal.azure.com), or simply run the following command in the [Azure Cloud Shell](../cloud-shell/quickstart.md):
124
+
In App Service authentication, you can preserve URL fragments across the OAuth sign-in by setting `WEBSITE_AUTH_PRESERVE_URL_FRAGMENT` to `true`. You use this app setting in the [Azure portal](https://portal.azure.com), or you can run the following command in [Cloud Shell](../cloud-shell/quickstart.md):
125
125
126
126
```azurecli-interactive
127
127
az webapp config appsettings set --name <app_name> --resource-group <group_name> --settings WEBSITE_AUTH_PRESERVE_URL_FRAGMENT="true"
128
128
```
129
129
130
-
## Setting the sign-in accounts domain hint
130
+
## Set the domain hint for sign-in accounts
131
+
132
+
Both Microsoft accounts and Microsoft Entra let you sign in from multiple domains. For example, a Microsoft account allows `outlook.com`, `live.com`, and `hotmail.com` accounts. Microsoft Entra allows any number of custom domains for the sign-in accounts. However, you might want to accelerate your users straight to your own branded Microsoft Entra sign-in page (such as `contoso.com`).
131
133
132
-
Both Microsoft Account and Microsoft Entra lets you sign in from multiple domains. For example, Microsoft Account allows _outlook.com_, _live.com_, and _hotmail.com_ accounts. Microsoft Entra allows any number of custom domains for the sign-in accounts. However, you may want to accelerate your users straight to your own branded Microsoft Entra sign-in page (such as `contoso.com`). To suggest the domain name of the sign-in accounts, follow these steps.
134
+
To suggest the domain name of the sign-in accounts, follow these steps:
133
135
134
-
1. In [https://resources.azure.com](https://resources.azure.com), At the top of the page, select **Read/Write**.
135
-
2.In the left browser, navigate to **subscriptions** > **_\<subscription-name_** > **resourceGroups** > **_\<resource-group-name>_** > **providers** > **Microsoft.Web** > **sites** > **_\<app-name>_** > **config** > **authsettingsV2**.
136
-
3.Click**Edit**.
137
-
4. Add a `loginParameters` array with a `domain_hint` item.
136
+
1. In [Resource Explorer](https://resources.azure.com), at the top of the page, select **Read/Write**.
137
+
2.On the left pane, go to **subscriptions** > *subscription-name* > **resourceGroups** > *resource-group-name* > **providers** > **Microsoft.Web** > **sites** > *app-name* > **config** > **authsettingsV2**.
138
+
3.Select**Edit**.
139
+
4. Add a `loginParameters` array with a `domain_hint` item:
138
140
139
141
```json
140
142
"identityProviders": {
@@ -146,31 +148,28 @@ Both Microsoft Account and Microsoft Entra lets you sign in from multiple domain
146
148
}
147
149
```
148
150
149
-
5. Click **Put**.
151
+
5. Select **Put**.
150
152
151
-
This setting appends the `domain_hint` query string parameter to the login redirect URL.
153
+
This setting appends the `domain_hint` query string parameter to the sign-in redirect URL.
152
154
153
155
> [!IMPORTANT]
154
-
> It's possible for the client to remove the `domain_hint` parameter after receiving the redirect URL, and then login with a different domain. So while this function is convenient, it's not a security feature.
155
-
>
156
+
> It's possible for the client to remove the `domain_hint` parameter after receiving the redirect URL, and then sign in with a different domain. So although this function is convenient, it's not a security feature.
156
157
157
158
## Authorize or deny users
158
159
159
-
While App Service takes care of the simplest authorization case (i.e. reject unauthenticated requests), your app may require more fine-grained authorization behavior, such as limiting access to only a specific group of users. In certain cases, you need to write custom application code to allow or deny access to the signed-in user. In other cases, App Service or your identity provider may be able to help without requiring code changes.
160
+
App Service takes care of the simplest authorization case (for example, reject unauthenticated requests). But your app might require more fine-grained authorization behavior, such as limiting access to only a specific group of users.
In certain cases, you need to write custom application code to allow or deny access to the signed-in user. In other cases, App Service or your identity provider might be able to help without requiring code changes.
164
163
165
164
### Server level (Windows apps only)
166
165
167
-
For any Windows app, you can define authorization behavior of the IIS web server, by editing the *Web.config* file. Linux apps don't use IIS and can't be configured through *Web.config*.
166
+
For any Windows app, you can define authorization behavior of the IIS web server by editing the `Web.config` file. Linux apps don't use IIS and can't be configured through `Web.config`.
168
167
169
-
1. Navigate to `https://<app-name>.scm.azurewebsites.net/DebugConsole`
168
+
1. Go to `https://<app-name>.scm.azurewebsites.net/DebugConsole`.
170
169
171
-
1. In the browser explorer of your App Service files, navigate to *site/wwwroot*. If a *Web.config* doesn't exist, create it by selecting **+** > **New File**.
170
+
1. In the browser explorer of your App Service files, go to `site/wwwroot`. If `Web.config` doesn't exist, create it by selecting **+** > **New File**.
172
171
173
-
1. Select the pencil for *Web.config* to edit it. Add the following configuration code and click **Save**. If *Web.config* already exists, just add the `<authorization>` element with everything in it. Add the accounts you want to allow in the `<allow>` element.
172
+
1. Select the pencil for `Web.config` to edit the file. Add the following configuration code, and then select **Save**. If `Web.config` already exists, just add the `<authorization>` element with everything in it. In the `<allow>` element, add the accounts that you want to allow.
174
173
175
174
```xml
176
175
<?xml version="1.0" encoding="utf-8"?>
@@ -186,16 +185,16 @@ For any Windows app, you can define authorization behavior of the IIS web server
186
185
187
186
### Identity provider level
188
187
189
-
The identity provider may provide certain turn-key authorization. For example:
188
+
The identity provider might provide certain turnkey authorization. For example:
190
189
191
-
- You can [manage enterprise-level access](../active-directory/manage-apps/what-is-access-management.md) directly in Microsoft Entra. For instructions, see [How to remove a user's access to an application](../active-directory/manage-apps/methods-for-removing-user-access.md).
192
-
- For [Google](configure-authentication-provider-google.md), Google API projects that belong to an [organization](https://cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy#organizations) can be configured to allow access only to users in your organization (see [Google's **Setting up OAuth 2.0** support page](https://support.google.com/cloud/answer/6158849?hl=en)).
190
+
- You can [manage enterprise-level access](../active-directory/manage-apps/what-is-access-management.md) directly in Microsoft Entra. For instructions, see [Remove user access to applications](../active-directory/manage-apps/methods-for-removing-user-access.md).
191
+
- For [Google](configure-authentication-provider-google.md), Google API projects that belong to an [organization](https://cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy#organizations) can be configured to allow access only to users in your organization. See the [Manage OAuth Clients](https://support.google.com/cloud/answer/6158849?hl=en) Google support page.
193
192
194
193
### Application level
195
194
196
-
If either of the other levels don't provide the authorization you need, or if your platform or identity provider isn't supported, you must write custom code to authorize users based on the [user claims](configure-authentication-user-identities.md).
195
+
If either of the other levels doesn't provide the authorization that you need, or if your platform or identity provider isn't supported, you must write custom code to authorize users based on the [user claims](configure-authentication-user-identities.md).
197
196
198
-
## More resources
197
+
## Related content
199
198
200
199
- [Tutorial: Authenticate and authorize users end-to-end](tutorial-auth-aad.md)
201
200
- [Environment variables and app settings for authentication](reference-app-settings.md#authentication--authorization)
0 commit comments