Msal Obo Flow
Developmentmsal-obo-flowMsal Obo Flow is an Agent Skill for development published in the AzureAD/microsoft-authentication-library-for-dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
On-Behalf-Of (OBO) Flow for web APIs to call downstream APIs while preserving user identity in MSAL.NET
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/HEAD/.github/skills/msal-obo-flow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/msal-obo-flow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
On-Behalf-Of (OBO) Flow Skill
Overview
OBO (On-Behalf-Of) Flow enables a web API to act on behalf of an authenticated user to access downstream APIs. The web API receives a user token, validates it, and exchanges it for a token to call another API while maintaining the user's identity and context.
When to Use
- Web APIs receiving user tokens from clients
- Need to access downstream APIs on behalf of authenticated users
- Multi-tier applications with user context propagation
- User authorization context must flow through service chain
Flow Steps
- Client calls web API with user access token in Authorization header
- Web API validates the incoming token
- Web API exchanges user token for new token scoped for downstream API
- Web API calls downstream API on behalf of user
Important: Token Types
⚠️ Always pass an access token, NOT an ID token to AcquireTokenOnBehalfOf()
ID tokens are for authentication; access tokens are for authorization and API access.
Agent Actions
Generate Code Snippet
Agent can show code for each credential type:
- Standard Certificate: with-certificate.cs
- Certificate with SNI: with-certificate-sni.cs
- Federated Identity Credentials: with-federated-identity-credentials.cs
Setup Guidance
Reference appropriate credential setup:
Example: Web API with Certificate
// In web API controller receiving user token
[HttpGet("api/data")]
public async Task<IActionResult> GetData()
{
// Extract access token from Authorization header
var authHeader = Request.Headers["Authorization"].ToString();
var userToken = authHeader.Replace("Bearer ", "");
// See: with-certificate.cs for credential setup
var app = ConfidentialClientApplicationBuilder
.Create(clientId)
.WithCertificate(cert)
.WithAuthority($"https://login.microsoftonline.com/{tenantId}/v2.0")
.Build();
// Create UserAssertion with access token (not ID token)
var userAssertion = new UserAssertion(userToken, "urn:ietf:params:oauth:grant-type:jwt-bearer");
var result = await app.AcquireTokenOnBehalfOf(
new[] { "scope-uri" },
userAssertion)
.ExecuteAsync();
// Use result.AccessToken to call downstream API
return Ok(result.AccessToken);
}
Error Resolution
Refer to Troubleshooting Guide
Common OBO errors:
MsalUiRequiredException: MFA or conditional access required—requires client re-authentication- Invalid token: Verify access token (not ID token) is passed
Best Practices
- Use Token Caching Strategies for optimal session-based token caching
- Implement Error Handling Patterns
- Always validate incoming token before using in OBO
- Extract
tidclaim from user token for guest user scenarios—use tenant-specific authority, not /common - For multi-instance deployments and advanced caching, see Token cache serialization documentation
Explain the Flow
- Token Reception: Web API receives user's access token from client
- Token Validation: Web API validates token signature and claims
- Token Exchange: Web API calls
AcquireTokenOnBehalfOf()with user's token + client credentials - Scoped Token: AAD returns new token scoped for downstream API
- Downstream Call: Web API calls downstream service with new token
Decision Help
Choose OBO if:
- Building multi-tier web API architecture
- Receiving user tokens in web API
- Need to maintain user context through service chain
- Authenticating with downstream APIs on behalf of user
Avoid if:
- Direct client-to-API communication (use Auth Code Flow)
- Service-to-service with no user context (use Client Credentials)