跳到主内容

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。

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

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

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