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

Вхід користувачів через 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-sdkNodejs backend: casdoor-raw-js-example
Go backend: casdoor-go-react-sdk-example
SDK лише для фронтендуДля веб-сайтів SPA лише з фронтендомcasdoor-js-sdkcasdoor-react-only-example
React SDKДля веб-сайтів на Reactcasdoor-react-sdkNodejs backend: casdoor-nodejs-react-example
Java backend: casdoor-spring-security-react-example
Next.js SDKДля веб-сайтів на Next.jsnextjs-auth
Nuxt SDKДля веб-сайтів на Nuxtnuxt-auth
Vue SDKFor Vue websitescasdoor-vue-sdkcasdoor-python-vue-sdk-example
Angular SDKFor Angular websitescasdoor-angular-sdkcasdoor-nodejs-angular-example
Flutter SDKFor Flutter Web websitescasdoor-flutter-sdkcasdoor-flutter-example
ASP.NET SDKFor ASP.NET Blazor WASM websitesBlazor.BFF.OpenIDConnect.Templatecasdoor-dotnet-blazorwasm-oidc-example
Firebase SDKДля додатків Google Firebasecasdoor-firebase-example

SDK для веб-бекенду​

SDK для веб-бекендуОписКод SdkПриклад коду
Go SDKДля Go бекендівcasdoor-go-sdkcasdoor-go-react-sdk-example
Java SDKДля Java бекендівcasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example, quarkus-casdoor-auth (Quarkus)
Node.js SDKДля Node.js бекендівcasdoor-nodejs-sdkcasdoor-nodejs-react-example
Python SDKДля Python бекендівcasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
PHP SDKДля PHP бекендівcasdoor-php-sdkwordpress-casdoor-plugin
.NET SDKДля ASP.NET бекендівcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
Rust SDKДля Rust бекендівcasdoor-rust-sdkcasdoor-rust-example
C/C++ SDKДля C/C++ бекендівcasdoor-cpp-sdkcasdoor-cpp-qt-example
Dart SDKДля Dart бекендівcasdoor-dart-sdk
Ruby SDKДля Ruby бекендівcasdoor-ruby-sdk

Мобільні SDK​

Mobile SDKОписКод SDKПриклад коду
Android SDKДля Android додатківcasdoor-android-sdkcasdoor-android-example
iOS SDKДля iOS додатківcasdoor-ios-sdkcasdoor-ios-example
React Native SDKДля додатків React Nativecasdoor-react-native-sdkcasdoor-react-native-example
Flutter SDKДля Flutter додатківcasdoor-flutter-sdkcasdoor-flutter-example
Firebase SDKДля додатків Google Firebasecasdoor-firebase-example
Unity Games SDKДля 2D/3D ігор на Unity для ПК/мобільних пристроївcasdoor-dotnet-sdkcasdoor-unity-example
uni-app SDKДля додатків uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
порада

Мобільний додаток, який виконує автентифікацію користувачів нативно, без браузера, може використовувати grant за кодом підтвердження для входу через SMS або електронну пошту з автоматичною реєстрацією. Користувачі, які увійшли в систему, також можуть підтвердити QR-код на сторінці входу вашого сайту з додатку.

Настільні SDK​

Набір розробника для робочого столуОписКод SDKПриклад коду
Electron SDKДля додатків Electroncasdoor-js-sdkcasdoor-electron-example
.NET SDK для робочого столуДля .NET додатків для робочого столуcasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
C/C++ SDKДля C/C++ додатків для робочого столуcasdoor-cpp-sdkcasdoor-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:

  1. В адміністративній консолі Casdoor відкрийте сторінку Certs.

    Certs page with the list of certificates

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

    Certificate edit page with the public key

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

    Application edit page with the certificate selected

Налаштуйте фронтенд SDK​

  1. Встановіть casdoor-js-sdk за допомогою npm:

    npm install casdoor-js-sdk

    Або за допомогою Yarn:

    yarn add casdoor-js-sdk
  2. Визначте допоміжні функції у спільному файлі, наприклад, 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;
    }
  3. У вхідному файлі фронтенду, наприклад, 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);
  4. Обробіть маршрут зворотного виклику (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-адреси входу та реєстрації.

Отримайте та перевірте токен доступу​

Процес входу складається з трьох кроків:

  1. Користувач натискає посилання на вхід і потрапляє на сторінку входу 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
  2. Користувач вводить ім'я користувача та пароль і натискає Sign In, або натискає кнопку провайдера, наприклад, кнопку GitHub.

  3. 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
}
FieldDescription
UserThe user, with all profile fields. See User
AccessTokenThe access token string
jwt.RegisteredClaimsThe 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, використовуйте токен доступу напряму:

  1. Надішліть токен доступу на фронтенд і збережіть його там, наприклад, у localStorage браузера.
  2. Надсилайте токен доступу на бекенд із кожним запитом.
  3. На бекенді перевірте токен за допомогою ParseJwtToken() або вашої власної функції та прочитайте з нього дані про користувача, який увійшов у систему.

Керуйте користувачами через SDK​

Бекенд SDK обгортають Casdoor API. Ця частина не стосується OIDC або OAuth 2.0. Функції включають:

FunctionDescription
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​

FunctionDescription
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), елементи входу та методи входу. Додаток працює в інтерфейсі без додаткової конфігурації.

Див. також​