跳到主内容

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

After your user has authenticated with Casdoor, Casdoor will redirect them to:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

Casdoor also supports the id_token as response_type, which is a feature of OpenID.

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

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

First, you need to make sure you have Password Credentials Grant enabled and send a POST request to:

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

使用客户端凭据授权

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

First, you need to make sure you have Client Credentials Grant enabled and send a POST request to 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 不同于前三个,因为它与应用程序相对应,而不是与用户相对应。

Refresh Token

Maybe you want to update your Access Token, then you can use the refreshToken you obtained above.

First, you need to set the expiration time of the Refresh Token in the application (default is 0 hours), and send a POST request to https://<CASDOOR_HOST>/api/login/oauth/refresh_token

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

You will get a response like this:

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

How to Verify Access Token

Casdoor currently supports the token introspection endpoint. This endpoint is protected by Basic Authentication (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

You will receive the following response:

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

How to Use AccessToken

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

For example, there are two different ways to request /api/userinfo.

Type 1: Query parameter

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

Type 2: HTTP Bearer token

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

Casdoor will parse the access_token and return corresponding user information according to the scope. You will receive the same response, which looks like this:

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

If you expect more user information, add scope when obtaining the AccessToken in step Authorization Code Grant.

Differences between the userinfo and get-account APIs

  • /api/userinfo: This API returns user information as part of the OIDC protocol. It provides limited information, including only the basic information defined in OIDC standards. For a list of available scopes supported by Casdoor, please refer to the available scopes section.

  • /api/get-account: This API retrieves the user object for the currently logged-in account. It is a Casdoor-specific API that allows you to obtain all the information of the user in Casdoor.