Instructions for

Validate Access Tokens

This guide explains how to verify a token's signature, manage key rotation, and how to use a refresh token to get a new access token.

Learning outcomes

Validate access tokens.

About access token validation

If you are building a modern app or API, you likely 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, which your application can then use. It is important that your application only uses the access token to grant access, and not the ID token. For more information about this, see the Access Tokens vs ID Tokens section below.

After the signed tokens are issued to the end users, they can be passed to your application 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 application with a public key that can be used.

If you'd like to jump straight to the local validation steps: What to Check When Validating an Access Token
If you'd like to see how to validate a token directly with Okta: Validating A Token Remotely With Okta
If you want to see specifically how to accomplish this in your language of choice: Okta Libraries to Help You Verify Access Tokens

Access Tokens vs ID Tokens

As mentioned above, it is important that the resource server (your server-side application) accepts only the access token from a client. This is because access tokens are intended for authorizing access to a resource.

ID Tokens, on the other hand, are intended for authentication. They provide information about the resource owner, to allow you verify that they are who they say they are. Authentication is the concern of the clients. Because of this, when a client makes an authentication request, the ID Token that is 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 and parse your Okta JSON Web Keys (JWK), which should be checked periodically and cached by your application.
Decode the access token, which is in JSON Web Token format
Verify the signature used to sign the access token
Verify the claims found inside the access token

Retrieve The JSON Web Keys

The JSON Web Keys (JWK) need to be retrieved from your Okta authorization server, though your application should have them cached. See Best practices. Specifically, your authorization server's Metadata endpoint contains the jwks_uri, which you can use to get the JWK.

For more information about retrieving this metadata, see Retrieve Authorization Server Metadata.

Decoding and Validating the Access Token

You will have to 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, the Microsoft OpenID Connect JWT libraries may be used for this purpose.

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

Get the signing keys

Okta signs JWTs using asymmetric encryption (RS256) (opens new window), and publishes the public signing keys in a JWKS (JSON Web Key Set) as part of the OAuth 2.0 and OpenID Connect discovery documents. The signing keys are rotated on a regular basis. 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 will download and parse the discovery document to get the key set. You can use it in conjunction with the ConfigurationManager class, which will handle 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());

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

Validate a token

The JwtSecurityTokenHandler class in the System.IdentityModel.Tokens.Jwt (opens new window) package will handle 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, and the issuer and configurationManager 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 will return an instance of JwtSecurityToken if the token is valid, or null if it is 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.

Additional validation for access tokens

If you are validating access tokens, you should verify that the aud (audience) claim equals the audience that is configured for your authorization server in the Okta 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 which was used to sign the token. You'll have to 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.");
}

Additional validation for ID tokens

When validating an ID token, you should verify that the aud (Audience) claim equals the Client ID of the current application.

Add this to the validation parameters:

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

// 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. You can 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}");
}

Validating A Token Remotely With Okta

Alternatively, you can also validate an access or refresh Token using the Token Introspection endpoint: Introspection Request. This endpoint takes your token as a URL query parameter and returns back a simple JSON response with a boolean active property.

This incurs a network request which is slower to do verification, but can be used when you want to guarantee that the access token hasn't been revoked.

On this page