Вхід користувачів через SDK Casdoor
Цей посібник містить список SDK Casdoor і пояснює, як забезпечити вхід користувачів у веб-додаток за допомогою фронтенд-SDK і бекенд-SDK. Приклади використовують casdoor-js-sdk та casdoor-go-sdk. Інші SDK працюють за тим самим принципом.
Результати навчання
- Виберіть SDK для вашої платформи.
- Налаштуйте бекенд-SDK і фронтенд-SDK.
- Обміняйте код авторизації на токен доступу та перевірте токен.
- Підтримуйте стан входу користувача у вашому додатку.
- Керуйте користувачами та додатками через SDK.
Що потрібно
- Працюючий екземпляр Casdoor
- Додаток у Casdoor з URL зворотного виклику вашого додатка у полі Redirect URLs
- Ідентифікатор клієнта (client ID) і секретний ключ клієнта (client secret) додатка, а також відкритий ключ його сертифіката
Про SDK
SDK Casdoor базуються на OpenID Connect (OIDC) і додають функції API Casdoor, такі як керування користувачами та завантаження файлів. Вони потребують трохи більше налаштувань, ніж стандартний OIDC-клієнт, але надають повний доступ до API Casdoor.
- Фронтенд-SDK: Для веб-фронтендів, мобільних додатків і десктопних додатків. Вони формують URL для входу та обробляють зворотний виклик в інтерфейсі.
- Бекенд-SDK: Для вашого сервера. Вони обмінюють код авторизації, перевіряють токени та викликають API Casdoor.
Якщо у вашого додатка окремі фронтенд і бекенд, використовуйте фронтенд-SDK в інтерфейсі та бекенд-SDK на сервері. Приклад див. у casdoor-python-vue-sdk-example. Якщо ваш додаток рендерить сторінки на сервері, як це роблять JSP- та PHP-додатки, може бути достатньо лише бекенд-SDK.
Виберіть SDK
Усі офіційні SDK знаходяться в організації casdoor на GitHub.
SDK для веб-фронтенду
| SDK для веб-фронтенду | Опис | Код SDK | Приклад коду |
|---|---|---|---|
| Javascript SDK | Для традиційних не-SPA веб-сайтів | casdoor-js-sdk | Nodejs backend: casdoor-raw-js-example Go backend: casdoor-go-react-sdk-example |
| SDK лише для фронтенду | Для веб-сайтів SPA лише з фронтендом | casdoor-js-sdk | casdoor-react-only-example |
| React SDK | Для веб-сайтів на React | casdoor-react-sdk | Nodejs backend: casdoor-nodejs-react-example Java backend: casdoor-spring-security-react-example |
| Next.js SDK | Для веб-сайтів на Next.js | nextjs-auth | |
| Nuxt SDK | Для веб-сайтів на Nuxt | nuxt-auth | |
| Vue SDK | For Vue websites | casdoor-vue-sdk | casdoor-python-vue-sdk-example |
| Angular SDK | For Angular websites | casdoor-angular-sdk | casdoor-nodejs-angular-example |
| Flutter SDK | For Flutter Web websites | casdoor-flutter-sdk | casdoor-flutter-example |
| ASP.NET SDK | For ASP.NET Blazor WASM websites | Blazor.BFF.OpenIDConnect.Template | casdoor-dotnet-blazorwasm-oidc-example |
| Firebase SDK | Для додатків Google Firebase | casdoor-firebase-example |
SDK для веб-бекенду
| SDK для веб-бекенду | Опис | Код Sdk | Приклад коду |
|---|---|---|---|
| Go SDK | Для Go бекендів | casdoor-go-sdk | casdoor-go-react-sdk-example |
| Java SDK | Для Java бекендів | casdoor-java-sdk | casdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example, quarkus-casdoor-auth (Quarkus) |
| Node.js SDK | Для Node.js бекендів | casdoor-nodejs-sdk | casdoor-nodejs-react-example |
| Python SDK | Для Python бекендів | casdoor-python-sdk | Flask: casdoor-python-vue-sdk-example Django: casdoor-django-js-sdk-example FastAPI: casdoor-fastapi-js-sdk-example |
| PHP SDK | Для PHP бекендів | casdoor-php-sdk | wordpress-casdoor-plugin |
| .NET SDK | Для ASP.NET бекендів | casdoor-dotnet-sdk | casdoor-dotnet-sdk-example |
| Rust SDK | Для Rust бекендів | casdoor-rust-sdk | casdoor-rust-example |
| C/C++ SDK | Для C/C++ бекендів | casdoor-cpp-sdk | casdoor-cpp-qt-example |
| Dart SDK | Для Dart бекендів | casdoor-dart-sdk | |
| Ruby SDK | Для Ruby бекендів | casdoor-ruby-sdk |
Мобільні SDK
| Mobile SDK | Опис | Код SDK | Приклад коду |
|---|---|---|---|
| Android SDK | Для Android додатків | casdoor-android-sdk | casdoor-android-example |
| iOS SDK | Для iOS додатків | casdoor-ios-sdk | casdoor-ios-example |
| React Native SDK | Для додатків React Native | casdoor-react-native-sdk | casdoor-react-native-example |
| Flutter SDK | Для Flutter додатків | casdoor-flutter-sdk | casdoor-flutter-example |
| Firebase SDK | Для додатків Google Firebase | casdoor-firebase-example | |
| Unity Games SDK | Для 2D/3D ігор на Unity для ПК/мобільних пристроїв | casdoor-dotnet-sdk | casdoor-unity-example |
| uni-app SDK | Для додатків uni-app | casdoor-uniapp-sdk | casdoor-uniapp-example |
Мобільний додаток, який виконує автентифікацію користувачів нативно, без браузера, може використовувати grant за кодом підтвердження для входу через SMS або електронну пошту з автоматичною реєстрацією. Користувачі, які увійшли в систему, також можуть підтвердити QR-код на сторінці входу вашого сайту з додатку.
Настільні SDK
| Набір розробника для робочого столу | Опис | Код SDK | Приклад коду |
|---|---|---|---|
| Electron SDK | Для додатків Electron | casdoor-js-sdk | casdoor-electron-example |
| .NET SDK для робочого столу | Для .NET додатків для робочого столу | casdoor-dotnet-sdk | WPF: casdoor-dotnet-desktop-example WinForms: casdoor-dotnet-winform-example Avalonia UI: casdoor-dotnet-avalonia-example |
| C/C++ SDK | Для C/C++ додатків для робочого столу | casdoor-cpp-sdk | casdoor-cpp-qt-example |
Налаштуйте бекенд SDK
Коли ваш бекенд запускається, ініціалізуйте SDK з адресою Casdoor та обліковими даними додатку. З casdoor-go-sdk:
var CasdoorEndpoint = "https://door.casdoor.com"
var ClientId = "541738959670d221d59d"
var ClientSecret = "66863369a64a5863827cf949bab70ed560ba24bf"
var CasdoorOrganization = "casbin"
var CasdoorApplication = "app-casnode"
//go:embed token_jwt_key.pem
var JwtPublicKey string
func init() {
auth.InitConfig(CasdoorEndpoint, ClientId, ClientSecret, JwtPublicKey, CasdoorOrganization, CasdoorApplication)
}
InitConfig() приймає наступні параметри:
| Параметр | Обов'язково | Опис |
|---|---|---|
| endpoint | Так | Casdoor Server URL, like https://door.casdoor.com or http://localhost:8000 |
| clientId | Так | Client ID для додатку Casdoor |
| clientSecret | Так | Client secret для додатку Casdoor |
| jwtPublicKey | Так | Публічний ключ для сертифіката додатку Casdoor |
| organizationName | Так | Назва для організації Casdoor |
| applicationName | Ні | Назва для додатку Casdoor |
Щоб отримати значення jwtPublicKey:
-
В адміністративній консолі Casdoor відкрийте сторінку Certs.

-
Відкрийте сертифікат і скопіюйте або завантажте його відкритий ключ.

-
На сторінці редагування додатку виберіть той самий сертифікат у полі Cert.

Налаштуйте фронтенд SDK
-
Встановіть
casdoor-js-sdkза допомогою npm:npm install casdoor-js-sdkАбо за допомогою Yarn:
yarn add casdoor-js-sdk -
Визначте допоміжні функції у спільному файлі, наприклад,
Setting.js:import Sdk from "casdoor-js-sdk";
export function initCasdoorSdk(config) {
CasdoorSdk = new Sdk(config);
}
export function getSignupUrl() {
return CasdoorSdk.getSignupUrl();
}
export function getSigninUrl() {
return CasdoorSdk.getSigninUrl();
}
export function getUserProfileUrl(userName, account) {
return CasdoorSdk.getUserProfileUrl(userName, account);
}
export function getMyProfileUrl(account) {
return CasdoorSdk.getMyProfileUrl(account);
}
export function getMyResourcesUrl(account) {
return CasdoorSdk.getMyProfileUrl(account).replace("/account?", "/resources?");
}
export function signin() {
return CasdoorSdk.signin(ServerUrl);
}
export function showMessage(type, text) {
if (type === "") {
return;
} else if (type === "success") {
message.success(text);
} else if (type === "error") {
message.error(text);
}
}
export function goToLink(link) {
window.location.href = link;
} -
У вхідному файлі фронтенду, наприклад,
index.jsабоapp.jsу React, ініціалізуйте SDK. Використовуйте ті ж значення для перших чотирьох налаштувань, що й у бекенд SDK.redirectPath— це шлях вашого додатку, куди Casdoor повертає користувача після входу.const config = {
serverUrl: "https://door.casdoor.com",
clientId: "014ae4bd048734ca2dea",
organizationName: "casbin",
appName: "app-casnode",
redirectPath: "/callback",
};
xxx.initCasdoorSdk(config); -
Обробіть маршрут зворотного виклику (callback). У цьому прикладі React компонент обробляє
/callbackі передає код на бекенд. Пропустіть цей крок, якщо Casdoor перенаправляє напряму на ваш бекенд, як у додатках JSP та PHP.import React from "react";
import {Button, Result, Spin} from "antd";
import {withRouter} from "react-router-dom";
import * as Setting from "./Setting";
class AuthCallback extends React.Component {
constructor(props) {
super(props);
this.state = {
classes: props,
msg: null,
};
}
componentWillMount() {
this.login();
}
login() {
Setting.signin().then((res) => {
if (res.status === "ok") {
Setting.showMessage("success", `Logged in successfully`);
Setting.goToLink("/");
} else {
this.setState({
msg: res.msg,
});
}
});
}
render() {
return (
<div style={{textAlign: "center"}}>
{this.state.msg === null ? (
<Spin
size="large"
tip="Signing in..."
style={{paddingTop: "10%"}}
/>
) : (
<div style={{display: "inline"}}>
<Result
status="error"
title="Login Error"
subTitle={this.state.msg}
extra={[
<Button type="primary" key="details">
Details
</Button>,
<Button key="help">Help</Button>,
]}
/>
</div>
)}
</div>
);
}
}
export default withRouter(AuthCallback);
Показуйте посилання на вхід та реєстрацію
Надайте користувачам кнопки або посилання Sign in та Sign up. Отримайте URL-адреси з фронтенд SDK або бекенд SDK. Див. URL-адреси входу та реєстрації.
Отримайте та перевірте токен доступу
Процес входу складається з трьох кроків:
-
Користувач натискає посилання на вхід і потрапляє на сторінку входу Casdoor, наприклад:
https://door.casdoor.com/login/oauth/authorize?client_id=014ae4bd048734ca2dea&response_type=code&redirect_uri=https%3A%2F%2Fforum.casbin.com%2Fcallback&scope=read&state=app-casnode -
Користувач вводить ім'я користувача та пароль і натискає Sign In, або натискає кнопку провайдера, наприклад, кнопку GitHub.
-
Casdoor перенаправляє користувача до вашого додатку з кодом авторизації, наприклад
https://forum.casbin.com?code=xxx&state=yyy.
Ваш бекенд потім обмінює код на токен доступу за допомогою GetOAuthToken() і перевіряє токен за допомогою ParseJwtToken():
// get code and state from the GET parameters of the redirected URL
code := c.Input().Get("code")
state := c.Input().Get("state")
// exchange the access token with code and state
token, err := auth.GetOAuthToken(code, state)
if err != nil {
panic(err)
}
// verify the access token
claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
panic(err)
}
Якщо ParseJwtToken() не повертає помилку, токен дійсний і виданий Casdoor. Користувач увійшов у систему. Використовуйте повернуті claims для ідентифікації користувача. Для повного прикладу див. обробник входу Casnode, форуму, написаного на Go.
Підтримуйте сесію користувача
Те, як ваш додаток запам'ятовує користувача, є вашим власним дизайнерським рішенням і не є частиною OIDC, OAuth 2.0 або Casdoor. Цей розділ описує два поширені способи.
claims, які повертає ParseJwtToken(), мають наступний тип:
type Claims struct {
User
AccessToken string `json:"accessToken"`
jwt.RegisteredClaims
}
| Field | Description |
|---|---|
User | The user, with all profile fields. See User |
AccessToken | The access token string |
jwt.RegisteredClaims | The standard claims of a JSON Web Token (JWT) |
У Casdoor токен доступу містить ті ж дані про користувача (claims), що й ID-токен, тому він містить інформацію про користувача, який увійшов у систему. Це все ще окремі токени з різним твердженням tokenType і можливо різним aud. Див. Токен доступу та ID-токен.
Використовуйте серверну сесію
Зберігайте claims у сесії вашого веб-фреймворку. Те, як ви це робите, залежить від мови програмування та фреймворку. Casnode використовує фреймворк Beego і зберігає користувача за допомогою c.SetSessionUser():
token, err := auth.GetOAuthToken(code, state)
if err != nil {
panic(err)
}
claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
panic(err)
}
claims.AccessToken = token.AccessToken
c.SetSessionUser(claims) // set session
Використовуйте токен доступу як JWT
Токен доступу є JWT. Якщо ваш додаток зберігає сесії у вигляді JWT, використовуйте токен доступу напряму:
- Надішліть токен доступу на фронтенд і збережіть його там, наприклад, у
localStorageбраузера. - Надсилайте токен доступу на бекенд із кожним запитом.
- На бекенді перевірте токен за допомогою
ParseJwtToken()або вашої власної функції та прочитайте з нього дані про користувача, який увійшов у систему.
Керуйте користувачами через SDK
Бекенд SDK обгортають Casdoor API. Ця частина не стосується OIDC або OAuth 2.0. Функції включають:
| Function | Description |
|---|---|
GetUser(name string) | Gets a user by username |
GetUsers() | Gets all users |
AddUser() | Adds a user |
UpdateUser() | Updates a user |
DeleteUser() | Deletes a user |
CheckUserPassword(auth.User) | Перевіряє пароль користувача |
Якщо SDK не має функції для певного ендпоінту, викликайте Casdoor API безпосередньо.
Керування додатками через SDK
| Function | Description |
|---|---|
AddApplication() | Creates an application |
GetApplication(name string) | Отримує додаток за назвою |
GetApplications() | Gets all applications |
UpdateApplication() | Updates an application |
DeleteApplication() | Deletes an application |
Коли ви створюєте додаток за допомогою AddApplication(), Casdoor заповнює стандартні елементи реєстрації (ID, Username, Display name, Password, Confirm password, Email, Phone, Agreement), елементи входу та методи входу. Додаток працює в інтерфейсі без додаткової конфігурації.