OpenID连接和OAuth 2.0

Okta是一个符合标准的OAuth 2.0授权服务器，也是一个经过认证的OpenID Connect提供商。

OpenID Connect扩展了OAuth 2.0。OAuth 2.0协议通过作用域访问令牌提供API安全性，OpenID Connect提供用户身份验证和单点登录（SSO）功能。

此页面包含Okta在其授权服务器上公开的OAuth 2.0和OpenID Connect端点的详细信息。有关如何使用这些端点的更高级信息，请参阅OAuth 2.0和OpenID Connect。

Scopes

OpenID Connect使用作用域值来指定为访问令牌请求哪些访问权限。

与访问令牌关联的作用域决定了在使用声明访问OIDC/userinfo端点时哪些声明可用。有关作用域的完整列表，请参阅OAuth 2.0作用域。

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

Okta发行的代币包含关于主题（用户）的声明。例如，声明可以是关于名称、身份、密钥、组或特权。安全令牌中的声明取决于令牌的类型、用于对用户进行身份验证的凭据的类型以及应用程序配置。

当使用response_type值导致发出访问令牌时，配置文件、电子邮件、地址和电话范围值所请求的声明将从/userinfo端点返回。但是，当没有发出访问令牌时（response_type值id_token就是这种情况），结果声明将在id令牌中返回。

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.

访问令牌是以Base64 URL编码格式编码的JSON web令牌（JWT），其中包含标头、有效载荷和签名。资源服务器可以根据访问令牌中的作用域和声明授权客户端访问特定资源。

访问令牌的生命周期可以在访问策略中配置。如果发出令牌的客户端被停用，则令牌将立即永久失效。重新激活客户端不会使令牌再次有效。

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:

Note: Okta has two types of authorization servers: the org authorization server and the custom authorization server. To learn more about each type of authorization server and when to use them, see Authorization servers.

• 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.

最佳实践

Okta强烈建议使用发现文档中发布的JWKS动态检索密钥。Okta还建议缓存或持久化这些密钥以提高性能。如果缓存签名密钥，并且启用了自动密钥旋转，请注意，当Okta自动旋转密钥时，验证失败。缓存密钥的客户端应定期检查JWKS以获取更新的签名密钥。

Okta建议使用一个定期缓存/keys端点的后台进程。您可以将此过程安排为每天运行一次或不经常运行一次，例如每周运行一次。这可确保您始终拥有一组最新的密钥进行验证，即使我们分别在45天或90天生成下一个密钥或自动旋转。

在几乎所有情况下，除了在通常的时间跨度之外旋转或生成密钥的情况外，上述操作就足够了。一个例子是，如果Okta或客户出于安全原因需要执行此操作。在快速重新生成和旋转密钥的情况下，您应该用故障保护来增强上述方法。

为什么不采用第二种方法呢？由于无法保证/keys端点是最新的，因此有可能缓存过时的数据。例如，键被旋转，但/keys端点尚未更新，这导致在一段时间内发生故障。

鉴于这种可能性，Okta建议采用定期缓存和及时检查的混合方法，以确保涵盖所有可能的情况。

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

有些行为并不明显：

• 必须在Okta中将用户分配给客户端，以便客户端从该客户端获取访问令牌。您可以直接（直接用户分配）或间接（组分配）分配客户端。
• 如果您尚未在授权服务器上的策略中创建允许所需的客户端、用户和作用域组合的规则，则请求将失败。要解决此问题，请在授权服务器上的策略中为指定客户端、用户和范围的相关资源创建至少一个规则。
• OpenID Connect作用域是默认授予的，因此如果您只请求这些作用域（OpenID、配置文件、电子邮件、地址、电话或离线访问），则不需要为它们定义任何作用域，但需要在自定义授权服务器上制定策略和规则。默认情况下，该规则授予OpenID Connect作用域，因此不需要在规则中配置它们。令牌过期时间取决于它们在规则中的定义方式以及哪些策略和规则与请求匹配。
• OpenID作用域可以通过自定义作用域进行请求。例如，请求可以包含openid和自定义作用域。
• 策略的评估始终在用户（或客户端凭据流中的客户端）的初始身份验证期间进行。如果流没有立即完成，例如当使用authorization_code授权类型请求令牌时，则不会再次评估策略，并且在用户或客户端最初经过身份验证后对策略的更改不会影响继续的流。