Перейти до основного вмісту

OAuth 2.0

Вступ​

Casdoor підтримує використання Access Token для аутентифікації клієнтів. У цьому розділі ми покажемо вам, як отримати Access Token, як перевірити Access Token та як використовувати Access Token.

Як отримати Access Token​

Існує два способи отримання Access Token: ви можете використовувати Casdoor SDKs. Для детальної інформації, будь ласка, зверніться до документації 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інформація про профіль користувача, включаючи ім'я, displayName та аватар
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 також підтримує id_token як response_type, що є особливістю OpenID.

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 наразі підтримує кінцеву точку інтроспекції токенів. Ця кінцева точка захищена 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

Ви отримаєте наступну відповідь:

{
    "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 токен

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.

Різниця між API userinfo та get-account​

  • /api/userinfo: Це API повертає інформацію про користувача як частину протоколу OIDC. Воно надає обмежену інформацію, включаючи лише основну інформацію, визначену в стандартах OIDC. Для списку доступних областей, підтримуваних Casdoor, будь ласка, зверніться до розділу доступні області.

  • /api/get-account: Це API отримує об'єкт користувача для поточного залогіненого акаунту. Це специфічне для Casdoor API, яке дозволяє отримати всю інформацію про користувача в Casdoor.