Token Exchange Types

Post by: syed hussain in All

Summary

Token exchange is the process of exchanging one type of security token for another. It is a crucial aspect of authorization in modern web-based applications and services. There are several types of token exchange protocols, including OAuth, SAML, JWT, and Kerberos.

In our example, we’ll look at how to perform a token exchange using C# and the OAuth 2.0 protocol. We’ll use the HttpClient class to send a request to the Azure AD token endpoint and pass in the client ID, client secret, grant type, assertion (access token), and target resource as parameters in the request body. Once we received the response from the token endpoint, we parsed the JSON content and extracted the access token.

It’s worth noting that token exchange is an important part of securing web-based applications and services, but it’s just one piece of the puzzle. Developers need to carefully consider the security implications of their token exchange implementation, as well as the overall architecture of their application or service. By following best practices and using established security protocols, developers can build robust and secure applications that protect users and their data.

Token Types

  • OAuth 2.0 Access Token – Used for authorisation and access to Azure services.
  • OAuth 2.0 Refresh Token – Used to obtain a new access token without re-authentication.
  • ID Token (OpenID Connect) – Contains identity information about the user, used for authentication.
  • SAML 2.0 Token – Used for Single Sign-On (SSO) with Azure Active Directory.
  • JWT (JSON Web Token) – Used for securely representing claims between parties, commonly used in many Azure services.
  • Kerberos Token – Used in hybrid environments with Azure AD and on-premises Active Directory.
  • Managed Identity Token – Issued by Azure for services using Managed Identities to authenticate.
  • Client Assertion Token – A JWT used in OAuth 2.0 client credentials flow.
  • API Key – Used in Azure API Management for access control.

The Bearer Token and OAuth Access Token are essentially the same, and the Client Assertion Token is a specific form of a JWT. So they’ve been grouped accordingly.

Token Exchange Types

OAuth 2.0

OAuth token exchange: OAuth is a popular protocol used for authorization and token exchange in web-based applications. With OAuth, a user can grant permission to an application to access their resources on a service provider, and the application receives an access token in exchange. The access token can be exchanged for another token, such as a refresh token, or a different type of access token with different scopes or permissions.

sequenceDiagram
    participant User
    participant Application
    participant AuthorizationServer
    participant ResourceServer
    
    User ->> Application: Grants Permission
    Application ->> AuthorizationServer: Requests Authorization Code
    AuthorizationServer ->> Application: Returns Authorization Code
    Application ->> AuthorizationServer: Exchanges Authorization Code for Access Token
    AuthorizationServer ->> Application: Returns Access Token
    Application ->> ResourceServer: Sends Access Token to Access Resources
    ResourceServer ->> Application: Grants Access
    Application ->> AuthorizationServer: Exchanges Access Token for Refresh Token or New Access Token

SAML

SAML token exchange: Security Assertion Markup Language (SAML) is a protocol used for exchanging security tokens between parties. With SAML, a user can authenticate to a service provider using a SAML token, and the service provider can exchange that token for another token, such as a SAML assertion or a different type of security token.

    sequenceDiagram
    participant User
    participant ServiceProvider
    participant IdentityProvider
    
    User ->> ServiceProvider: Requests access to service
    ServiceProvider ->> IdentityProvider: Sends Authentication Request (SAML Request)
    IdentityProvider ->> User: Requests Authentication
    User ->> IdentityProvider: Provides Credentials
    IdentityProvider ->> ServiceProvider: Sends SAML Assertion (SAML Token)
    ServiceProvider ->> User: Grants Access to the Service
    ServiceProvider ->> IdentityProvider: Exchanges SAML Assertion for Another Token (e.g., SAML Assertion or Security Token)

    JWT token exchange

    JSON Web Tokens (JWT) are a popular format for representing claims securely between parties. With JWT, a user can authenticate to a service provider using a JWT token, and the service provider can exchange that token for another token, such as an OAuth access token or a SAML assertion.

    sequenceDiagram
    participant User
    participant Application
    participant AuthorizationServer
    participant ResourceServer
    
    User ->> Application: Logs in/Requests Access
    Application ->> AuthorizationServer: Sends credentials (or login request)
    AuthorizationServer ->> Application: Returns JWT Token
    Application ->> ResourceServer: Sends JWT Token for resource access
    ResourceServer ->> Application: Grants Access to Resources
    Application ->> AuthorizationServer: Exchanges JWT Token for OAuth Access Token or SAML Assertion (if needed)

    Example

    Here’s an example of how to perform a token exchange using C# and the OAuth 2.0 protocol:

    using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public async Task<string> ExchangeToken(string accessToken, string targetResource)
{
    string tokenEndpoint = "https://login.microsoftonline.com/{tenant-id}/oauth2/token"; // replace {tenant-id} with your Azure AD tenant ID
    string clientId = "your-client-id"; // replace with your Azure AD app client ID
    string clientSecret = "your-client-secret"; // replace with your Azure AD app client secret

    HttpClient client = new HttpClient();

    // set the request parameters
    var content = new FormUrlEncodedContent(new[]
    {
        new KeyValuePair<string, string>("client_id", clientId),
        new KeyValuePair<string, string>("client_secret", clientSecret),
        new KeyValuePair<string, string>("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"),
        new KeyValuePair<string, string>("assertion", accessToken),
        new KeyValuePair<string, string>("resource", targetResource)
    });

    // send the request to the token endpoint
    HttpResponseMessage response = await client.PostAsync(tokenEndpoint, content);

    // read the response and extract the access token
    string responseContent = await response.Content.ReadAsStringAsync();
    var token = JObject.Parse(responseContent)["access_token"].ToString();

    return token;
}

    In this example, we use the HttpClient class to send a request to the Azure AD token endpoint. We pass in the client ID, client secret, grant type, assertion (access token), and target resource as parameters in the request body.

    Once we receive the response from the token endpoint, we parse the JSON content and extract the access token. Finally, we return the access token as a string.

    Note that this example assumes that you have already obtained an access token using some other means, such as using the Azure AD authentication libraries. The accessToken parameter should contain the access token that you want to exchange for a different type of token. The targetResource parameter should contain the URI of the resource that the new token will be used to access.

    Tags:
    05 May 2023
    0