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

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。

`userinfo` 和 `get-account` APIs之间的差异

/api/userinfo：此API作为OIDC协议的一部分返回用户信息。它提供有限的信息，包括仅在OIDC标准中定义的基本信息。要查看Casdoor支持的可用范围列表，请参阅可用范围部分。
/api/get-account：此API用于检索当前登录账户的用户对象。这是一个特定于Casdoor的API，允许您获取Casdoor中用户的所有信息。

介绍​

如何获取AcessToken​

获取授权码 ​

可用的作用域（scope）​

隐式授权​

Device Grant​

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

使用客户端凭据授权​

刷新令牌​

如何验证访问令牌​

如何使用AccessToken​

userinfo 和 get-account APIs之间的差异​

介绍

如何获取AcessToken

获取授权码

可用的作用域（scope）

隐式授权

Device Grant

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

使用客户端凭据授权

刷新令牌

如何验证访问令牌

如何使用`AccessToken`

`userinfo` 和 `get-account` APIs之间的差异