跳到主内容

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.

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

OAuth授权类型

Authorization Code Grant

首次重定向您的用户到 https:///<CASDOOR_HOST>/api/login/oauth/codeclient_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=openid&state=STATE 当您的用户已经通过casdoor进行身份验证后,casdoor将会重定向到 https://REDIRECT_URI?code=CODE&state=STATE 现在您已经获得了授权码,在您的后端应用程序中为 https:////<CASDOOR_HOST>/api/login/oauth/access_token 发出一个 POST 请求:

{
"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 功能。 您可以添加两个参数:&code_challenge_method=S256&code_challenge=YOUR_CHANLLENGE以启用 PKCE。 获取令牌时,您需要通过 代码验证器 参数来验证 PKCE 。 值得一提的是,启用PKCE 后,Client_secret并不需要,但如果您要通过它,它就必须是正确的。

Implicit Grant

如果您的应用程序没有后端,您需要使用Implicit Grant。 首先,您需要确保您启用了Implicit Grant,然后将您的用户重定向到:https:////<CASDOOR_HOST>/login/oauth/author/authority? lient_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 as response_type, 这是OpenID的一个功能。

Resource Owner Password Credentials Grant

如果您的应用程序没有前端重定向用户到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"
}

Client Credentials Grant

当应用程序没有前端时,您也可以使用Client Credentials Grant。

首先,您需要确保您已启用Client Credentials Grant,并发送一个 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小时) 发送一个 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 introspection 端点。 目前,端点受Basic Authoritarian (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。 这是当我们只使用“openid”范围获取用户信息端点时。

  1. 查询参数:

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

  1. HTTP 持证人令牌

使用header访问 https:///<CASDOOR_HOST>/api/userinfo "Authorization: Bearer ACCESSTOKEN <your_access_token>"

您将得到响应:

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

当我们使用 "openid profile address phone email" 作为范围时,我们可以得到更详细的回应:

{
"sub": "2f80c349-4beb-407f-b1f0-528aac0f1acd",
"iss": "https://door.casbin.com",
"aud": "7a11****0fa2172",
"name": "admin",
"preferred_username": "Admin",
"email": "admin@example.com",
"picture": "https://casbin.org/img/casbin.svg",
"address": "Guangdong",
"phone": "12345678910"
}

userinfoget-account API 之间的差异

  • /api/userinfo: 返回用户信息作为OIDC 协议的一部分。 归还的信息较少,包括只归还OIDC 标准中的基本信息。 您可以通过添加 scope 返回更多信息。 此步骤应该在您获得 code, 之前重定向到 授权代码授予
信息

范围

以下是未编码范围请求的非规范性例子:

scope=openid profile 电子邮件电话

除了这些OpenID特定范围外,您的范围参数还可以包含其他范围值。 所有范围值必须是空间分隔的。

欲了解更多详情,请参阅 OIDC 标准

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