Skip to content

Commit d57c212

Browse files
Jak-MSJak-MS
committed
edit pass: v1-oauth2-on-behalf-of-flow
1 parent 60163ce commit d57c212

File tree

1 file changed

+33
-33
lines changed

1 file changed

+33
-33
lines changed

‎articles/active-directory/develop/v1-oauth2-on-behalf-of-flow.md

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Azure Active Directory service-to-service authentication using the OAuth2.0 On-Behalf-Of draft specification | Microsoft Docs
3-
description: This article describes how to use HTTP messages to implement service-to-service authentication using the OAuth2.0 On-Behalf-Of flow.
2+
title: Azure Active Directory service-to-service authentication that uses the OAuth2.0 On-Behalf-Of draft specification | Microsoft Docs
3+
description: This article describes how to use HTTP messages to implement service-to-service authentication with the OAuth2.0 On-Behalf-Of flow.
44
services: active-directory
55
documentationcenter: .net
66
author: navyasric
@@ -20,18 +20,18 @@ ms.reviewer: hirsin, nacanuma
2020
ms.custom: aaddev
2121
---
2222

23-
# Service-to-service calls using delegated user identity in the On-Behalf-Of flow
23+
# Service-to-service calls that use delegated user identity in the On-Behalf-Of flow
2424

2525
[!INCLUDE [active-directory-develop-applies-v1](../../../includes/active-directory-develop-applies-v1.md)]
2626

2727
The OAuth 2.0 On-Behalf-Of (OBO) flow enables an application that invokes a service or web API to pass user authentication to another service or web API. The OBO flow propagates the delegated user identity and permissions through the request chain. For the middle-tier service to make authenticated requests to the downstream service, it must secure an access token from Azure Active Directory (Azure AD) on behalf of the user.
2828

2929
> [!IMPORTANT]
30-
> As of May 2018, an `id_token` can't be used for the On-Behalf-Of flow. Single-page apps (SPAs) must pass an **access** token to a middle-tier confidential client to perform OBO flows. For more detail about the clients that can perform On-Behalf-Of calls, see [limitations](#client-limitations).
30+
> As of May 2018, an `id_token` can't be used for the On-Behalf-Of flow. Single-page apps (SPAs) must pass an access token to a middle-tier confidential client to perform OBO flows. For more detail about the clients that can perform On-Behalf-Of calls, see [limitations](#client-limitations).
3131
3232
## On-Behalf-Of flow diagram
3333

34-
The OBO flow starts after the user has been authenticated on an application using the [OAuth 2.0 authorization code grant flow](v1-protocols-oauth-code.md). At that point, the application has an access token (token A) with the user’s claims and consent to access the middle-tier web API (API A). Next, API A needs to make an authenticated request to the downstream web API (API B).
34+
The OBO flow starts after the user has been authenticated on an application that uses the [OAuth 2.0 authorization code grant flow](v1-protocols-oauth-code.md). At that point, the application has an access token (token A) with the user’s claims and consent to access the middle-tier web API (API A). Next, API A needs to make an authenticated request to the downstream web API (API B).
3535

3636
These steps constitute the On-Behalf-Of flow:
3737
![OAuth2.0 On-Behalf-Of Flow](./media/v1-oauth2-on-behalf-of-flow/active-directory-protocols-oauth-on-behalf-of-flow.png)
@@ -52,9 +52,9 @@ Register both the middle-tier service and the client application in Azure AD.
5252
### Register the middle-tier service
5353

5454
1. Sign in to the [Azure portal](https://portal.azure.com).
55-
1. On the top bar, select your account and look under the **Directory** list to choose an Active Directory tenant for your application.
55+
1. On the top bar, select your account and look under the **Directory** list to select an Active Directory tenant for your application.
5656
1. Select **More Services** on the left pane and choose **Azure Active Directory**.
57-
1. Select **App registrations** and choose **New application registration**.
57+
1. Select **App registrations** and then **New application registration**.
5858
1. Enter a friendly name for the application and select the application type.
5959
1. Depending upon the application type, set either the sign-on URL or the redirect URL to the base URL.
6060
1. Select **Create** to create the application.
@@ -64,30 +64,30 @@ Register both the middle-tier service and the client application in Azure AD.
6464
1. When you save this page, the Azure portal displays the key value. Copy and save the key value in a safe location.
6565

6666
> [!IMPORTANT]
67-
> You need the key to configure the application settings in your implementation. This key value is not displayed again nor retrievable by any other means. Record it as soon as it is visible in the Azure Portal.
67+
> You need the key to configure the application settings in your implementation. This key value is not displayed again, and it isn't retrievable by any other means. Record it as soon as it is visible in the Azure portal.
6868
6969
### Register the client application
7070

7171
1. Sign in to the [Azure portal](https://portal.azure.com).
72-
1. On the top bar, select your account and look under the **Directory** list to choose an Active Directory tenant for your application.
72+
1. On the top bar, select your account and look under the **Directory** list to select an Active Directory tenant for your application.
7373
1. Select **More Services** on the left pane and choose **Azure Active Directory**.
74-
1. Select **App registrations** and choose **New application registration**.
74+
1. Select **App registrations** and then **New application registration**.
7575
1. Enter a friendly name for the application and select the application type.
7676
1. Depending upon the application type, set either the sign-on URL or the redirect URL to the base URL.
7777
1. Select **Create** to create the application.
7878
1. Configure permissions for your application.
7979
1. In the Settings menu, choose the **Required permissions** section, and then select **Add** and **Select an API**.
80-
1. Type the name of the middle-tier service in the textbox.
81-
1. Choose **Select Permissions** and then select **Access service name**.
80+
1. Type the name of the middle-tier service in the text field.
81+
1. Choose **Select Permissions** and then select **Access service name**.
8282

8383
### Configure known client applications
8484

85-
In this scenario, the middle-tier service needs to obtain the user's consent to access the downstream API without a user interaction. The option to grant access to the downstream API must be presented upfront as part of the consent step during authentication.
85+
In this scenario, the middle-tier service needs to obtain the user's consent to access the downstream API without a user interaction. The option to grant access to the downstream API must be presented up front as part of the consent step during authentication.
8686

8787
Follow the steps below to explicitly bind the client app's registration in Azure AD with the middle-tier service's registration. This operation merges the consent required by both the client and middle-tier into a single dialog.
8888

8989
1. Go to the middle-tier service registration and select **Manifest** to open the manifest editor.
90-
1. Locate the `knownClientApplications` array property and add the Client ID of the client application as an element.
90+
1. Locate the `knownClientApplications` array property and add the client ID of the client application as an element.
9191
1. Save the manifest by selecting **Save**.
9292

9393
## Service-to-service access token request
@@ -106,11 +106,11 @@ When using a shared secret, a service-to-service access token request contains t
106106

107107
| Parameter | | Description |
108108
| --- | --- | --- |
109-
| grant_type |required | The type of the token request. Since an OBO request uses a JSON Web Token (JWT), the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
109+
| grant_type |required | The type of the token request. An OBO request uses a JSON Web Token (JWT) so the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
110110
| assertion |required | The value of the access token used in the request. |
111-
| client_id |required | The App ID assigned to the calling service during registration with Azure AD. To find the App ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
111+
| client_id |required | The app ID assigned to the calling service during registration with Azure AD. To find the app ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
112112
| client_secret |required | The key registered for the calling service in Azure AD. This value should have been noted at the time of registration. |
113-
| resource |required | The App ID URI of the receiving service (secured resource). To find the App ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
113+
| resource |required | The app ID URI of the receiving service (secured resource). To find the app ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
114114
| requested_token_use |required | Specifies how the request should be processed. In the On-Behalf-Of flow, the value must be **on_behalf_of**. |
115115
| scope |required | A space separated list of scopes for the token request. For OpenID Connect, the scope **openid** must be specified.|
116116

@@ -140,12 +140,12 @@ A service-to-service access token request with a certificate contains the follow
140140

141141
| Parameter | | Description |
142142
| --- | --- | --- |
143-
| grant_type |required | The type of the token request. Since an OBO request uses a JWT access token, the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
143+
| grant_type |required | The type of the token request. An OBO request uses a JWT access token so the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
144144
| assertion |required | The value of the token used in the request. |
145-
| client_id |required | The App ID assigned to the calling service during registration with Azure AD. To find the App ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
145+
| client_id |required | The app ID assigned to the calling service during registration with Azure AD. To find the app ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
146146
| client_assertion_type |required |The value must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
147147
| client_assertion |required | A JSON Web Token that you create and sign with the certificate you registered as credentials for your application. See [certificate credentials](active-directory-certificate-credentials.md) to learn about assertion format and about how to register your certificate.|
148-
| resource |required | The App ID URI of the receiving service (secured resource). To find the App ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
148+
| resource |required | The app ID URI of the receiving service (secured resource). To find the app ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
149149
| requested_token_use |required | Specifies how the request should be processed. In the On-Behalf-Of flow, the value must be **on_behalf_of**. |
150150
| scope |required | A space separated list of scopes for the token request. For OpenID Connect, the scope **openid** must be specified.|
151151

@@ -182,9 +182,9 @@ A success response is a JSON OAuth 2.0 response with the following parameters:
182182
| scope |The scope of access granted in the token. |
183183
| expires_in |The length of time the access token is valid (in seconds). |
184184
| expires_on |The time when the access token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. This value is used to determine the lifetime of cached tokens. |
185-
| resource |The App ID URI of the receiving service (secured resource). |
185+
| resource |The app ID URI of the receiving service (secured resource). |
186186
| access_token |The requested access token. The calling service can use this token to authenticate to the receiving service. |
187-
| id_token |The requested id token. The calling service can use this token to verify the user's identity and begin a session with the user. |
187+
| id_token |The requested ID token. The calling service can use this token to verify the user's identity and begin a session with the user. |
188188
| refresh_token |The refresh token for the requested access token. The calling service can use this token to request another access token after the current access token expires. |
189189

190190
### Success response example
@@ -208,7 +208,7 @@ The following example shows a success response to a request for an access token
208208

209209
### Error response example
210210

211-
The Azure AD token endpoint returns an error response when it tries to acquire an access token for a downstream API that is set with a conditional access policy (e.g., multi-factor authentication). The middle-tier service should surface this error to the client application so that the client application can provide the user interaction to satisfy the conditional access policy.
211+
The Azure AD token endpoint returns an error response when it tries to acquire an access token for a downstream API that is set with a conditional access policy (for example, multi-factor authentication). The middle-tier service should surface this error to the client application so that the client application can provide the user interaction to satisfy the conditional access policy.
212212

213213
```
214214
{
@@ -244,24 +244,24 @@ Some OAuth-based web services need to access other web service APIs that accept
244244
> [!TIP]
245245
> When you call a SAML-protected web service from a front-end web application, you can simply call the API and initiate a normal interactive authentication flow with the user's existing session. You only need to use an OBO flow when a service-to-service call requires a SAML token to provide user context.
246246
247-
### Obtain a SAML token using an OBO request with a shared secret
247+
### Obtain a SAML token by using an OBO request with a shared secret
248248

249249
A service-to-service request for a SAML assertion contains the following parameters:
250250

251251
| Parameter | | Description |
252252
| --- | --- | --- |
253-
| grant_type |required | The type of the token request. For a request using a JWT, the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
253+
| grant_type |required | The type of the token request. For a request that uses a JWT, the value must be **urn:ietf:params:oauth:grant-type:jwt-bearer**. |
254254
| assertion |required | The value of the access token used in the request.|
255-
| client_id |required | The App ID assigned to the calling service during registration with Azure AD. To find the App ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
255+
| client_id |required | The app ID assigned to the calling service during registration with Azure AD. To find the app ID in the Azure portal, select **Active Directory**, choose the directory, and then select the application name. |
256256
| client_secret |required | The key registered for the calling service in Azure AD. This value should have been noted at the time of registration. |
257-
| resource |required | The App ID URI of the receiving service (secured resource). This is the resource that will be the Audience of the SAML token. To find the App ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
257+
| resource |required | The app ID URI of the receiving service (secured resource). This is the resource that will be the Audience of the SAML token. To find the app ID URI in the Azure portal, select **Active Directory** and choose the directory. Select the application name, choose **All settings**, and then select **Properties**. |
258258
| requested_token_use |required | Specifies how the request should be processed. In the On-Behalf-Of flow, the value must be **on_behalf_of**. |
259259
| requested_token_type | required | Specifies the type of token requested. The value can be **urn:ietf:params:oauth:token-type:saml2** or **urn:ietf:params:oauth:token-type:saml1** depending on the requirements of the accessed resource. |
260260

261261
The response contains a SAML token encoded in UTF8 and Base64url.
262262

263-
- **_SubjectConfirmationData_ for a SAML assertion sourced from an OBO call**: If the target application requires a recipient value in **SubjectConfirmationData**, then the value must be a non-wildcard Reply URL in the resource application configuration.
264-
- **The _SubjectConfirmationData_ node**: The node can't contain an **InResponseTo** attribute since it's not part of a SAML response. The application receiving the SAML token must be able to accept the SAML assertion without an **InResponseTo** attribute.
263+
- **SubjectConfirmationData for a SAML assertion sourced from an OBO call**: If the target application requires a recipient value in **SubjectConfirmationData**, then the value must be a non-wildcard Reply URL in the resource application configuration.
264+
- **The SubjectConfirmationData node**: The node can't contain an **InResponseTo** attribute since it's not part of a SAML response. The application receiving the SAML token must be able to accept the SAML assertion without an **InResponseTo** attribute.
265265

266266
- **Consent**: Consent must have been granted to receive a SAML token containing user data on an OAuth flow. For information on permissions and obtaining administrator consent, see [Permissions and consent in the Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/azure/active-directory/develop/v1-permissions-and-consent).
267267

@@ -273,7 +273,7 @@ The response contains a SAML token encoded in UTF8 and Base64url.
273273
| scope |The scope of access granted in the token. |
274274
| expires_in |The length of time the access token is valid (in seconds). |
275275
| expires_on |The time when the access token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. This value is used to determine the lifetime of cached tokens. |
276-
| resource |The App ID URI of the receiving service (secured resource). |
276+
| resource |The app ID URI of the receiving service (secured resource). |
277277
| access_token |The parameter that returns the SAML assertion. |
278278
| refresh_token |The refresh token. The calling service can use this token to request another access token after the current SAML assertion expires. |
279279

@@ -282,17 +282,17 @@ The response contains a SAML token encoded in UTF8 and Base64url.
282282
- ext_expires_in: 0
283283
- expires_on: 1529627844
284284
- resource: `https://api.contoso.com`
285-
- access_token: < SAML assertion >
285+
- access_token: <SAML assertion>
286286
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
287-
- refresh_token: < Refresh token >
287+
- refresh_token: <Refresh token>
288288

289289
## Client limitations
290290

291291
Public clients with wildcard reply URLs can't use an `id_token` for OBO flows. However, a confidential client can still redeem **access** tokens acquired through the implicit grant flow even if the public client has a wildcard redirect URI registered.
292292

293293
## Next steps
294294

295-
Learn more about the OAuth 2.0 protocol and another way to perform service-to-service authentication using client credentials:
295+
Learn more about the OAuth 2.0 protocol and another way to perform service-to-service authentication that uses client credentials:
296296

297297
* [Service to service authentication using OAuth 2.0 client credentials grant in Azure AD](v1-oauth2-client-creds-grant-flow.md)
298298
* [OAuth 2.0 in Azure AD](v1-protocols-oauth-code.md)

0 commit comments

Comments
 (0)