OpenID Connect & OAuth 2.0

Okta is a standards-compliant OAuth 2.0 authorization server and a certified OpenID Connect provider.

OpenID Connect extends OAuth 2.0. The OAuth 2.0 protocol provides API security via scoped access tokens, and OpenID Connect provides user authentication and single sign-on (SSO) functionality.

This page contains detailed information about the OAuth 2.0 and OpenID Connect endpoints that Okta exposes on its authorization servers. For higher-level information about how to use these endpoints, see OAuth 2.0 and OpenID Connect.

Scopes

OpenID Connect uses scope values to specify which access privileges are being requested for access tokens.

The scopes associated with access tokens determine which claims are available when they are used to access the OIDC /userinfo endpoint. See OAuth 2.0 scopes for a full list of scopes.

Scope values

Note: The maximum length for the scope parameter value is 1024 characters.

• openid is required for any OpenID request connect flow. If the openid scope value isn't present, the request may be a valid OAuth 2.0 request, but it's not an OpenID Connect request.
• profile requests access to these default profile claims: name , family_name , given_name , middle_name , nickname , preferred_username , profile , picture , website , gender , birthdate , zoneinfo , locale , and updated_at .
• offline_access can only be requested in combination with a response_type that contains code . If the response_type doesn't contain code , offline_access is ignored.
• For more information about offline_access , see the OIDC spec .
• For more information about device_sso , see Native SSO .

Scope properties

A consent dialog appears depending on the values of three elements:

• prompt - a query parameter that is used in requests to /authorize
• consent_method - an application property that allows you to determine whether a client is fully trusted (for example, a first-party application) or requires consent (for example, a third-party application).
• consent - a Scope property, listed in the previous table, that allows you to enable or disable user consent for an individual scope.

Note: When a scope is requested during a Client Credentials grant flow and CONSENT is set to FLEXIBLE, the scope is granted in the access token with no consent prompt. This occurs because there is no user involved in a two-legged OAuth Client Credentials grant flow.

Notes:

• Apps created on /api/v1/apps default to consent_method=TRUSTED , while those created on /api/v1/clients default to consent_method=REQUIRED .
• If you request a scope that requires consent while using the client_credentials flow, an error is returned. Because there is no user, no consent can be given.
• If the prompt value is set to NONE , but the consent_method and the consent values are REQUIRED , then an error occurs.
• The scope name must only contain printable ASCII except for spaces, double quotes, and backslashes. It also must not start with okta. or okta: and must not be only okta or * .

Tokens and claims

This section contains some general information about claims, as well as detailed information about access and ID tokens.

• Access Token
• ID Token
• Refresh Token

Token lifetime

When you are using the Okta Authorization Server, the lifetime of the JWT tokens is hard-coded to the following values:

• ID token: 60 minutes
• Access token: 60 minutes
• Refresh token: 90 days

When you are using a Custom Authorization Server, you can configure the lifetime of the JWT tokens:

• Access tokens: The minimum is five minutes, and the maximum is 24 hours (configurable using an Access Policy ).
• Refresh tokens: The minimum access token lifetime. The idle time window is at least 10 minutes, with a maximum of five years (configurable using an Access Policy ).
• ID tokens: Not configurable. Token lifetime is 60 minutes.

Claims

Tokens issued by Okta contain claims that are statements about a subject (user). For example, the claim can be about a name, identity, key, group, or privilege. The claims in a security token are dependent upon the type of token, the type of credential used to authenticate the user, and the application configuration.

The claims requested by the profile, email, address, and phone scope values are returned from the /userinfo endpoint when a response_type value is used that results in an access token being issued. However, when no access token is issued (which is the case for the response_type value id_token), the resulting claims are returned in the ID token.

Access token

Note: Use of the access token differs depending on whether you are using the Okta Org Authorization Server or a Custom Authorization Server. While the structure of an access token retrieved from a Custom Authorization Server is guaranteed to not change, the structure of the access token issued by the Okta Org Authorization Server is subject to change.

An access token is a JSON web token (JWT) encoded in Base64 URL-encoded format that contains a header, payload, and signature. A resource server can authorize the client to access particular resources based on the scopes and claims in the access token.

The lifetime of an access token can be configured in access policies. If the client that issued the token is deactivated, the token is immediately and permanently invalidated. Reactivating the client doesn't make the token valid again.

Access token header

{
  "alg": "RS256",
  "kid": "45js03w0djwedsw"
}

Access token payload

{
  "ver": 1,
  "jti": "AT.0mP4JKAZX1iACIT4vbEDF7LpvDVjxypPMf0D7uX39RE",
  "iss": "https://{yourOktaDomain}/oauth2/{authorizationServerId}",
  "aud": "https://api.example.com",
  "sub": "00ujmkLgagxeRrAg20g3",
  "iat": 1467145094,
  "exp": 1467148694,
  "cid": "nmdP1fcyvdVO11AL7ECm",
  "uid": "00ujmkLgagxeRrAg20g3",
  "scp": [
    "openid",
    "email",
    "flights",
    "custom"
  ],
  "auth_time": 1467142021,
  "custom_claim": "CustomValue"
}

Access token signature

This is a digital signature that Okta generates using the public key identified by the kid property in the header section.

Access token scopes and claims

Access tokens include reserved scopes and claims and can optionally include custom scopes and claims.

Scopes are requested in the initial authorization request, and the Authorization Server uses the access policies to decide whether they can be granted. If any of the requested scopes are rejected by the Access Policies, the request is rejected.

Based on the granted scopes, claims are added into the access token returned from the request.

Reserved scopes and claims

Okta defines a number of reserved scopes and claims that can't be overridden.

• Reserved scopes
• Reserved claims in the header section
• Reserved claims in the payload section

Reserved scopes

openid, profile, email, address, phone, offline_access, and groups are available to ID tokens and access tokens, using either the Okta Org Authorization Server or a Custom Authorization Server. For details, see Scopes. All of these scopes except groups are defined in the OpenID Connect specification.

Additionally, we reserved the scope device_sso as it has a particular meaning in the Native SSO flow.

Reserved claims in the header section

The header only includes the following reserved claims:

Reserved claims in the payload section

The payload includes the following reserved claims:

Custom scopes and claims

You can configure custom scopes and claims for your access tokens, depending on the authorization server that you are using (see Composing your base URL):

• For the Okta Org Authorization Server, you can configure a custom groups claim.
• For a Custom Authorization Server, you can configure a custom groups claim or any other custom scopes and claims you want.

Custom scopes

If the request that generates the access token contains any custom scopes, those scopes are a part of the scp claim together with the reserved scopes provided from the OIDC specification. The names of your custom scopes must conform to the OAuth 2.0 specification.

Note: Scope names can contain the characters < (less than) or > (greater than), but not both characters.

Custom claims

Custom claims are associated with scopes. In general, granting a custom scope means a custom claim is added to the token. However, the specifics depend on which claims are requested, whether the request is to the Okta Org Authorization Server or a Custom Authorization Server, and some configuration choices.

Quick Reference: Which token has which claims?

Custom claims are configured in the Custom Authorization Server, and returned depending on whether it matches a scope in the request, and also depending on the token type, authorization server type, and the token and claim configuration set in the authorization server:

• Base claims are always returned in ID tokens and access tokens for both authorization server types (Okta Org Authorization Server or Custom Authorization Server).
• Scope-dependent claims are returned in tokens depending on the response type for either authorization server type. See the second table in the Scope-dependent claims topic for details.
• Custom claims require configuration in the Custom Authorization Server. You can specify that claims be returned in each token (ID or access) always or only when requested. Assuming a claim matches a requested scope, it is returned to the ID token if there is no access token requested.

The ID token or access token may not include all claims associated with the requested scopes. The /userinfo endpoint always contains a full set of claims for the requested scopes.

ID token

OpenID Connect introduces an ID token that is a JSON Web Token (JWT) that contains information about an authentication event and claims about the authenticated user.

Clients can use any of the following sequences of operations to obtain an ID token:

• Authorization code flow or Authorization code with PKCE flow -- the client obtains an authorization code from the authorization server's /authorize endpoint and uses it to obtain an ID token and an access token from the authorization server's /token endpoint .
• Implicit flow -- the client obtains an ID token and optionally an access token directly from the authorization server's /authorize endpoint.

Clients should always validate ID tokens to ensure their integrity.

The ID tokens returned by the /authorize endpoint (implicit flow) or the /token endpoint (authorization code flow) are identical, except if:

• You are using the implicit flow. If so, the nonce parameter is required in the initial /authorize request, and the ID token includes a nonce claim that should be validated to make sure it matches the nonce value passed to /authorize.
• Both an ID and an access token were requested. If so, the ID token includes the at_hash parameter that can be validated against the hash of the access token to guarantee that the access token is genuine.

The ID token consists of three period-separated, Base64 URL-encoded JSON segments: a header, the payload, and the signature.

ID token header

{
  "alg": "RS256",
  "kid": "45js03w0djwedsw"
}

ID token payload

{
  "ver": 1,
  "sub": "00uid4BxXw6I6TV4m0g3",
  "iss": "https://{yourOktaDomain}",
  "aud": "uAaunofWkaDJxukCFeBx",
  "iat": 1449624026,
  "exp": 1449627626,
  "amr": [
    "pwd"
  ],
  "jti": "ID.4eAWJOCMB3SX8XewDfVR",
  "auth_time": 1449624026,
  "at_hash": "cpqKfdQA5eH891Ff5oJr_Q",
  "name" :"John Doe",
  "nickname":"Jimmy",
  "preferred_username": "john.doe@example.com",
  "given_name":"John",
  "middle_name":"James",
  "family_name":"Doe",
  "profile":"https://example.com/john.doe",
  "zoneinfo":"America/Los_Angeles",
  "locale":"en-US",
  "updated_at":1311280970,
  "email":"john.doe@example.com",
  "email_verified":true,
  "address" : { "street_address": "123 Hollywood Blvd.",
      "locality": "Los Angeles",
      "region": "CA",
      "postal_code": "90210",
      "country": "US"
    },
  "phone_number":"+1 (425) 555-1212"
}

ID token signature

This is the digital signature that Okta signs using the public key identified by the kid property in the Header section.

ID token claims

The Header and Payload sections contain claims.

Claims in the Header section

Claims in the Header are always returned.

Claims in the Payload section

Claims in the payload are either base claims, independent of scope (always returned), or dependent on scope (not always returned).

Base claims (always present)

Scope-dependent claims (not always returned)

Be aware of the following before you work with scope-dependent claims:

• To protect against arbitrarily large numbers of groups matching the group filter, the groups claim has a limit of 100. If more than 100 groups match the filter, then the request fails. Expect that this limit may change in the future. For more information about configuring an app for OpenID Connect, including group claims, see Create a client application .

Important: Scope-dependent claims are returned differently depending on the values in response_type and the scopes requested:

• The full set of claims for the requested scopes is available via the /oauth2/v1/userinfo endpoint. Call this endpoint using the access token.

Refresh token

Refresh tokens are opaque. More information about using them can be found in the Refresh access tokens guide.

JSON Web Key Set

The /keys endpoint returns a JSON Web Key Set (JWKS) that contains the public keys that you can use to verify the signatures of tokens that you receive from your authorization server.

Key rotation

The keys that are used to sign tokens are periodically changed. Okta automatically rotates your authorization server's keys on a regular basis.

Clients can opt-out of automatic key rotation by changing the client sign-in mode for the Okta org authorization server. In this case, passing the client_id with your request retrieves the keys for that specific client.

Key rotation behaves differently with custom authorization servers. For more information about key rotation with custom authorization servers, see the Authorization Server Keys API.

Alternative validation

You can use the /introspect endpoint for validation.

Best practices

Okta strongly recommends retrieving keys dynamically with the JWKS published in the discovery document. Okta also recommends caching or persisting these keys to improve performance. If you cache signing keys, and automatic key rotation is enabled, be aware that verification fails when Okta rotates the keys automatically. Clients that cache keys should periodically check the JWKS for updated signing keys.

Okta recommends a background process that regularly caches the /keys endpoint. You can schedule this process to run once a day or more infrequently, for example, once per week. This ensures that you always have an up-to-date set of keys for validation even when we generate the next key or rotate automatically at the 45 or 90 day mark respectively.

Under almost all circumstances, the above would be sufficient except in cases where keys were rotated or generated outside the usual timespans. An example of this would be if Okta or a customer had a need to perform this operation for security reasons. You should augment the above approach with a failsafe for circumstances where keys are quickly regenerated and rotated.

Why not just use the second approach? There's potential for the caching of stale data since there's no guarantee that the /keys endpoint is up to date. For example, the keys are rotated, but the /keys endpoint hasn't yet been updated, which results in a period of time where failures occur.

Given that possibility, Okta recommends the blended approach of regularly scheduled caching and just-in-time checking to ensure that all possible scenarios are covered.

Troubleshooting

If you run into trouble setting up an authorization server or performing other tasks for OAuth 2.0/OIDC, use the following suggestions to resolve your issues.

Start with the System Log

The system log contains detailed information about why a request was denied and other useful information.

Limits

• Scopes are unique per authorization server.
• The audiences value you specify is an array of String. If the string contains ":" it must be a valid URI.
• Tokens can expire, be explicitly revoked at the endpoint, or implicitly revoked by a change in configuration.
• Token revocation can be implicit in two ways: token expiration or a change to the source.
  • Expiration happens at different times:
    • ID token expires after one hour.
    • Access token expiration is configured in a policy, but is always between five minutes and one day.
    • Refresh token expiration depends on two factors:
      1. Expiration is configured in an access policy, no limits, but must be greater than or equal to the access token lifetime
      2. Revocation if the refresh token isn't exercised within a specified time. Configure the specified time in an access policy, with a minimum of ten minutes.
  • Revocation happens when a configuration is changed or deleted:
    • User deactivation or deletion.
    • Configuration in the authorization server is changed or deleted.
    • The client app is deactivated, changed, unassigned, or deleted.

Subtle behavior

Some behaviors aren't obvious:

• A user must be assigned to the client in Okta for the client to get access tokens from that client. You can assign the client directly (direct user assignment) or indirectly (group assignment).
• If you haven't created a rule in a policy on the authorization server to allow the client, user, and scope combination that you want, the request fails. To resolve, create at least one rule in a policy on the authorization server for the relevant resource that specifies client, user, and scope.
• OpenID Connect scopes are granted by default, so if you are requesting only those scopes ( openid , profile , email , address , phone , or offline_access ), you don't need to define any scopes for them, but you need a policy and rule on a Custom Authorization Server. The rule grants the OpenID Connect scopes by default, so they don't need to be configured in the rule. Token expiration times depend on how they are defined in the rules and which policies and rules match the request.
• OpenID scopes can be requested with custom scopes. For example, a request can include openid and a custom scope.
• The evaluation of a policy always takes place during the initial authentication of the user (or of the client in case of the client credentials flow). If the flow isn't immediately finished, such as when a token is requested using the authorization_code grant type, the policy isn't evaluated again, and a change in the policy after the user or client is initially authenticated won't affect the continued flow.