Link Search Menu Expand Document
Link Search Menu Expand Document XAuth
文档
使用指南 集成应用 开发者

OIDC&OAuth2.0 APIs

  1. OIDC&OAuth2.0 APIs
    1. 基础URL组合
      1. 1.仅单点登录场景
      2. 2. 作为您应用或者API的授权中心
    2. EndPoint
      1. /Authorize
      2. /Token
      3. /Introspect
      4. /Revoke
      5. /Logout
      6. /Userinfo

基础URL组合

此页面上的所有端点都以授权服务器的Url为首拼接，但是该服务器的URL因端点和授权服务器的类型而异。根据您的使用场景，有两种类型的授权服务器可供选择：

1.仅单点登录场景

这适用于您有多个应用，但是仍然期望XAuth用于统一存储和管理您组织的用户，以便于用户可以使用XAuth进行单点登录。并且您仅希望为他们提供单点登录（例如，您希望您的员工使用其XAuth帐户登录到应用程序）。从技术角度看，在OAuth2.0术语定义中中，XAuth既是授权服务器又是资源服务器。当XAuth作为自身的授权服务器时，我们将其称为XAuth 内置授权服务器，您的baseUrl如下所示：

https://${yourXAuthDomain}/oauth/v1

完整的/authorze端点如下所示：

https://${yourXAuthDomain}/oauth/v1/authorize

2. 作为您应用或者API的授权中心

这适用于您希望XAuth充当应用程序的用户存储、认证、授权的中心，类似于您为您的应用和API构建一个身份OS/身份中台（但是，虽然XAuth充当应用程序的用户存储，但XAuth对用户不可见）。从技术的专业定义上，应用或API最为资源服务器（Resource Server，简称RS），而XAuth是RS的授权服务器。这种我们需要选择在XAuth上的自定义授权服务器作为RS授权服务器，您的基本URL如下所示：

https://${yourXAuthDomain}/oauth/v1/${authorizationServerId}

完整的/authorze端点如下所示：

https://${yourXAuthDomain}/oauth/v1/${authorizationServerId}/authorize

XAuth平台为您创建了默认的<自定义授权服务器>：

https://${yourXAuthDomain}/oauth/v1/default

完整的/authorze端点如下所示：

https://${yourXAuthDomain}/oauth/v1/default/authorize

参考：授权服务器了解授权服务器的更多信息和如何选择。

EndPoint

/Authorize

GET ${baseUrl}/v1/authorize

注：此端点的基baseUrl 因您是否使用<自定义授权服务器>而异。

/authorzie端点是基于浏览器的OIDC协议流程（如Implicit和授权码模式）的起点。该端点需要对用户进行身份验证并将token与授权许可作为回调响应的一部分一起返回给客户端应用程序。

注：When making requests to the /authorize endpoint, the browser (user agent) should be redirected to the endpoint. You can’t use AJAX with this endpoint.

请求参数

参数 描述 参数类型 数据类型 是否必需
client_id 在XAuth中创建应用时获得的，该应用在XAuth内的唯一标识。 Query String 是
code_challenge PKCE中的挑战码，该挑战码将在请求access token时进行验证 Query String 否
code_challenge_method 生成PKCE挑战码的算法。默认算法: S256 Query String 否
display 执行社交登录时传递给IdP（身份供应商）的display参数。参数值包括：page , popup , touch , wap，如果display参数未指定，则默认为page Query String 否
login_hint 当提示进行身份验证时，要预填充的用户名。（将login_hint带来的参数作为用户名填入认证页面的登录窗的用户名输入窗中，用户可以重新填写其它的用户名） Query String 否
nonce nonce是在 ID token中返回的值，它用于防止重放攻击。在Implicit和Hybrid模式中nonce是必需的，但对于授权码式是可选的。详见OIDC标准 Query String 否
prompt 有效的值包括: none, consent, login, login consent或consent login Query String 否
redirect_uri 接收授权码或token的回调地址，该回调地址必须是应用在XAuth中配置的回调地址相匹配。 Query String 是
response_type code, token, id_token三者的任意组合，不同的组合对应的不同的OIDC模式和流程。 Query String 是
response_mode 响应授权请求的方式。 值包括：fragment, form_post, query 。当response_type是 id_token 或token 时， response mode的值不能是query 。Implicit模式和Hybrid 模式中默认为fragment 。 Query String 否
scope 在认证的场景中必须有openid ，同时也可以有其它scopes Query String 是
sessionToken XAuth一次性的会话token，用于基于 API 的用户登录流程（而不是 XAuth 登录 UI）。会话token可以通过AuthN API 获取。 Query String 否
state 在token中返回的值。客户端应用程序可以使用它来记住在身份验证调用时它与最终用户的交互状态。它可以包含字母数字、逗号、句点、下划线和连字符。 Query String 否

参数详情

  • idp, sessionToken and idp_scope是在OIDC协议上扩展的参数

  • display：该参数用于指定授权服务器向用户展现身份认证和授权信息确认的交互界面。

    • page ：授权服务器应当使用一个完整的页面向用户展现身份认证和授权信息确认的交互，如果display参数未指定，则默认为page
    • popup ：授权服务器应当使用一个弹窗向用户展现身份认证和授权信息确认的交互
    • touch ：授权服务器应当使用触屏交互的设备向用户展现身份认证和授权信息确认的交互
    • wap：授权服务器应当使用适配功能机的交互方式向用户展现身份认证和授权信息确认界面

  • prompt：

    如果没有指定prompt参数，将发生以下标准行为：

    • 如果会话已存在，则对用户进行静默验证。否则，将提示用户进行身份验证。
    • 如果请求的scope需要用户确认同意，而经过身份验证的用户尚未同意，则会提示用户同意。

    该参数可能有4个值：

    • none：不需要提示进行身份认证或同意；当XAuth会话已经存在时，对用户进行静默验证；否则报错
    • login：不论在XAuth中是否已经存在该用户的会话，始终提示进行身份认证。
    • consent：在应用中是否需要用户确认的配置concent_method和scope的concent属性值共同决定了是否弹窗提示并由用户确认。“用户确认同意”在自定义授权服务器中同样可用。
    • login consent或consent login（二者相同）：始终提示用户进行身份验证，并且根据应用程序中为 concent_method的值和scope的concent属性值，即使用户已经同意，也会出现用户同意对话框。

  • request：

    • 必须使用应用的client Secret对JWT进行签名
    • 该JWT不能加密
    • XAuth支持HMac、RSA签名算法。HMac算法签名需要应用客户端的token_endpoint_auth_method是client_secret
    • 建议您不要在 JWT 和query URI 本身中复制任何请求参数。您可以在state nonce code_challenge code_challenge_method 这些参数中这样做。在这些情况下，JWT 中的值会覆盖查询 URI 值。
    • XAuth通过以下几种方式使reques 的参数生效：
      1. iss 必需，且必须是client_id
      2. aud必需，且值必须与生成access token 和ID token的授权服务器的issuer值相同。该值将发布的授权服务器的元数据
      3. JWT必须有签发时间iat和过期时间exp。如果JWT已过期或无效，XAuth将报错invalid_request_object。
      4. 当JWT的jti存在但是已被处理时，XAuth将拒绝该JWT

  • response_mode：

    response_mode 的每个值提供不同的行为：

    • fragment：参数在重定向回客户端时添加到 redirect_uri 的 URL 片段中进行编码。例如：

      在Implicit流程中，当response_type设置为token的时候，授权服务器会直接把access token通过url的fragment部分返回给应用客户端,

http://example.com/oauth-callback**#**access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz&expires_in=3600

  • query：参数在重定向回客户端时添加到 redirect_uri 的query字符串中进行编码。例如：

    授权码流程中，当response_type设置为code的时候，授权服务器会把授权码code通过url的query部分传递给应用客户端,

https://example.com/oauth-callback**?**code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

  • form_post：参数被编码为 HTML 表单值（application/x-www-form-urlencoded 格式）并通过 HTTP POST 方法发送到客户端。

    当reponse_mode设置为form_post的时，授权服务器返回的示例：

 <html>
   <head><title>Submit This Form</title></head>
   <body onload="javascript:document.forms[0].submit()">
    <form method="post" action="https://client.lnh.dev/oidc-callback">
      <input type="hidden" name="state"
       value="DcP7csa3hMlvybERqcieLHrRzKBra"/>
      <input type="hidden" name="id_token"
       value="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiw
         iYXVkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLC
         Jpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5M
         DMxMTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1B
         SnllRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0F
         NTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2Mz
         kwMDg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqq
         wwq-Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fk
         IufbGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcq
         XVEKhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_h
         nrQ5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc
         0uVAwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA"/>
    </form>
   </body>

关于form_post更详细的说明参考oauth-v2-form-post-response-mode-1_0

  • state：

    为防止跨站攻击（CSRF），XAuth要求所有对/authorize端点的请求都使用state参数。OAuth2规范要求客户端通过在授权请求中发送一个值来保护他们的重定向 URI 免受 CSRF 的影响，该值将请求和用户身份验证状态绑定。使用state参数也是对其他几种已知的针对OAuth2的攻击的一种预防对策。

  • nonce：

    nonce 参数值需要包含每个会话的状态，并且攻击者无法猜测。为 Web 服务器客户端实现此目的的方法是将随机值存储为 HttpOnly session cookie，并使用该值的哈希作为 nonce 参数。在这种情况下，将返回的 ID token中的随机数与session cookie 的哈希值进行比较，以检测第三方对 ID token的重放。一种适用于 JavaScript 客户端的相关方法是将随机值存储在 HTML5 的 local storage中，并使用该值的哈希。

/authorazie请求的响应

无论是哪种响应类型（response type），响应的内容都如表中所述。

参数 描述 类型
access_token 当 response_type 中包含 token参数时，返回access token String
code 授权码，它是一个随机数用于token端点换取token。当 response_type 是code时返回 。 授权码的有效期是300秒。 String
error 错误代码，当发生异常时返回 String
error_description 错误描述 String
expires_in access_token 的过期时间，单位是“秒”。只有当返回了access_token时才返回该参数 String
id_token 当 response_type 中包含 id_token参数时返回 String
scope access_token中提供的socpe，只有当返回了access_token时才返回该参数 String
state 未经修改过的原请求中的 state参数值。 String
token_type token的类型，通常是 Bearer ，并且只有当 response_type 中包含 token参数时返回 String

异常信息

这些 API 符合OIDC和 OAuth 2.0 规范以及一些 XAuth的 特定扩展。

OAuth2错误代码

错误代码 详情
access_denied 服务器拒绝了请求
invalid_client 无效的client ID
invalid_grant 指定的授权无效、已过期、已撤销或与授权请求中使用的重定向 URI 不匹配
invalid_request 请求缺少必要参数、参数值无效或请求包含重复参数。
invalid_scope 请求的 scopes 包含无效或不受支持的值。
invalid_token 提供的access token无效
server_error 服务器内部发生错误。
temporarily_unavailable 服务器暂时不可用，但稍后能够处理请求。
unsupported_response_type 指定的response_type无效或不受支持。
unsupported_response_mode 指定的response_mode无效或不受支持，对于不允许的response_mode也会引发该错误。例如，当包含 的response_mode为query时指定的response_tpye 包含id_token。

OIDC错误代码

错误代码 详情
insufficient_scope 提供的access token不包含访问资源所需的scope。
login_required 该请求指定了不显示任何提示，但用户当前未通过身份验证。

请求的示例

发起的请求中由 response_type=code 指定了授权码模式。该请求会返回一个授权码code，用于向/token端点请求access token。

https://${yourXAuthSubDomain}/oauth/v1/default/authorize?client_id=0oabucvy
c38HLL1ef0h7&response_type=code&scope=openid&redirect_uri=http%3A%2F%2Flocal
host%3A8080&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601&nonce=g5ly497e8ps

此请求执行了相同的操作，但使用request参数传递了包含所有查询参数的HS256算法签名的JWT：

https://${yourXAuthSubDomain}/oauth/v1/default/authorize?
  request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPa3RhIiwiaWF0IjoxNTEyNTE2MjIxLCJleHAiOjE1NDQwNTIyMjEsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6InNqYWNrc29uQGV4YW1wbGUuY29tIiwiRW1haWwiOiJzamFja3NvbkBleGFtcGxlLmNvbSIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIiwicmVzcG9uc2VfbW9kZSI6ImZvcm1fcG9zdCIsInJlZGlyZWN0X3VyaSI6Im15UmVkaXJlY3RVUkkuY29tIiwic3RhdGUiOiJteVN0YXRlIiwibm9uY2UiOiJteU5vbmNlIiwic2NvcGUiOiJvcGVuaWQgb2ZmbGluZV9hY2Nlc3MifQ.TjPy2_nUerULClavBNHcpnO_Pd1DxNEjQCeSW45ALJg

该请求发起了Implicit模式，从授权服务器直接获取 ID token和access token，无需交换code的步骤。除了 response_type=id_token token 参数以外，其它与第一个示例相同：

https://${yourXAuthSubDomain}/oauth/v1/default/authorize?client_id=0oabv6kx4qq6
h1U5l0h7&response_type=id_token token&scope=openid&redirect_uri=https%3A%2F%2Fwww.example.com&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601&nonce=foo

（成功的）响应示例

在授权码模式中，端点发送重定向头，将用户的浏览器重定向回发出请求的应用程序。

根据授权类型，XAuth 返回一个code：

https://www.example.com#code=QnowT-aeawtOJKp-MtkH&state=e97f03dd-d006-4e2d-8aa6-c221702a29ec

或者是返回了一个token：

https://www.example.com#access_token=eyJhbGciOiJSUzI1NiJ9.eyJ2ZXIiOjEsImlzcyI6Imh0dHA6Ly9yYWluLm9rdGExLmNvbToxODAyIiwiaWF0IjoxNDQ5NjI0MDI2LCJleHAiOjE0NDk2Mjc2MjYsImp0aSI6IlVmU0lURzZCVVNfdHA3N21BTjJxIiwic2NvcGVzIjpbIm9wZW5pZCIsImVtYWlsIl0sImNsaWVudF9pZCI6InVBYXVub2ZXa2FESnh1a0NGZUJ4IiwidXNlcl9pZCI6IjAwdWlkNEJ4WHc2STZUVjRtMGczIn0.HaBu5oQxdVCIvea88HPgr2O5evqZlCT4UXH4UKhJnZ5px-ArNRqwhxXWhHJisslswjPpMkx1IgrudQIjzGYbtLFjrrg2ueiU5-YfmKuJuD6O2yPWGTsV7X6i7ABT6P-t8PRz_RNbk-U1GXWIEkNnEWbPqYDAm_Ofh7iW0Y8WDA5ez1jbtMvd-oXMvJLctRiACrTMLJQ2e5HkbUFxgXQ_rFPNHJbNSUBDLqdi2rg_ND64DLRlXRY7hupNsvWGo0gF4WEUk8IZeaLjKw8UoIs-ETEwJlAMcvkhoVVOsN5dPAaEKvbyvPC1hUGXb4uuThlwdD3ECJrtwgKqLqcWonNtiw&token_type=Bearer&expires_in=3600&scope=openid&state=e97f03dd-d006-4e2d-8aa6-c221702a29ec

（失败的）响应示例

请求的scopes无效：

https://www.example.com/#error=invalid_scope&error_description=The+requested+scope+is+invalid%2C+unknown%2C+or+malformed

/Token

POST ${baseUrl}/v1/token

此端点根据请求参数返回 access tokens, ID tokens,和 refresh tokens。对于password、client credentials、和refresh token流程，调用 /token是这些流程的唯一步骤。对于授权码流，调用 /token是该流的第二个步骤（第一步先调用 /authorize获取code）。

注意：如果是授权码流获取refresh token，必须将 offline_access范围作为对 /authorize 端点的代码请求的一部分进行请求，而不是发送到 /token 端点的请求。参考：获取刷新令牌

注意：此端点的基本URL因您是否使用自定义授权服务器而异。有关更多信息，请参见基础URL组合。

请求参数

以下参数可通过 URL-encoded form values 作为请求的一部分发送到 /token端点。

注意：注意：/token端点需要客户端进行身份验证。有关选择哪种方法进行验证，以及如何

使用请求中的参数的更多信息，请参阅客户端身份验证方法”部分。

参数 描述 类型
code 如果grant_type是authorization_code,则该参数值不能为空。该值从/authorize端点获取。code的有效期为300s. String
code_verifier 如果 grant_type 是 authorization_code 且上一步 /authorize 初始请求时指定了 code_challenge，则该参数值不能为空。XAuth使用该参数计算出 code_challenge 用来与初始请求时指定的 code_challenge进行比对是否一致。 长度介于43到128个字符（含）之间的不可使用的加密随机字符串，使用字符A–Z、A–Z、0–9、“-”、“.”、“”和“~” String
grant_type 可以是如下值：authorization_code, password, client_credentials, refresh_token. Sting
password 如果grant_type是password,则该参数值不能为空。 String
redirect_uri 如果grant_type是authorization_code,则该参数值不能为空。用于指定授权回调的地址，该值必须与上一步 /authorize 初始请求时指定了的redirect_uri一致 String
refresh_token 如果grant_type是refresh_token,则该参数值不能为空。该值是之前从本端点颁发的有效的刷新令牌。 String
scope 如果grant_type是password,这是客户端希望包含在访问令牌中的scope列表。 如果grant_type是refresh_token,则这些scope(s)必须是用于首先生成刷新令牌的scopes的子集。 String
username 如果grant_type是password,则该参数值不能为空。 String

响应参数

响应的参数如下，基于请求的scopes，响应的Scopes的值回包含在access token中。

参数 描述 类型
access_token 访问令牌 String
token_type 令牌的受众 String
expires_in 访问令牌的过期时间（秒） Integer
scope 访问令牌中包含的作用域。 String
refresh_token 不透明的刷新令牌。如果offline_access被包含在scope中授予，则返回此值。注意：如果是authorization_code 则offline_access是对 /authorize 端点的代码请求的Scope中包含。 String
id_token 身份令牌，如果scope中包含了openid，则需要返回该值 String

可能的错误

错误id 错误描述
invalid_client 没有找到指定的client_id
invalid_grant code 和refresh_token、username+password, client_credentials,这种组合错误。或者redirect_uri与上一步的授权请求中的该uri不一致。
invalid_request 请求结构无效。例如，基本身份验证header的格式不正确，header和form参数都用于身份验证，或者未提供身份验证信息，或者请求包含重复的参数。
invalid_scope 请求的scopes中包含非法的、或不支持的值，或grant_type是refresh_token时，新的请求超越之前授予范围的值。
unsupported_grant_type 请求不支持的Grant_type，非authorization_code, password, client_credentials, refresh_token.

请求示例

curl -v -X POST \
-H "Content-type:application/x-www-form-urlencoded" \
"https://${yourXAuthDomain}/oauth/v1/default/token" \
-d "client_id=${clientId}&client_secret=${clientSecret}&grant_type=authorization_code&redirect_uri=${redirectUri}&code=${code}"

响应示例（成功)

{
    "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJ2ZXIiOjEsImlzcyI6Imh0dHA6Ly9yYWluLm9rdGExLmNvbToxODAyIiwiaWF0IjoxNDQ5NjI0MDI2LCJleHAiOjE0NDk2Mjc2MjYsImp0aSI6IlVmU0lURzZCVVNfdHA3N21BTjJxIiwic2NvcGVzIjpbIm9wZW5pZCIsImVtYWlsIl0sImNsaWVudF9pZCI6InVBYXVub2ZXa2FESnh1a0NGZUJ4IiwidXNlcl9pZCI6IjAwdWlkNEJ4WHc2STZUVjRtMGczIn0.HaBu5oQxdVCIvea88HPgr2O5evqZlCT4UXH4UKhJnZ5pxArNRqwhxXWhHJisslswjPpMkx1IgrudQIjzGYbtLFjrrg2ueiU5-YfmKuJuD6O2yPWGTsV7X6i7ABT6P-t8PRz_RNbk-U1GXWIEkNnEWbPqYDAm_Ofh7iW0Y8WDA5ez1jbtMvdoXMvJLctRiACrTMLJQ2e5HkbUFxgXQ_rFPNHJbNSUBDLqdi2rg_ND64DLRlXRY7hupNsvWGo0gF4WEUk8IZeaLjKw8UoIsETEwJlAMcvkhoVVOsN5dPAaEKvbyvPC1hUGXb4uuThlwdD3ECJrtwgKqLqcWonNtiw",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "scope"      : "openid email",
    "refresh_token" : "a9VpZDRCeFh3Nkk2VdY",
    "id_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMHVpZDRCeFh3Nkk2VFY0bTBnMyIsImVtYWlsIjoid2VibWFzdGVyQGNsb3VkaXR1ZGUubmV0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInZlciI6MSwiaXNzIjoiaHR0cDovL3JhaW4ub2t0YTEuY29tOjE4MDIiLCJsb2dpbiI6ImFkbWluaXN0cmF0b3IxQGNsb3VkaXR1ZGUubmV0IiwiYXVkIjoidUFhdW5vZldrYURKeHVrQ0ZlQngiLCJpYXQiOjE0NDk2MjQwMjYsImV4cCI6MTQ0OTYyNzYyNiwiYW1yIjpbInB3ZCJdLCJqdGkiOiI0ZUFXSk9DTUIzU1g4WGV3RGZWUiIsImF1dGhfdGltZSI6MTQ0OTYyNDAyNiwiYXRfaGFzaCI6ImNwcUtmZFFBNWVIODkxRmY1b0pyX1EifQ.Btw6bUbZhRa89DsBb8KmL9rfhkumbNC2pgC8yu8obJnwO12nFBepui9KzbpJhGM91PqJwi_AylE6rpehamfnUAO4JL14PkemF45Pn3u_6KKwxJnxcWxLvMuuisnvIs7NScKpOAab6ayZU0VL8W6XAijQmnYTtMWQfSuaaR8rYOaWHrffh3OypvDdrQuYacbkT0csxdrayXfBG3UF5ZAlhfch1fhFT3yZFdWwzkSDc0BGygfiFyNhCezfyT454wbciSZgrA9ROeHkfPCaX7KCFO8GgQEkGRoQntFBNjluFhNLJIUkEFovEDlfuB4tv_M8BM75celdy3jkpOurg"
}

响应示例（错误)

HTTP 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
    "error" : "invalid_client",
    "error_description" : "No client credentials found."
}

/Introspect

POST ${baseUrl}/v1/introspect

注：此端点的基baseUrl 因您是否使用自定义授权服务器而异。

该接口称为自省端点，自省端点对传入的access token 、ID token、refresh token进行判断，然后返回token是否有效的布尔值。如果token是有效的，还会返回有关token的其他数据；如果token无效、过期或者已注销则视为不可用的、无效的。

确保您使用的是用于创建token的同一个授权服务器的 /introspect 端点。

尽管 ID token可以发送到此端点进行自省，但它们通常在应用侧进行验证。

参考RFC标准7662

请求示例

以下参数可以作为 URL 编码的表单值的一部分发送到 API接口。

/introspect 端点需要客户端身份验证。大多数客户端身份验证方法要求使用Basice身份验证方法将client_id和 client_secret 进行base64 编码包含在授权头中。详情查看客户端认证方式章节。

对于没有client_secret的公共客户端（例如SPA应用和移动应用程序），您必须在调用 /introspect 端点时包含 client_id 作为查询参数。确保您没有在请求中传递授权头。

参数 描述 类型
token access token, ID token, refresh token String
token_type_hint 表示本次请求自省的 token 类型， 有效的值包括: access_token, id_token, refresh_token, String (枚举)

响应参数

返回的 JSON 根据token的类型及其状态，包含了不同的信息。除了token中的claims外，还可能包含：

参数 描述 类型
active token是否有效的状态 Boolean
aud token的audience String
client_id 与token关联的应用的client_id String
exp token的过期时间，使用Unix标准时 Integer
iat token的颁发时间，使用Unix标准时 Integer
iss 颁发token的授权服务器的issuer信息 String
jti token 的标识ID String
nbf Identifies the time (a timestamp in seconds since January 1, 1970 UTC) before which the token must not be accepted for processing. Integer
scope 以空格分隔的scopes String
sub token的主体 String
token_type token类型，通常是 Bearer. String
uid 用户标识。仅当token是access token并且主体是用户时才返回此参数。 String
username token关联的用户名 String

备注：此处的sub、uid、username三者是否都有存在必要？

异常信息

错误代码 详情
invalid_client 指定的client ID 无效。
invalid_request 请求结构无效。例如，基本认证的头格式错误，头和表单参数都用于认证，没有提供认证信息，或者请求包含重复的参数。

响应示例（成功的access token）

{
    "active" : true,
    "token_type" : "Bearer",
    "scope" : "openid profile",
    "client_id" : "a9Vadfsdada3342VdYsdfg",
    "username" : "yang.yu@example.com",
    "exp" : 1351605300,
    "iat" : 1351602700,
    "sub" : "ang.yu@example.com",
    "aud" : "https://${yourXAuthDomain}",
    "iss" : "https://${yourXAuthDomain}/oauth/v1/acmmksfnnseinsf3",
    "jti" : "AT.7P4KlczBYaffasdfeiNYkZIC9uGJ28Cc-YcN",
    "uid" : "q4SZasdOeasdfa423sdaa"
}

响应示例（成功的refresh token）

{
    "active" : true,
    "token_type" : "Bearer",
    "scope" : "openid profile email",
    "client_id" : "a9Vadfsdada3342VdYsdfg",
    "username" : "john.doe@example.com",
    "exp" : 1451606500,
    "sub" : "yang.yu@example.com",
    "device_id" : "q4SZasdOeasdfa423sdaae"
}

响应示例（ token无效）

{
    "active" : false
}

异常的响应示例

HTTP 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
    "error" : "invalid_client",
    "error_description" : "No client credentials found."
}

/Revoke

POST ${baseUrl}/v1/revoke

注：此端点的基baseUrl 因您是否使用自定义授权服务器而异。

该API 用于撤销access toekn 和refresh token。被撤销的token在/introspect端点自省的结果是无效的token。客户端只能撤销自己的token。

请求参数

以下参数可以作为 URL 编码的表单值的一部分发送到 API接口。

/revoke端点需要对客户端身份验证。关于选择哪种方式以及如何在请求中使用参数，请参阅客户端身份验证方法章节。

参数 描述 类型
token access token或 refresh token String
token_type_hint 表示本次请求中 token 类型， 有效的值包括: access_token, refresh_token String (枚举)

只撤销请求中指定的token（如，请求中指定了一个refresh token，则只撤销该refresh token，该用户的access token不会被撤销）

响应

成功撤销将返回 HTTP 200 OK 。请注意：为避免泄露信息，撤销无效、过期或已撤销的token时都会返回成功的响应。

异常

错误代码 详情
invalid_client 指定的client ID 无效。
invalid_request 请求结构无效。例如，基本认证头格式错误，头和表单参数都用于认证，没有提供认证信息，或者请求包含重复的参数。

响应示例(成功的）

HTTP 200 OK

响应示例(失败的）

HTTP 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
    "error": "invalid_client",
    "error_description": "No client credentials found."
}

/Logout

GET ${baseUrl}/v1/logout

注意：此端点的baseUrl因您是否使用自定义授权服务器而异。有关更多信息，请参见基础URL组合。

使用此操作可通过删除用户的XAuth的浏览器会话注销用户。

如果主体与当前 XAuth会话匹配，此端点将获取ID令牌并将用户从XAuth注销。可以指定post_logout_redirect_uri以在执行注销后重定向浏览器。否则，浏览器将重定向到XAuth登录页面。有关更多信息，请参阅[XAuth执行用户登出]。

如果不存在XAuth会话，则此端点无效，浏览器将立即重定向到XAuth登录页面或post_logout_redirect_uri（如果指定）。

请求参数

以下为请求可以包含的参数：

参数 描述 类型 是否必须
id_token_hint 有效的指向当前Session的ID Token String 是
post_logout_redirect_uri 注销成功后重定向的uri，必须在XAuth的应用中已经添加。 String 否
state 可选值，包含在重定向的响应中返回 String 否

请求示例

如下发起XAuth的注销请求，并在注销后重定向到XAuth登录页面。

GET https://${baseUrl}/logout?id_token_hint=${id_token}

如下发起XAuth的注销请求，并注销后重定向到post_logout_redirect_uri

GET https://${baseUrl}/logout?
  id_token_hint=${id_token}&
  post_logout_redirect_uri=${post_logout_redirect_uri}&
  state=${state}

请求响应

HTTP 302 Found
Location: https://example.com/post_logout/redirect&state=${state}

错误条件

  • 如果XAuth会话已过期（或不存在），注销请求只会重定向到XAuth登录页面或post_logout_redirect_uri（如果指定）。
  • 如果通过IDtoken提示传递的ID令牌无效，浏览器将重定向到错误页面。
  • 如果ID_token有效但已过期，并且主体与当前XAuth会话匹配，则注销请求会注销用户并将浏览器重定向到post_logout_redirect_uri。

/Userinfo

GET ${baseUrl}/v1/userinfo

注：此端点的基baseUrl 因您是否使用自定义授权服务器而异。

返回有关当前登录用户的信息。

您必须在 HTTP 授权头中包含access token（在/authorization端点返回）。

请求示例

curl -X GET \
-H "Authorization: Bearer ${access_token}" \
"https://${baseUrl}/userinfo"

响应示例

返回一个 JSON 文档，其中包含有关当前（经过身份验证的）用户身份信息(描述用户身份的claims)。

响应示例（成功的）

{
  "sub": "00uidadafa32sdsd4m0g3",
  "name" :"yang yu",
  "nickname":"wudao",
  "given_name":"yang",
  "middle_name":"-",
  "family_name":"yu",
  "profile":"https://example.com/yang.yu",
  "zoneinfo":"china/hangzou",
  "updated_at":1311270380,
  "email":"yang.yu@example.com",
  "email_verified":true,
  "phone_number":"+86 189xxxx1212"
}

其中许多claims也包含在 ID token中，但调用该userinfo端点时会始终返回用户的所有claims。ID token可以配置为包括用户claims的子集。查看ID token文档中关于依赖于scope的claims的说明以了解详情。

响应示例（失败的）

HTTP 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid"

响应示例（失败的）

HTTP 403 Forbidden
Expires: 0
WWW-Authenticate: Bearer error="insufficient_scope", error_description="The access token must provide access to at least one of these scopes - profile, email, address or phone"
email sales@cipherchina.com
address
杭州市余杭区中国人工智能小镇5幢7楼
qrcode
企业身份
单点登录SSO 自适应MFA 通用身份目录 API访问与管理 B2B集成
解决方案
集团身份建设 远程办公 向云迁移 密码管理 伙伴身份
资源中心
使用指南 Open API 更新日志 博客 现代身份构建指南
©2017-2022 XAuth 版权所有 浙ICP备2021006333号