1. Token有效期
2. 什么是Claims
3. 访问令牌解析(Access Token)
   1. 令牌格式
   2. 预留的scopes和claims
   3. 自定义的scopes和claims
4. 身份令牌(ID Token) 解析
   1. 令牌格式
   2. 基本Claims（始终存在）
   3. 依赖于scope的claims（不始终返回）
5. Refresh Token

Token有效期

当使用XAuth内置的授权服务器时，生成的token有效期是固定的：

• Access token ：1小时
• ID token ：1小时
• Refresh token ：90天

当使用自定的授权服务器时，token有效期是可以配置的：

• Access token ：最小3分钟，最大24小时（在自定义授权服务器的访问策略中配置）
• Refresh token ：最小3分钟，最大999天。（在自定义授权服务器的访问策略中配置）
• ID token ： 不可以配置，有效期固定为1小时

什么是Claims

XAuth颁发的token中包含一组用于描述主体（用户）的claims，如姓名、身份、权限等。token的类型决定了其中的claims，token在类型有两种：用于认证用户，用于认证应用程序。

当使用access token请求/userinfo端点时，返回的是与access token中指定的scopeprofile， email ，phone， address 所对应claims 。但当未颁发access token时（这是response_type 值为 id_token 时的情况），claims的值将在包含在 ID token中。

访问令牌解析(Access Token)

注：对access token的使用会根据您使用的是XAuth内置授权服务器还是自定义授权服务器有所不同。由自定义授权服务器颁发的access token的结构是不会改变的，但是由XAuth内置授权服务器颁发的access token的结构可能会发生变化。

access token 是一个使用Base64 URL 编码格式的JWT（JSON web token ），它包含了Header（头）、payload和签名三部分。资源服务器可以根据access token中的scopes和claims来授权客户端访问特定资源。

在自义授权服务器的访问策略中可以配置access token的有效期。如果颁发token的客户端被停用，token将立即永久失效，即使重新激活客户端不会使token再次有效。

令牌格式

access token的 Header

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

access token的 payload

{
  "ver": 1,
  "jti": "AT.sdotTcWK5_oCxUf1521HNhG4hD4zrboaf0HExDEgmqk",
  "iss": "https://domain.xauth.cloud/oauth/v1/0oacqf8qaJw56czJi0g4",
  "aud": "https://api.example.com",
  "sub": "userName",
  "iat": 1634807022,
  "exp": 1634810622,
  "cid": "0oa4kxu5gaeV6M1yr696",
  "uid": "00u4j6wy5gYz4csRa696",
  "scp": [
    "openid",
    "email",
    "phone",
    "custom"
  ],
  "custom_claim": "CustomValue"
}

access token的签名

access token的签名是使用header部分中的 Kid 所标识的公钥生成的数字签名。

access token 、scopes和claims

access token中包括预留的scopes和claims，同时可以选择性地包括自定义的scopes和claims。

在第一步向授权服务器发起的的授权请求中（/authorization）包含了本次请求的scopes，授权服务器根据访问策略来决定是否可以授予它们。

然后根据授予的scope，将对应的claims添加到返回的access token中。

预留的scopes和claims

XAuth 定义了一些预留的scopes和claims。

• 预留的scopes
• 在Header中预留的claims
• 在payload中预留的claims

预留的 scopes

在XAuth中预留了以下几个OIDC标准规定的scope：openid 、profile、 email、 phone 、address 和offline_access，这些scopes在XAuth的内置授权服务器和自定义授权服务器中都是可用的。

在Header中预留的claims

在header中只有以下两个claims：

在payload中预留的claims

在payload中预留了以下几个claims：

自定义的scopes和claims

在XAuth的自定义授权服务器中，您可以为access token配置自定义的scopes和claims。

自定义的scopes

当一个生成access tokenr的请求中包含自定义的scope时，请求中的这些自定义scopes将与 OIDC 规范提供的scopes一起成为claim: scp的一部分。自定义scope的名称必须符合OAuth2的规范。

注：Scope名称中可以包含<或>，但是二者不能同时存在。 （于洋备注：这点与Scope中的约定相悖。）

自定义的Claims

自定义claims是与scopes相关联的。通常情况下，授予自定义scope意味着将自定义的claims添加到token中。但是具体还取决于请求哪些claims或其它配置的选择。

参考：token和claims的对应关系

自定义claims在自定义授权服务器中进行配置，token中包含哪些claims取决于多种因素，包括请求中scopes关联了哪些claims、请求的token类型、在授权服务器中token与claim的配置：

• 内置授权服务器和自定义授权服务器颁发的access token和ID token中始终包含基本claims（预留的claims）
• 根据授权服务器的responesType在token中返回依赖于scope的claims。请在Scope-dependent claims的第二个表格中查看详情。
• 自定义Claims需要在自定义授权服务器中进行配置，您可以指定始终或仅在请求时在每个token（ID token 或access token）中返回claims。在没有请求access token时，如果claim与请求中的scopes匹配则在ID token中返回。

ID token和access token中可能不包括所有与请求的scopes关联的claims，但是在/userinfo端点中始终包含与scope关联的所有claims。

身份令牌(ID Token) 解析

在OIDC协议中引入了一个 ID token，它是一个 JSON Web token (JWT)，在ID token中包含有关身份验证事件的信息和验证通过后用户的声明(claims)。

客户端可以使用以下任意操作来获取ID token：

• Authorization code或Authorization code + PKCE 模式：客户端从授权服务器的/authorize端点取得授权码（Authorization code），然后使用授权码向授权服务器的/token端点换取ID token 和access token
• Implicit 模式：客户端直接从授权服务器的/authorize端点获取ID token 以及access token

客户端应当始终验证ID token以确保其完整性。

通过以上介绍了两种获取ID token的方法（从/authorize端点获取、通过授权码从/token端点获取取）所取得的ID token都是完全相同的，除了以下情形：

• 在Implicit模式下，在初始/authorize请求中需要nonce参数，此时在 ID token中将有一个名为 nonce的claim，应验证该claim以确保它与传递给 /authorize 的 nonce 值匹配。
• 在ID token和access token都生成了的情况下， ID token中将包含一个 at_hash 参数，该参数可以由access token的哈希值来进行验证，以确保access token的是真实的。

令牌格式

ID token的Header

{
  "alg": "RS256",
  "kid": "8rB7hRasIdvwxZu2IujzBRSI-oitxtB9CjvAtewNXIw"
}

ID token的payload

{
  "ver": 1,
  "sub": "userName",
  "iss": "https://domain.xauth.cloud",
  "aud": "https://api.example.com",
  "iat": 1634807022,
  "exp": 1634810622,
  "amr": [
    "pwd"
  ],
  "jti": "ID.4eAWJOCMB3SX8XewDfVR",
  "auth_time": 1449624026,
  "at_hash": "cpqKfdQA5eH891Ff5oJr_Q",
  "name" :"Zhang San",
  "nickname":"Sam",
  "given_name":"San",
  "family_name":"Zhang",
  "profile":"https://example.com/john.doe",
  "zoneinfo":"CN/Hangzhou",
  "locale":"CN",
  "updated_at":1311280970,
  "email":"zhang@example.com",
  "email_verified":true,
  "address" : { "street_address": "文一西路1818-2号",
      "locality": "杭州",
      "region": "浙江",
      "postal_code": "310000",
      "country": "CN"
    },
  "phone_number":"+86 0571-12345678"
}

ID token的签名

ID token的签名是使用header部分中的 Kid 所标识的公钥生成的数字签名。

ID token的Claims

在ID token的Header和payload 中包含了calims

Header中的Claims

在ID token的header中始终返回claims：

Payload中的Claim

ID token中的calims包含基本claims、独立不依赖于scope的claims（始终返回）、依赖于scope的claims（不始终返回）

基本Claims（始终存在）

依赖于scope的claims（不始终返回）

重要：请求中的response_tpye和所请求的scopes决定了返回的信息中包含哪些依赖于scope的claims

通过使用access token访问/userinfo端点可以取得所请求的scopes中所包含的全部完整的claims

Refresh Token

Refresh Token是个不透明的令牌。更多的信息参考获取刷新令牌