跳到主内容

OAuth 2.0

介绍

Casdoor 支持AccessToken验证客户端。 在本节中,我们将向您展示如何获取AccessToken,如何验证AccessToken,以及如何使用AccessToken。

如何获取AcessToken

您有两种方法获得AccessToken:您可以使用 Cassdoor SDK, 欲了解详情,请参阅SDK文档,在此我们将主要向您展示如何使用 API 获取AccessToken。

Casdoor支持四种OAuth 授予类型: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, 和 Client Credentials Grant.

出于安全考虑,Casto应用默认已开启授权码模式。 如果您需要使用其他模式,请前往相应的应用程序来设置它。

OAuth授权类型

获取授权码

首先重定向您的用户请求到:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE

可用的作用域(scope)

名称描述
openid (no scope)sub (用户ID), iss (发行人) 和 aud (受众)
profile用户资料信息,包括名称、显示名称、头像
email用户的电子邮件地址
address用户地址
phone用户的电话号码
信息

您的 OAuth 应用程序可以在首次重定向时带上请求的作用域。 您可以指定多个作用域并使用空格(转义后为%20)分隔:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=...&
scope=openid%20email

更多详情,请参阅 OIDC 标准

当您的用户通过casdoor身份验证后,他的请求会被casdoor重定到:

https://REDIRECT_URI?code=CODE&state=STATE

现在您已经获得授权码,在你的后端应用发送 POST 请求:

https://<CASDOOR_HOST>/api/login/oauth/access_token

在你的后端应用

{
"grant_type": "authorization_code",
"client_id": ClientId,
"client_secret": ClientSecret,
"code": Code,
}

您将得到以下响应:

{
"access_token": "eyJhb...",
"id_token": "eyJhb...",
"refresh_token": "eyJhb...",
"token_type": "Bearer",
"expires_in": 10080,
"scope": "openid"
}
备注

Casdoor也支持 PKCE 功能。 当发送获取授权码请求时,您可以通过添加两个参数来启用 PKCE。

&code_challenge_method=S256&code_challenge=YOUR_CHANLLENGE

获取令牌时,您需要通过 code_verifier 参数来验证 PKCE 。 值得一提的是,启用PKCE 后,Client_secret并不是必需的,但如果您要发送这个参数,它的值就必须是正确的。

隐式授权

如果您的应用程序没有后端,您需要使用隐式授权。 首先,您需要确保您启用了隐式授权,然后将您的用户请求重定向到:

https://<CASDOOR_HOST>/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=token&scope=openid&state=STATE

当您的用户通过casdoor身份验证后,他的请求会被casdoor重定到:

https://REDIRECT_URI/#token=ACCESS_TOKEN

Casdoor还支持 id_token 作为参数response_type的值, 这是OpenID的一个功能。

使用资源拥有者的密码凭据授权

如果您的应用程序没有前端来重定向用户到Casdoor,那么您可能需要这个功能。

首先,您需要确保您已启用密码凭证授权,并发送一个 POST 请求:

https://<CASDOOR_HOST>/api/login/oauth/access_token
{
"grant_type": "password",
"client_id": ClientId,
"client_secret": ClientSecret,
"username": Username,
"password": Password,
}

您将得到以下响应:

{
"access_token": "eyJhb...",
"id_token": "eyJhb...",
"refresh_token": "eyJhb...",
"token_type": "Bearer",
"expires_in": 10080,
"scope": "openid"
}

使用客户端凭据授权

当应用程序没有前端时,您也可以使用客户端凭据授权。

首先,您需要确保您已启用客户端凭据授权,并发送一个 POST 请求到 https://<CASDOOR_HOST>/api/login/oauth/access_token

{
"grant_type": "client_credentials",
"client_id": ClientId,
"client_secret": ClientSecret,
}

您将得到以下响应:

{
"access_token": "eyJhb...",
"id_token": "eyJhb...",
"refresh_token": "eyJhb...",
"token_type": "Bearer",
"expires_in": 10080,
"scope": "openid"
}

必须指出,以这种方式获得的AccessToken 不同于前三个,因为它与应用程序相对应,而不是与用户相对应。

更新访问令牌

如果您想要更新访问令牌,您可以使用上面的 refreshToken

首先您需要在应用程序中设置refreshToken的到期时间(默认为0小时), 发送一个 POST 请求到 https://<CASDOOR_HOST>/api/login/oauth/refresh_token

{
"grant_type": "refresh_token",
"refresh_token": REFRESH_TOKEN,
"scope": SCOPE,
"client_id": ClientId,
"client_secret": ClientSecret,
}

您将得到响应:

{
"access_token": "eyJhb...",
"id_token": "eyJhb...",
"refresh_token": "eyJhb...",
"token_type": "Bearer",
"expires_in": 10080,
"scope": "openid"
}

如何验证访问令牌

目前Casdoor有支持 token 校验 的API。 目前,接口使用Basic 方式认证(ClientId:ClientSecret) :

POST /api/login/oauth/introspect HTTP/1.1
Host: CASDOOR_HOST
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

token=ACCESS_TOKEN&token_type_hint=access_token

您将得到以下响应:

{
"active": true,
"client_id": "c58c...",
"username": "admin",
"token_type": "Bearer",
"exp": 1647138242,
"iat": 1646533442,
"nbf": 1646533442,
"sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
"aud": [
"c58c..."
],
"iss": "http://localhost:8000"
}

如何使用访问令牌

您可以使用AccessToken访问需要认证的 Casdoor API。

例如,请求 /api/userinfo 的两种不同方法。

方法 1 查询参数:

https://<CASDOOR_HOST>/api/userinfo?accessToken=<your_access_token>

方法 2 HTTP Bearer token

https://<CASDOOR_HOST>/api/userinfo with the header: "Authorization: Bearer <your_access_token>"

Casdoor 将解析 access_token,根据 scope 作用域返回对应的用户信息。 您将得到响应:

{
"sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
"iss": "http://localhost:8000",
"aud": "c58c..."
}

如果您需要更多用户信息,在申请访问令牌获取授权码这一步添加更多 scope

userinfoget-account API 之间的差异

  • /api/userinfo: 返回用户信息是OIDC 协议的一部分。 返回少量信息,只包含OIDC标准中的基本信息 请查看 Cassdoor支持的可用的作用域(scope)

  • /api/get-account: 获取当前登录帐户的用户对象。 这是一个 只适用于Casdoor 的API, 用于获取Cassdoor中的 用户 的所有信息。