OAuth 2.0

Введение

Casdoor поддерживает использование Access Token для аутентификации клиентов. В этом разделе мы покажем вам, как получить Access Token, как проверить Access Token и как использовать Access Token.

Как получить Access Token

Есть два способа получить Access Token: вы можете использовать SDK Casdoor. Для подробной информации, пожалуйста, обратитесь к документации SDK. Здесь мы в основном покажем вам, как использовать API для получения Access Token.

Casdoor поддерживает четыре типа OAuth-авторизации: Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant и Client Credentials Grant.

В целях безопасности в приложении Casdoor по умолчанию включен режим кода авторизации. Если вам нужно использовать другие режимы, пожалуйста, перейдите в соответствующее приложение, чтобы настроить его.

Authorization Code Grant

Сначала перенаправьте ваших пользователей на:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE

Доступные области

Имя	Описание
openid (no scope)	sub (идентификатор пользователя), 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 не требуется, но если вы его передаете, он должен быть корректным.

Implicit Grant

Возможно, у вашего приложения нет серверной части, и вам нужно использовать Implicit Grant. Сначала вам нужно убедиться, что у вас включен Implicit Grant, затем перенаправьте ваших пользователей на:

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 также поддерживает response_type id_token, который является функцией 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.

Resource Owner Password Credentials Grant

Если у вашего приложения нет фронтенда, который перенаправляет пользователей в Casdoor, тогда это может вам понадобиться.

Сначала вам нужно убедиться, что у вас включен Password Credentials Grant и отправить 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, полученный таким образом, отличается от первых трех тем, что он соответствует приложению, а не пользователю.

Refresh Token

Возможно, вы хотите обновить ваш Access Token, тогда вы можете использовать полученный выше refreshToken.

Сначала вам нужно установить время истечения Refresh Token в приложении (по умолчанию 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"
}

Как проверить Access Token

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 для доступа к API Casdoor, требующим аутентификации.

Например, есть два разных способа запросить /api/userinfo.

Тип 1: Параметр запроса

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

Тип 2: HTTP Bearer token

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

Если вы ожидаете больше информации о пользователе, добавьте scope при получении AccessToken на шаге Authorization Code Grant.

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.

Различия между API userinfo и get-account

• /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.