Instructions for

Validate Access Tokens

This guide explains why access token validation is important and how to validate and decode the access token.

Learning outcomes

Understand token validation.
Understand what to check when validating tokens.
Decode access tokens.
Validate access tokens remotely.

About access token validation

If you're building a modern app or API, you want to know if your end user is authenticated. This is important to give context or to protect APIs from unauthenticated users. You can use Okta to authenticate your end users and issue them signed access and ID tokens. Your app can then use these tokens. It's important that your app uses only the access token to grant access, and not the ID token. See Access tokens vs ID tokens.

After signed tokens are issued to end users, they can be passed to your app for validation. There are two ways to verify a token: locally or remotely with Okta. The token is signed with a JSON Web Key (JWK) using the RS256 algorithm. To validate the signature, Okta provides your app with a public key that you can use.

To jump straight to the local validation steps: What to check when validating an access token
To see how to validate a token directly with Okta: Validate a token remotely with Okta

Note: Okta is the only app that should consume or validate access tokens from the org authorization server. Org authorization servers have the following issuer format: https://{yourOktaOrg}. Consider these access tokens as opaque strings because their content is subject to change at any time. Therefore, any attempts by your app to validate the tokens may not work in the future.

Access tokens vs ID tokens

Access tokens are intended for authorizing access to a resource. It's important that the resource server (your server-side app) accepts only an access token from a client.

ID tokens, on the other hand, are intended for authentication. They provide information about the resource owner so that you can verify that they're who they say they are. Authentication is important to clients. Because of this, when a client makes an authentication request, the ID token that's returned contains the client_id in the ID token's aud claim.

What to check when validating an access token

The high-level overview of validating an access token looks like this:

Retrieve your Okta JSON Web Keys (JWK) (opens new window), which your app should check periodically and cache.
Decode the access token, which is in JSON Web Token (JWT) (opens new window) format.
Verify the signature used to sign the access token.
Verify the claims found inside the access token.

Retrieve the JSON Web Keys

Okta signs JWTs using asymmetric encryption (RS256) (opens new window). Okta publishes the public signing keys in a JSON Web Key Set (JWKS) as part of the OAuth 2.0 and OpenID Connect discovery documents. The signing keys are rotated regularly.

The first step to verify a signed JWT is to retrieve the current signing keys.

The OpenIdConnectConfigurationRetriever class in the Microsoft.IdentityModel.Protocols.OpenIdConnect (opens new window) package downloads and parses the discovery document to get the key set. Use it with the ConfigurationManager class, which handles caching the response and refreshing it regularly:

// Replace with your authorization server URL:
var issuer = "https://${yourOktaDomain}/oauth2/default";

var configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
    issuer + "/.well-known/oauth-authorization-server",
    new OpenIdConnectConfigurationRetriever(),
    new HttpDocumentRetriever());

After you've instantiated the configurationManager, keep it around as a singleton. You only need to set it up once.

Decode and validate the access token

Decode the access token, which is in JWT format. This involves the following steps:

Verify the token signature.
Verify the claims.

Although Okta doesn't provide a .Net library for JWT validation, you can use the Microsoft OpenID Connect JWT libraries for this purpose.

For more details about the code described here, see the .NET JWT Validation Guide.

Validate a token

The JwtSecurityTokenHandler class in the System.IdentityModel.Tokens.Jwt (opens new window) package handles the low-level details of validating a JWT.

You can write a method that takes the token, the issuer, and the configurationManager you created. The method is async because the configurationManager may need to make an HTTP call to get the signing keys (if they aren't already cached):

private static async Task<JwtSecurityToken> ValidateToken(
    string token,
    string issuer,
    IConfigurationManager<OpenIdConnectConfiguration> configurationManager,
    CancellationToken ct = default(CancellationToken))
{
    if (string.IsNullOrEmpty(token)) throw new ArgumentNullException(nameof(token));
    if (string.IsNullOrEmpty(issuer)) throw new ArgumentNullException(nameof(issuer));

    var discoveryDocument = await configurationManager.GetConfigurationAsync(ct);
    var signingKeys = discoveryDocument.SigningKeys;

    var validationParameters = new TokenValidationParameters
    {
        RequireExpirationTime = true,
        RequireSignedTokens = true,
        ValidateIssuer = true,
        ValidIssuer = issuer,
        ValidateIssuerSigningKey = true,
        IssuerSigningKeys = signingKeys,
        ValidateLifetime = true,
        // Allow for some drift in server time
        // (a lower value is better; we recommend two minutes or less)
        ClockSkew = TimeSpan.FromMinutes(2),
        // See additional validation for aud below
        ValidateAudience = false,
    };

    try
    {
        var principal = new JwtSecurityTokenHandler()
            .ValidateToken(token, validationParameters, out var rawValidatedToken);

        return (JwtSecurityToken)rawValidatedToken;
    }
    catch (SecurityTokenValidationException)
    {
        // Logging, etc.

        return null;
    }
}

To use the method, pass it a token, the issuer, and configurationManager that you declared earlier:

var accessToken = "eyJh...";

var validatedToken = await ValidateToken(accessToken, issuer, configurationManager);

if (validatedToken == null)
{
    Console.WriteLine("Invalid token");
}
else
{
    // Additional validation...
    Console.WriteLine("Token is valid!");
}

This method returns an instance of JwtSecurityToken if the token is valid or null if it’s invalid. Returning JwtSecurityToken makes it possible to retrieve claims from the token later.

Depending on your application, you could change this method to return a boolean, log specific exceptions like SecurityTokenExpiredException with a message, or handle validation failures in some other way.

More validation for access tokens

If you’re validating access tokens, you should verify that the aud (audience) claim equals the audience that is configured for your authorization server in the Admin Console.

For example, if your authorization server audience is set to MyAwesomeApi, add this to the validation parameters:

ValidateAudience = true,
ValidAudience = "MyAwesomeApi",

You also must verify that the alg claim matches the expected algorithm that was used to sign the token. Perform this check after the ValidateToken method returns a validated token:

// Validate alg
var validatedToken = await ValidateToken(accessToken, issuer, configurationManager);
var expectedAlg = SecurityAlgorithms.RsaSha256; //Okta uses RS256

if (validatedToken.Header?.Alg == null || validatedToken.Header?.Alg != expectedAlg)
{
    throw new SecurityTokenValidationException("The alg must be RS256.");
}

More validation for ID tokens

When validating an ID token, you should verify that the aud (audience) claim equals the client ID of the current app.

Add this to the validation parameters:

ValidateAudience = true,
ValidAudience = "xyz123", // This Application's Client ID

You also must verify that the alg claim matches the expected algorithm that was used to sign the token. Perform this check after the ValidateToken method returns a validated token:

// Validate alg
var validatedToken = await ValidateToken(idToken, issuer, configurationManager);
var expectedAlg = SecurityAlgorithms.RsaSha256; //Okta uses RS256

if (validatedToken.Header?.Alg == null || validatedToken.Header?.Alg != expectedAlg)
{
    throw new SecurityTokenValidationException("The alg must be RS256.");
}

If you specified a nonce during the initial code exchange when your application retrieved the ID token, you should verify that the nonce matches:

var validatedToken = await ValidateToken(idToken, issuer, configurationManager);

// Validate nonce
var expectedNonce = "foobar"; // Retrieve this from a saved cookie or other mechanism
var nonceMatches = validatedToken.Payload.TryGetValue("nonce", out var rawNonce)
    && rawNonce.ToString() == expectedNonce;

if (!nonceMatches)
{
    throw new SecurityTokenValidationException("The nonce was invalid.");
}

Decode token claims

The sample ValidateToken method above both validates a token and decodes its claims. Use the returned JwtSecurityToken object to inspect the claims in the token.

For example, you can get the sub (subject) claim with the Subject property:

Console.WriteLine("Token subject: {validatedToken.Subject}");

You can access more claims with the Payload property or loop over the entire Claims collection:

Console.WriteLine("All claims:");

foreach (var claim in validatedToken.Claims)
{
    Console.WriteLine("{claim.Type}\t{claim.Value}");
}

Validate a token remotely with Okta

Alternatively, you can validate an access or refresh token using the Token Introspection endpoint: Introspection request (opens new window). This endpoint takes your token as a URL query parameter and returns a simple JSON response with a Boolean active property.

This involves a network request that is slower for performing validation. But, you can use it when you want to guarantee that the access token hasn't been revoked.

On this page