Troubleshooting OAuth 2.0 tokens

Created by Steve Place, Modified on Mon, Feb 24 at 6:36 PM by Steve Place

This page is a companion to our OAuth 2.0 Integration docs page.

curl your access token endpoint and decode the access token claim.

For example, suppose your token issuer was Microsoft Entra ID and your jwt.yaml file looked like this:

https://login.microsoftonline.com/{tenant_id}/v2.0:
  audience: {client_id}
  usernameField: preferred_username
  autoCreateUsers: True
  rolesClaimPath: roles
  algorithms:
    RS256:
      keyUrl:
        https://login.microsoftonline.com/{tenant_id}/discovery/keys?appid={client_id}

You would curl the endpoint like this:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "scope=https://graph.microsoft.com/.default" \
  -d "grant_type=client_credentials" \
  "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"

If successful, you'll receive a response like this:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb..."
}

where eyJ0eXAiOiJKV1QiLCJhb... is the token. You can decode your token at a site like jwt.io (more on this below).

Based on the above configuration, the following claims should be present in the token:

iss: https://login.microsoftonline.com/{tenant_id}/v2.0
aud: {client_id}
preferred_username: <some-username>
- If this isn’t included, you may need to request the profile scope when acquiring the access token from Azure. (See more here.)
roles: an array of strings representing Stardog roles that exist on the Stardog server (e.g. [ "reader", "writer", "creator", "somerole"]). This claim is populated via the “App Roles” for the user. (See more here.)

The output of your decoded token will look something like this:

{
  "aud": "{client_id}",
  "iss": "https://login.microsoftonline.com/{tenant_id}/v2.0",
  "iat": 1740409037,
  "nbf": 1740409037,
  "exp": 1740414123,
  "aio": "{authentication_token}",
  "azp": "{client_id}",
  "azpacr": "1",
  "name": "{user_name}",
  "oid": "{user_object_id}",
  "preferred_username": "{user_email}",
  "rh": "{refresh_token_hash}",
  "roles": [
    "creator"
  ],
  "scp": "User.Read",
  "sid": "{session_id}",
  "sub": "{subject_identifier}",
  "tid": "{tenant_id}",
  "uti": "{unique_token_id}",
  "ver": "2.0"
}

Compare this to what you have in jwt.yaml and correct any mismatches.