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应用默认已开启授权码模式。 如果您需要使用其他模式，请前往相应的应用程序来设置它。

获取授权码

首先，重定向您的用户到：

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的一个特性。

Device Grant

Maybe your devices have limited input capabilities or lack a suitable browser, and you need to use Device Grant. First, you need to make sure you have Device Grant enabled, the request device_authorization_endpoint in OIDC discover, then use QR code or text to show verification_uri and lead user to enter login page.

Second, you should request token endpoint to get Access Token with parameter define in rfc8628.

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

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

Accessing OAuth Provider Tokens

When users authenticate through OAuth providers (GitHub, Google, etc.), you can access the provider's original access token to make API calls to the third-party service on their behalf. This token is stored in the user's originalToken field.

The token is available through the /api/get-account endpoint:

{
  "status": "ok",
  "data": {
    "name": "user123",
    "originalToken": "ya29.a0AfH6SMBx...",
    ...
  }
}

The originalToken is visible only when the user requests their own account or when the requester is an admin. For other requests, it is masked for privacy.

This allows your application to interact with third-party APIs (e.g., GitHub API, Google Drive API) using the provider's access token without requiring additional OAuth flows.

userinfo 和 get-account APIs之间的差异

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

• /api/get-account：此API用于检索当前登录账户的用户对象。 It is a Casdoor-specific API that allows you to obtain all the information of the user in Casdoor, including the OAuth provider's access token when applicable.