OpenParable
Skip to content
← Back to skills

Msal Obo Flow

Development
msal-obo-flow

Msal 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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  1. Client calls web API with user access token in Authorization header
  2. Web API validates the incoming token
  3. Web API exchanges user token for new token scoped for downstream API
  4. 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:

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

Explain the Flow

  1. Token Reception: Web API receives user's access token from client
  2. Token Validation: Web API validates token signature and claims
  3. Token Exchange: Web API calls AcquireTokenOnBehalfOf() with user's token + client credentials
  4. Scoped Token: AAD returns new token scoped for downstream API
  5. 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)