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

Property Description Type Default Required for create or update
consent Indicates whether a consent dialog is needed for the scope. Valid values: REQUIRED, IMPLICIT. Enum IMPLICIT True
optional Indicates whether the Scope is optional. When set to true, the user can skip consent for the scope. Boolean False False
default Whether the scope is a default scope Boolean False
description Description of the scope String False
displayName Name of the end user displayed in a consent dialog window String False
id ID of the scope String False
metadataPublish Whether the scope should be included in the metadata. Valid values: NO_CLIENTS, ALL_CLIENTS Enum NO_CLIENTS True except for create
name Name of the scope String True
system Whether Okta created the scope Boolean False

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.
prompt Value consent_method consent Result
CONSENT TRUSTED or REQUIRED REQUIRED Prompted
CONSENT TRUSTED or REQUIRED FLEXIBLE Prompted
CONSENT TRUSTED IMPLICIT Not prompted
NONE TRUSTED FLEXIBLE, IMPLICIT, or REQUIRED Not prompted
NONE REQUIRED FLEXIBLE or REQUIRED Prompted
NONE REQUIRED IMPLICIT Not prompted

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.

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

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

Access token payload

Copy
Copied
{
  "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

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:

Property Description DataType
alg Identifies the digital signature algorithm used. This is always RS256. String
kid Identifies the public-key used to sign the access_token. The corresponding public-key can be found via the JWKS in the discovery document. String
Reserved claims in the payload section

The payload includes the following reserved claims:

Property Description DataType
auth_time The time the end user was authenticated, represented in Unix time (seconds). Integer
cid Client ID of the client that requested the access token. String
exp The time the access token expires, represented in Unix time (seconds). Integer
iat The time the access token was issued, represented in Unix time (seconds). Integer
iss The Issuer Identifier of the response. This value is the unique identifier for the Authorization Server instance. String
jti A unique identifier for this access token for debugging and revocation purposes. String
scp Array of scopes that are granted to this access token. Array
uid A unique identifier for the user. It isn't included in the access token if there is no user bound to it. String
ver The semantic version of the access token. Integer
acr Information about the level of assurance that the user verified at the time of authentication String
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:

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

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

ID token payload

Copy
Copied
{
  "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.

Property Description DataType
alg Identifies the digital signature algorithm used. This is always RS256. String
kid Identifies the public key used to verify the ID token. The corresponding public key can be found via the JWKS in the discovery document. String
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)
Property Description DataType Example
amr JSON array of strings that are identifiers for authentication methods used in the authentication. Array [ "pwd", "mfa", "otp", "kba", "sms", "swk", "hwk" ]
aud Identifies the audience that this ID token is intended for. It is one of your application's OAuth 2.0 client IDs. String 6joRGIzNCaJfdCPzRjlh
auth_time The time the end user was authenticated, represented in Unix time (seconds). Integer 1311280970
exp The time the ID token expires, represented in Unix time (seconds). Integer 1311280970
iat The time the ID token was issued, represented in Unix time (seconds). Integer 1311280970
idp The Okta org ID or the ID of an Identity Provider if this authentication used Social Authentication or Inbound SAML. String 00ok1u7AsAkrwdZL3z0g3
iss The URL of the authorization server that issued this ID token. String https://{yourOktaDomain}
jti A unique identifier for this ID token for debugging and revocation purposes. String Tlenfse93dgkaksginv
sub The subject. A unique identifier for the user. String 00uk1u7AsAk6dZL3z0g3
ver The semantic version of the ID token. Integer 1
Scope-dependent claims (not always returned)
Property Required Scope Description DataType Example
name profile User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the user's locale and preferences. String John Doe
nickname profile Casual name of the user that may or may not be the same as the given_name. String Jimmy
preferred_username profile The chosen login (username) for the end user. By default this is the Okta username. String john.doe@example.com
given_name profile Given name(s) or first name(s) of the user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. String John
middle_name profile Middle name(s) of the user. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names aren't used. String James
family_name profile Surname(s) or last name(s) of the user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. String Doe
profile profile URL of the user's profile page. String https://profile.wordpress.com/john.doe
zoneinfo profile String that represents the user's time zone. String America/Los_Angeles
locale profile Language and ISO3166‑1 country code in uppercase, separated by a dash. String en-US
updated_at profile Time the user's information was last updated, represented in Unix time (seconds). Integer 1311280970
email email User's preferred email address. The resource provider must not rely on this value being unique. String john.doe@example.com
email_verified email True if the user's email address (Okta primary email) has been verified; otherwise false. boolean true
address address User's preferred postal address. The value of the address member is a JSON structure that contains street_address, locality, region, postal_code, and country. JSON structure { "street_address": "123 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US" }
phone_number phone User's preferred telephone number in E.164 format. String +1 (425) 555-1212
groups groups The groups that the user is a member of that also match the ID token group filter of the client app. List [ "MyGroup1", "MyGroup2", "MyGroup3" ]

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:

Response Type Claims Returned in ID Token from Org AS Claims Returned in ID Token from Custom AS Claims Returned from Userinfo Endpoint
code N/A N/A N/A
token N/A N/A N/A
id_token Claims associated with requested scopes. Claims associated with requested scopes. N/A
id_token code Claims associated with requested scopes. Claims associated with requested scopes. N/A
id_token token email if email scope is requested; name and preferred_username if profile scope is requested Claims associated with the requested scopes and the alwaysIncludeinToken property set to true. Claims associated with the requested scopes
code id_token token email if email scope is requested; name and preferred_username if profile scope is requested Claims associated with the requested scopes and the alwaysIncludeinToken property set to true. Claims associated with the requested scopes
  • 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.

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.