Microsoft Azure Active Directory supports an OAuth2 protocol extension called On-Behalf-Of flow (OBO flow). This is documented at both the Microsoft Identity Platform V1 and V2 endpoint. The OBO flow is used in the following scenario. Both Web API 1 and Web API 2 are protected by Azure AD.
- A client application (could be a SPA app, a front-end Web Application, or a native application) signs a user into Azure AD and request a delegated access token for Web API 1
- Client application then calls Web API 1 with the issued access token
- Web API 1 in turn needs to call a downstream Web API 2 so it uses its access token (in step 2 above) to request an access token for Web API 2. What happens in this step is that Web API 1 uses the OBO flow to exchange its access token for another resource’s access token. The exchanged token is still issued on behalf of the original sign in user and it has delegated permission.
- Web API 1 uses the new access token to call Web API 2
Let’s look at the parameters used in an OBO flow at the V1 endpoint below. I want to call out a few highlighted parameters as their significance will become more obvious a little bit later.
this is the access token issued in step 2 above
application id of Web API 1
this is Application ID URI or Application ID of Web API 2
Let’s look at an OBO end to end traffic in Fiddler:
Frame 1 – 14 below shows the user navigates to the web site and is redirected to Azure AD to log in. Frame 15 is the request to the token endpoint to get an access token for Web API 1
Hover over image to enlarge
In this example Web API 2 is Microsoft Graph. In frame 19 below Web API 1 uses an OBO flow to request a token for Microsoft Graph. It uses the access token received in frame 15 as the assertion parameter.
Hover over image to enlarge
It is extremely important to use the correct parameter in the OBO flow. Note that the OBO parameters client_id and the assertion (access token) are for the calling application (Web API 1) in this token exchange request.
Common pitfall customers run into when using the OBO flow
I have seen a few AADSTS error returned for this flow when either the client_id or the assertion parameters used are not for the calling application (Web API 1). Below are a few examples:
HTTP 400 error: AADSTS500131: Assertion audience does not match the Client app presenting the assertion. The audience in the assertion was ‘00000002-0000-0000-c000-000000000000’ and the expected audience is …
Root cause: The access token used in the assertion is for a different application / resource instead of for the calling app Web API 1. The GUID in this error is an Azure AD Graph resource.
HTTP 400 error: AADSTS50013: Assertion failed signature validation. [Reason – The provided signature value did not match the expected signature value., Thumbprint of key used by client:…
Root cause: The access token used in the assertion is for Microsoft Graph resource (https://graph.microsoft.com)
HTTP 400 error: AADSTS50013: Assertion failed signature validation. [Reason – The key was not found., Thumbprint of key used by client: ‘B25930C…..
Root cause: Web API 1 is a SAML Application (check the Enterprise Application blade to see if Single sign-on is enabled and there is a SAML signing Certificate attached).
HTTP 500 error: AADSTS50000: There was an error issuing a token.
Root cause: the client id used is either not valid or does not exist in the tenant.
How can I diagnose this issue?
- Take a Fiddler trace to see what the parameters used are.
Use https://jwt.ms to decode the access token assertion and look at the “aud” (audience) claim to see if it’s for the calling web API 1
What if my Web API 2 is SAML Application?
If the downstream API App can only consume SAML token (instead of jwt token), you can certainly use the OBO flow to exchange a JWT token for the SAML token using the following parameters (see https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-on-behalf-of-flow for more info). The key is in the parameter requested_token_type. The allowed values are
urn:ietf:params:oauth:token-type:saml2 – SAML 2.0 token
urn:ietf:params:oauth:token-type:saml1 – SAML 1.1 token
At the time of this writing, this JWT – SAML token exchange OBO flow is only available in the V1 endpoint.
Note: Azure AD returns the SAML token encoded in UTF8 and Base64URL as noted in the documentation
What about Azure AD B2C?
The OBO flow is currently not supported in Azure AD B2C per Application types that can be used in Active Directory B2C
Drop me a comment if you find this useful or any other important information I should add.
Update 8/22 – added one more condition for error AADSTS50013 due to SAML App
32 Thoughts to “Understanding Azure AD’s On-Behalf-Of flow (aka OBO flow)”
Great article, I am trying to get a saml token from a jwt token but when i hit the endpoint to get the saml token i am receiving the following error:
“error_description”: “AADSTS50013: Assertion failed signature validation. [Reason – The key was not found., Thumbprint of key used by client: ‘CAC25D36924A3AD5B1D66E884AA55B5F04526F1A’]\r\nTrace ID: 47644c95-3bd8-46c3-b320-23fbe9432c00\r\nCorrelation ID: 5e83afde-3791-4d87-bce2-dfe5dc5d4ee6\r\nTimestamp: 2019-08-21 00:33:27Z”,
“timestamp”: “2019-08-21 00:33:27Z”,
I see you did not mention about certificates, Am I missing something?
My downstream api is configured with saml sso, i do not know if that could be the issue.
Check your Web API 1 (the one that requests an access token for web API 2 using OBO flow) to make sure it’s an OAuth2 application and not a SAML application. Is Web API 1 created in App Registration blade or Enterprise Application blade? If created in the Enterprise Application blade then there is a good chance it’s a SAML application (The single Sign On blade is enabled and there is a SAML certificate attached). In general we don’t recommend the same application being used as a SAML app and an OAuth2 app. That can create problem due to different maintenance of signing certificates. Please open a support ticket with us if this does not help. Your downstream web API 2 configured with SAML SSO should be fine.
Thanks a lot Bac, indeed I had created the Web API 1 application using the Enterprise blade, I thought it was right because the single sign on were disabled but after creating it through app registration blade it worked.
If my two applications were SAML can I use OBO flow the same way or I need to have a OAuth2 token to start with? Is it possible to bypass the problems of signing certificates if my WEB API 1 were SAML and OAuth2 at the same time?
Thanks again 🙂
Unfortunately, web API 1 has to be an OAuth2 application for this to work. Your Web API 2 can be a SAML App. Thanks for bringing this issue to my attention. I updated the post to include this scenario now.
I received a saml token to my downstream API but I tried to validate it by just decoding and inflating the xml and it is not a valid saml token, maybe is it encoded in a different way?
“resource”: “my resource”,
Your access token is a Base 64-encoded SAML token. Just run it through any Base64 decoder and you should see the XML string.
Thanks Bac for spending your time helping me! I already decoded and inflated the SAML token above, but it seems to be encoded/encrypted as follows:
��K��\��Y\���Yۘ]\�H[��H������˝�˛ܙ�̌�K�[�Y�ȏ��YۙY[��Ϗ�[�ۚX�[^�][ۓY]�[�ܚ]OH������˝�˛ܙ�̌K�L�[Y^�X�M�ȋ��6�v�GW&T�WF��B�v�&�F���&�GG���wwr�s2��&r�#�B�� …. (so on)
It is always the first child node that is being encrypted, I have tried many times and all my received SAML tokens are this way, do you have an ideia what this could be?
The Base64 decoder says: The input is not a valid Base-64 string as it contains a non-base 64 character, more than two padding characters, or an illegal character among the padding characters.
I used Fiddler’s TextWizard feature (Transform = From Base64) and the tool at https://www.freeformatter.com/base64-encoder.html Both decode your token just fine.
Hi Bac, I was being fooled by the others decoder64 sites I visited, I had tried by example these two sites: https://www.base64decode.org/ https://codebeautify.org/base64-decode and both of them gave me these wrong results but indeed in Fiddler it worked.
Just to reminder someone that is trying to do the same thing, the SAML token that is returned is an Assertion, it does not contain the SAML Response tag, so if your downstream API is expecting this tag you must decode the SAML token and wrap it with the SAML response tag and its status tag, after that you encode in base64 again and it is ready to be used.
Thanks for your help. 🙂
For those who are trying to decode the SAML token response:
About the decoding code, most of the tools to decode base64 follows the RFC 4648 (previously, RFC 3548; standard) but there is no agreement about some encondig characters, more specifically the 62nd (+) and 63rd (/), the response SAML token from the OBO flow returns a base64url even if the data comes from the request’s body, this way the (+) character is replaced by (-) and etc…
Doing this in C# code won’t work: byte data = Convert.FromBase64(customBase64);
The correct way is to use the HttpServerUtility.UrlTokenDecode method, it expects that at the end of the data it contains the number of paddings.
The right code:
if (base64String.Length % 4 != 0) base64String += (4 – base64String.Length % 4);
else base64String += 0;
var data = Encoding.UTF8.GetString(HttpServerUtility.UrlTokenDecode(base64String));
Thanks for sharing Marcio
Hi, We are making an application using Azure Bot Service. Bot service internally calls one of our Web Service to get data based on query. We can consider Bot service as service1 and our Web Service as service2. After we get token from service1 we use that token as assertion to get bearer token from service2 by providing all required input parameters. We are getting error “AADSTS50013: Assertion failed signature validation. [Reason – The provided signature value did not match the expected signature value., Thumbprint of key used by client:…” and we cannot move forward. Can you please suggest what may be point of mistake?
your error is listed above. Make sure you are using the correct access token for web service 1. I would suggest examining the access token using https://jwt.ms to verify the token used by service 1 in the OBO flow is meant for service 1 and not for another resource app.
Hi Bac Hoang,
Does AAD support SAML Enhanced Client or Proxy Profile? I am able to get the SAML Assertion using OBO flow however I’m not sure how to wrap that up in a SAML Response. Wondered if I should use ECP instead. Thanks!
At the time of this writing, this JWT – SAML token exchange OBO flow is only available in the V1 endpoint.
Can seem to get this to work for V2.0 Oauth enpoint. Do you know if that should work?
As far as I know, the JWT – SAML token exchange functionality is only available in the V1 endpoint.
Hi, many thanks for this post. I’m working on an OBO flow but seem to be facing an issue (likely myself) with the aud claim in the originating service’s access token which is being sent to azure in the on_behalf_of POST request. I’m using the v1 endpoint.
I have configured the aud claim as guid within the access token claim but it’s still coming through with a default(?) value of 00000002-0000-0000-c000-000000000000. Even before adding the claim, I was getting this value which seems to contradict the docs?
Have I misunderstood how to configure the OBO flow? I am getting the AADSTS500131 error. I’m led to believe I’m attempting the correct fix as the error message tells me the aud claim should equal the value of the client_id.
Any help is greatly appreciated!
That GUID is for Azure Active Directory Graph. Make sure you specify the correct resource when asking for your web API Access Token. If you still need help, please open a support case with us
I have dameon app need to send messages to team cannel, but currently application type doesn’t have permisson to send messages to channel.. is it possible to achive this using OBO flow. i have two apps registered one is for dameon and web api with exposed api.. where i can will authenticate to web api using client credentials from dameon app and use that assertion token to call the graph api with web api credentails..
I am getting below error : ‘error’: ‘unauthorized_client’, ‘error_description’: “AADSTS7000114: Application ‘xxxxxxxxxxx’ is not allowed to make application on-behalf-of calls’
On Behalf Of (OBO) flow is only applicable for delegated permission where there is an actual user signing in. This does not work for application permission scenario where you are authenticating with a client id and secret.
Thanks, could you please let me know how can i post messages to team channels form application. webhook or card connectors is not a option as channels are created dynamically from application
And there is an implemetation here using dameon app used to obo flow
That discussion does not refer to using client credentials grant flow to get a token and then subsequently use that token in the OBO flow. There is a user context discussed there. Regarding your questions about Teams messages, it’s best if you can open a support case for the right team to assist you with.
Thank you for the response
Using API gateway in front of back-end services is a typical approach used in a microservices architecture. OBO is a good way to implement it but as we know it this flow is still not supported in Azure AD B2C. Could you please suggest how we should address it?
For API Gateway we are using lightweight Ocelot Gateway
Yes I believe your understanding is correct. OBO flow is currently not supported for Azure AD B2C
Thank you for sharing, I’m just getting started with the OBO samples on Github, how about some example code of calling APIs other than Graph? like Azure DevOps, etc.?
The code is essentially the same. Instead of using Microsoft Graph scope, you can use Azure DevOps scope.
Thanks for this great post. I was wondering, do you know if the second request of an access token in the flow (the one by Web API 1 to access Web API 2) get logged in any Azure Active Directory sign in logs?
Interesing…I am not sure. If you don’t find it in the sign-ins blade in the portal then perhaps it’s not logged. That 2nd request is not really a sign in request. It’s a token exchange request. Perhaps you can log a feedback item for a feature request here: https://feedback.azure.com/d365community/forum/22920db1-ad25-ec11-b6e6-000d3a4f0789