Skip to content

Commit 03c71c1

Browse files
ktoliverktoliver
committed
edits
1 parent 84ae014 commit 03c71c1

File tree

2 files changed

+68
-61
lines changed

2 files changed

+68
-61
lines changed

‎articles/app-service/configure-authentication-user-identities.md

Lines changed: 31 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: User identities in AuthN/AuthZ
3-
description: Learn how to access user identities when using the built-in authentication and authorization in App Service.
2+
title: User Identities in AuthN/AuthZ
3+
description: Learn how to access user identities when you use the built-in authentication and authorization in Azure App Service.
44
ms.topic: article
55
ms.date: 03/29/2021
66
ms.custom: AppServiceIdentity
@@ -10,29 +10,33 @@ ms.author: cephalin
1010

1111
# Work with user identities in Azure App Service authentication
1212

13-
This article shows you how to work with user identities when using the built-in [authentication and authorization in App Service](overview-authentication-authorization.md).
13+
This article shows you how to work with user identities when you use built-in [authentication and authorization in Azure App Service](overview-authentication-authorization.md).
1414

1515
## Access user claims in app code
1616

17-
For all language frameworks, App Service makes the claims in the incoming token (whether from an authenticated end user or a client application) available to your code by injecting them into the request headers. External requests aren't allowed to set these headers, so they're present only if set by App Service. Some example headers include:
17+
For all language frameworks, App Service makes the claims in the incoming token (whether from an authenticated end user or from a client application) available to your code by injecting them into the request headers. External requests aren't allowed to set these headers, so they're present only if set by App Service.
18+
19+
Some example headers are described in the following table:
1820

1921
| Header | Description |
2022
|------------------------------|-----------------------------------------------------------------------|
21-
| `X-MS-CLIENT-PRINCIPAL` | A Base64 encoded JSON representation of available claims. For more information, see [Decoding the client principal header](#decoding-the-client-principal-header). |
22-
| `X-MS-CLIENT-PRINCIPAL-ID` | An identifier for the caller set by the identity provider. |
23-
| `X-MS-CLIENT-PRINCIPAL-NAME` | A human-readable name for the caller set by the identity provider, such as email address or user principal name. |
24-
| `X-MS-CLIENT-PRINCIPAL-IDP` | The name of the identity provider used by App Service Authentication. |
23+
| `X-MS-CLIENT-PRINCIPAL` | A Base64-encoded JSON representation of available claims. For more information, see [Decode the client principal header](#decode-the-client-principal-header). |
24+
| `X-MS-CLIENT-PRINCIPAL-ID` | An identifier for the caller, which the identity provider sets. |
25+
| `X-MS-CLIENT-PRINCIPAL-NAME` | A human-readable name for the caller, set by the identity provider, such as an email address or a user principal name. |
26+
| `X-MS-CLIENT-PRINCIPAL-IDP` | The name of the identity provider that App Service authentication uses. |
2527

2628
Provider tokens are also exposed through similar headers. For example, Microsoft Entra also sets `X-MS-TOKEN-AAD-ACCESS-TOKEN` and `X-MS-TOKEN-AAD-ID-TOKEN` as appropriate.
2729

2830
> [!NOTE]
29-
> Different language frameworks might present these headers to the app code in different formats, such as lowercase or title case.
31+
> Different language frameworks might present these headers to the app code in different formats, such as in lowercase or by using title case.
32+
33+
Code that is written in any language or framework can get the information that it needs from these headers. [Decode the client principal header](#decode-the-client-principal-header) covers this process. For some frameworks, the platform also provides extra options that might be more convenient.
3034

31-
Code that is written in any language or framework can get the information that it needs from these headers. [Decoding the client principal header](#decoding-the-client-principal-header) covers this process. For some frameworks, the platform also provides extra options that might be more convenient.
35+
### Decode the client principal header
3236

33-
### Decoding the client principal header
37+
`X-MS-CLIENT-PRINCIPAL` contains the full set of available claims as Base64-encoded JSON. These claims go through a default claims-mapping process, so some might have different names than you would see if you processed the token directly.
3438

35-
`X-MS-CLIENT-PRINCIPAL` contains the full set of available claims as Base64 encoded JSON. These claims go through a default claims-mapping process, so some might have different names than you would see if processing the token directly. The decoded payload is structured as follows:
39+
Here's the decoded payload is structured:
3640

3741
```json
3842
{
@@ -50,14 +54,14 @@ Code that is written in any language or framework can get the information that i
5054

5155
| Property | Type | Description |
5256
|------------|------------------|---------------------------------------|
53-
| `auth_typ` | string | The name of the identity provider used by App Service Authentication. |
54-
| `claims` | array of objects | An array of objects representing the available claims. Each object contains `typ` and `val` properties. |
55-
| `typ` | string | The name of the claim. It might be subject to default claims mapping and could be different from the corresponding claim contained in a token. |
57+
| `auth_typ` | string | The name of the identity provider that App Service authentication uses. |
58+
| `claims` | array of objects | An array of objects that represent the available claims. Each object contains `typ` and `val` properties. |
59+
| `typ` | string | The name of the claim. It might be subject to default claims mapping and might be different from the corresponding claim that is contained in a token. |
5660
| `val` | string | The value of the claim. |
57-
| `name_typ` | string | The name claim type, which is typically a URI providing scheme information about the `name` claim if one is defined. |
58-
| `role_typ` | string | The role claim type, which is typically a URI providing scheme information about the `role` claim if one is defined. |
61+
| `name_typ` | string | The name claim type, which is typically a URI that provides scheme information about the `name` claim if one is defined. |
62+
| `role_typ` | string | The role claim type, which is typically a URI that provides scheme information about the `role` claim if one is defined. |
5963

60-
To process this header, your app needs to decode the payload and iterate through the `claims` array to find the claims of interest. It might be convenient to convert them into a representation used by the app's language framework. Here's an example of this process in C# that constructs a [ClaimsPrincipal](/dotnet/api/system.security.claims.claimsprincipal) type for the app to use:
64+
To process this header, your app must decode the payload and iterate through the `claims` array to find relevant claims. It might be convenient to convert claims into a representation that the app's language framework uses. Here's an example of this process in C# that constructs a [ClaimsPrincipal](/dotnet/api/system.security.claims.claimsprincipal) type for the app to use:
6165

6266
```csharp
6367
using System;
@@ -105,10 +109,10 @@ public static class ClaimsPrincipalParser
105109

106110
/**
107111
* At this point, the code can iterate through `principal.Claims` to
108-
* check claims as part of validation. Alternatively, we can convert
112+
* check claims as part of validation. Alternatively, you can convert
109113
* it into a standard object with which to perform those checks later
110114
* in the request pipeline. That object can also be leveraged for
111-
* associating user data, etc. The rest of this function performs such
115+
* associating user data, and so on. The rest of this function performs such
112116
* a conversion to create a `ClaimsPrincipal` as might be used in
113117
* other .NET code.
114118
*/
@@ -125,18 +129,17 @@ public static class ClaimsPrincipalParser
125129

126130
For ASP.NET 4.6 apps, App Service populates [ClaimsPrincipal.Current](/dotnet/api/system.security.claims.claimsprincipal.current) with the authenticated user's claims, so you can follow the standard .NET code pattern, including the `[Authorize]` attribute. Similarly, for PHP apps, App Service populates the `_SERVER['REMOTE_USER']` variable. For Java apps, the claims are [accessible from the Tomcat servlet](configure-language-java-security.md#authenticate-users-easy-auth).
127131

128-
For [Azure Functions](../azure-functions/functions-overview.md), `ClaimsPrincipal.Current` isn't populated for .NET code, but you can still find the user claims in the request headers, or get the `ClaimsPrincipal` object from the request context or even through a binding parameter. For more information, see [Working with client identities in Azure Functions](../azure-functions/functions-bindings-http-webhook-trigger.md#working-with-client-identities).
132+
For [Azure Functions](../azure-functions/functions-overview.md), `ClaimsPrincipal.Current` isn't populated for .NET code, but you can still find the user claims in the request headers, or get the `ClaimsPrincipal` object from the request context or even through a binding parameter. For more information, see [Work with client identities in Azure Functions](../azure-functions/functions-bindings-http-webhook-trigger.md#working-with-client-identities).
129133

130-
For .NET Core, [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web/) supports populating the current user with App Service authentication. To learn more, you can read about it on the [Microsoft.Identity.Web wiki](https://github.com/AzureAD/microsoft-identity-web/wiki/1.2.0#integration-with-azure-app-services-authentication-of-web-apps-running-with-microsoftidentityweb), or see it demonstrated in [this tutorial for a web app accessing Microsoft Graph](./scenario-secure-app-access-microsoft-graph-as-user.md?tabs=command-line#install-client-library-packages).
134+
For .NET Core, [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web/) supports populating the current user with App Service authentication. To learn more, review the [Microsoft.Identity.Web wiki](https://github.com/AzureAD/microsoft-identity-web/wiki/1.2.0#integration-with-azure-app-services-authentication-of-web-apps-running-with-microsoftidentityweb) or see it demonstrated in [this tutorial for a web app accessing Microsoft Graph](./scenario-secure-app-access-microsoft-graph-as-user.md?tabs=command-line#install-client-library-packages).
131135

132136
> [!NOTE]
133-
> For claims mapping to work, you must enable the [Token store](overview-authentication-authorization.md#token-store).
137+
> For claims mapping to work, you must enable the [token store](overview-authentication-authorization.md#token-store).
134138
135-
## Access user claims using the API
139+
## Access user claims by using the API
136140

137-
If the [token store](overview-authentication-authorization.md#token-store) is enabled for your app, you can also obtain other details on the authenticated user by calling `/.auth/me`.
141+
If the [token store](overview-authentication-authorization.md#token-store) is enabled for your app, you can also obtain other details on the authenticated user by calling `/.auth/me`.
138142

139-
## Next steps
143+
## Related content
140144

141-
> [!div class="nextstepaction"]
142-
> [Tutorial: Authenticate and authorize users end-to-end](tutorial-auth-aad.md)
145+
- [Tutorial: Authenticate and authorize users end-to-end](tutorial-auth-aad.md)

0 commit comments

Comments
 (0)