跳到主内容

OAuth 2.0

介绍

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

如何获取AcessToken

获取访问令牌有两种方式:您可以使用 Casdoor SDK 详情请参阅SDK文档。 这里我们将主要向您展示如何使用 API 来获取访问令牌。

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_CHANNELLENGE

获取令牌时,您需要传递 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/#access_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

首先,您需要在应用中设置刷新令牌的过期时间(默认为0小时),并向https://<CASDOOR_HOST>/api/login/oauth/refresh_token发送POST请求

{
"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 目前支持 令牌自省 端点。 此端点受基本身份验证保护(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

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

例如,有两种不同的方式来请求/api/userinfo

类型1:查询参数

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

类型2:HTTP Bearer 令牌

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..."
}

如果您期望获得更多用户信息,请在获取AccessToken的步骤授权码授予中添加scope

userinfoget-account APIs之间的差异

  • /api/userinfo:此API作为OIDC协议的一部分返回用户信息。 它提供有限的信息,包括仅在OIDC标准中定义的基本信息。 要查看Casdoor支持的可用范围列表,请参阅可用范围部分。

  • /api/get-account:此API用于检索当前登录账户的用户对象。 这是一个特定于Casdoor的API,允许您获取Casdoor中用户的所有信息。