跳到主要内容
在线体验
微信咨询
获取方案

授权码模式（PKCE）

用户访问第三方应用时，第三方应用使用code_challenge向TOPIAM发起授权登录请求，用户输入用户密码认证成功后，TOPIAM将重定向到第三方应用，并且带上授权码code参数。

获取授权码​

请求说明​

请求方式：GET

请求地址：https://{your_domain}/api/v1/authorize/{app_code}/oauth2/auth

请求头​

无

请求示例​

GET https://{your_domain}/api/v1/authorize/{app_code}/oauth2/auth?client_id=2bae87d88feb129f817a1ce52d798e0b&response_type=code&redirect_uri=https://127.0.0.1:8080/login/oauth2&scope=openid profile&code_challenge=e48gxaK8KzZMKHszOHD7ws3jYy7K8rhQuKKSNEn3f8Q&code_challenge_method=S256

请求参数​

参数名中文名称必须示例值描述
client_id客户端ID是2bae87d88feb129f817a1ce52d798e0b申请接入后分配给第三方应用的clientid。
response_type授权类型是code此值固定为 code，代表采用授权码模式。
redirect_uri回调地址是https://127.0.0.1:8080/login/oauth2授权后的回调地址，必须是注册应用时填写的可信域名一致，需要将url进行URLEncode编码。
statestate可选4dR2J42l--8jkiS2jN9mHTkrl9XXDcECa7GyscM42EY=用于防止CSRF攻击，成功授权后回调时会原样带回，请检查用户与state状态绑定。
scopescope范围可选openid profile可选值openid email phone profile。
code_challengePKCE挑战码是wz-T_qpPke3k7cs1qfgxSToF_kRhpv8RWVj7LpO3xHI应用随机生成一串长度43-128的字符并作URL-Safe的Base64编码处理，结果用作 code_verifier，将这串字符通过SHA256哈希，并用URL-Safe的Base64编码处理，结果用作 code_challenge。
code_challenge_methodPKCE挑战码加密方法是S256固定值S256。

响应参数​

如果用户成功登录并授权，则会跳转到指定的回调地址，并在redirect_uri地址后带上授权码code和原始的state值。

参数名中文名称必须示例值描述
code授权码是JH20mMwZTxL68RvriBqAXctKh3ISauj用户登录并授权后，授权服务器返回给应用的授权码。注意：此code有效期5分钟，有效期内只能使用一次。
state应用端状态码可选bnEyPsdFpO7oeYU4zfQD5NGC91klVgWfB应用端的状态值。用于第三方应用防止CSRF攻击，成功授权后回调时会原样带回。

响应示例​

成功​

HTTP Status: 302
{redirect_uri}?code=II2MdiC7Vyq5Qkf_M7SVFh3laW0aXREPZIQAtBCfkZ1Sa8D42g9f87-1Rm1tAewapYWzzV-sM__NQj610KOTImaEba15s34sxDfd0FAAVXxmm1vDsDcVIkbTlHi_97Ye

client_id 参数缺失​

client_id 参数不正确​

response_type 参数值错误​

redirect_uri 参数不正确​

scope 参数不正确​

HTTP Status: 302
{redirect_uri}?error=invalid_scope&error_description=OAuth 2.0 Parameter: scope&error_uri=https://topiam.cn/docs/application/oidc/faq/#错误码

code_challenge 参数不正确​

HTTP Status: 302
{redirect_uri}?error=invalid_request&error_description=OAuth 2.0 Parameter: code_challenge&error_uri=https://topiam.cn/docs/application/oidc/faq/#错误码

code_challenge_method 参数不正确​

HTTP Status: 302
{redirect_uri}?error=invalid_request&error_description=OAuth 2.0 Parameter: code_challenge_method&error_uri=https://topiam.cn/docs/application/oidc/faq/#错误码

获取token​

请求说明​

请求方式：POST

请求地址：https://{your_domain}/api/v1/authorize/{app_code}/oauth2/token

请求头​

参数名中文名称必须示例值描述
Content-Type数据类型是application/x-www-form-urlencoded使用表单方式提交参数。
危险

注意：此处不需要传递 Authorization Basic 认证信息。

请求示例​

POST https://{your_domain}/api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=stRWlW&redirect_uri=https://127.0.0.1:8080/login/oauth2&scope=openid profile

请求参数​

参数名中文名称必须示例值描述
grant_type授权类型是authorization_code此值固定为authorization_code。
code授权码是code上一步返回的授权code。
code_verifierPKCE验证码是aqHAm7JQXUWbjjEJ0DfW应用随机生成一串长度43-128的字符并作URL-Safe的Base64编码处理，结果用作 code_verifier，将这串字符通过SHA256哈希，并用URL-Safe的Base64编码处理，结果用作 code_challenge。
redirect_uri回调地址是https://127.0.0.1:8080/login/oauth2与上面一步中传入的 redirect_uri 保持一致。

响应参数​

参数名中文名称必须示例值描述
access_token授权令牌是5Vy9tHWsp6xORfDaTVJ49_qtFZ6wXSy授权服务器返回给第三方应用的授权令牌。
expires_in授权令牌的有效期是21599授权服务器返回给应用的访问票据的有效期。注意：有效期以秒为单位。
refresh_token刷新令牌是Su9TAyeB2igIjQD07s81BeycRQ0dppyHuc授权服务器返回给第三方应用的刷新令牌。
token_type令牌类型是Bearer始终为 Bearer。
scope授权范围是openid profile
id_token用户令牌是eyJraWQiOiIxMTISlh...H2UOrwiXF9CUKm1Zbe-j1

响应示例​

成功​

{
    "access_token": "5Vy9tHWsp6xORfDaTVJ49_qtFZ6wXSy",
    "refresh_token": "Su9TAyeB2igIjQD07s81BeycRQ0dppyHuc",
    "scope": "openid profile",
    "id_token": "eyJraWQiOiIxMTISlh...H2UOrwiXF9CUKm1Zbe-j1",
    "token_type": "Bearer",
    "expires_in": 21599
}

客户端未认证​

{
  "error_description": "Full authentication is required to access this resource",
  "error": "access_denied",
  "error_uri": "https://topiam.cn/docs/application/oidc/faq/#错误码"
}

grant_type 错误​

{
    "error_description": "OAuth 2.0 Parameter: grant_type",
    "error": "unsupported_grant_type",
    "error_uri": "https://topiam.cn/docs/application/oidc/faq/#错误码"
}

redirect_uri 地址错误​

{
  "error_description": "The redirect_uri does not match the redirection URI used in the authorization request.",
  "error": "invalid_grant",
  "error_uri": "https://topiam.cn/docs/application/oidc/faq/#错误码"
}

授权 code 错误​

{
  "error_description": "Client authentication failed: code",
  "error": "invalid_grant",
  "error_uri": "https://topiam.cn/docs/application/oidc/faq/#错误码"
}

code 无效或已过期​

{
    "error_description": "The authorization code is invalid or has expired.",
    "error": "invalid_grant",
    "error_uri": "https://topiam.cn/docs/application/oidc/faq/#%E9%94%99%E8%AF%AF%E7%A0%81"
}

client_id 或 client_secret 错误​

{
  "error_description": "Client authentication failed. Either the client or the client credentials are invalid.",
  "error": "invalid_client",
  "error_uri": "https://topiam.cn/docs/application/oidc/faq/#错误码"
}