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

Casdoor SDKs

Вступ​

У порівнянні зі стандартним протоколом OIDC, Casdoor надає більше функціональності у своєму SDK, як управління користувачами, завантаження ресурсів тощо. Підключення до Casdoor через Casdoor SDK займає більше часу, ніж використання стандартної бібліотеки клієнта OIDC, але забезпечить найкращу гнучкість та найпотужніший API.

SDK Casdoor можна поділити на дві категорії:

  1. Frontend SDK: як Javascript SDK, Vue SDK для веб-сайтів, Android або iOS SDK для додатків тощо. Casdoor підтримує надання аутентифікації як для веб-сайтів, так і для мобільних додатків.
  2. Backend SDK: SDK для мов backend, таких як Go, Java, Node.js, Python, PHP тощо.
порада

Якщо ваш веб-сайт розроблений у вигляді окремих frontend та backend, то ви можете використовувати Javascript SDK: casdoor-js-sdk або React SDK: casdoor-react-sdk або Vue SDK: casdoor-vue-sdk для інтеграції Casdoor у frontend. Якщо ваш веб-додаток є традиційним веб-сайтом, розробленим за допомогою JSP або PHP, ви можете використовувати лише Backend SDK. Дивіться приклад: casdoor-python-vue-sdk-example

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
Набір розробника для робочого столуОписКод 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Приклад коду
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 SDKFor Google Firebase appscasdoor-firebase-example

Далі використовуйте один з наступних Backend SDK в залежності від мови вашого backend:

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
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 Casdoor, будь ласка, дивіться: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

Як користуватися SDK Casdoor?​

1. Конфігурація Backend SDK​

Коли ваш додаток запускається, вам потрібно ініціалізувати конфігурацію SDK Casdoor, викликавши функцію InitConfig() з необхідними параметрами. Візьміть як приклад casdoor-go-sdk: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

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 можна керувати на сторінці Certs як показано нижче.

Управління сертифікатами

Ви можете знайти публічний ключ на сторінці редагування сертифіката, скопіювати його або завантажити для SDK.

Редагування сертифікатів

Потім ви можете вибрати сертифікат на сторінці редагування додатку.

Вибір сертифікатів

2. Конфігурація Frontend​

Спочатку встановіть casdoor-js-sdk через NPM або Yarn:

npm install casdoor-js-sdk

Або:

yarn add casdoor-js-sdk

Потім визначте наступні утилітні функції (краще в глобальному JS файлі, як 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;
}

У вхідному файлі вашого frontend коду (як index.js або app.js у React), вам потрібно ініціалізувати casdoor-js-sdk, викликавши функцію InitConfig() з необхідними параметрами. Перші 4 параметри повинні використовувати те саме значення, що і Backend SDK Casdoor. Останній параметр redirectPath є відносним шляхом для переадресованої URL-адреси, повернутої зі сторінки входу Casdoor.

const config = {
  serverUrl: "https://door.casdoor.com",
  clientId: "014ae4bd048734ca2dea",
  organizationName: "casbin",
  appName: "app-casnode",
  redirectPath: "/callback",
};

xxx.initCasdoorSdk(config);

(Необов'язково) Оскільки ми використовуємо React як приклад, наш шлях /callback веде до маршруту React. Ми використовуємо наступний компонент React для отримання виклику /callback та відправки на backend. Цей крок можна ігнорувати, якщо ви переадресовуєтеся безпосередньо на backend (як у 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);

3. Отримання URL-адрес для входу​

Далі ви можете показати кнопки або посилання "Зареєструватися" та "Увійти" вашим користувачам. URL-адреси можна отримувати як на frontend, так і на backend. Дивіться більше деталей за адресою: /docs/basic/core-concepts#login-urls

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

Ось кроки:

  1. Користувач натискає на 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
  2. Користувач вводить ім'я користувача та пароль та натискає Sign In (або просто натискає кнопку входу через сторонній сервіс, як Sign in with GitHub).
  3. Користувач переадресовується назад у ваш додаток з авторизаційним кодом, виданим Casdoor (наприклад: https://forum.casbin.com?code=xxx&state=yyy), backend вашого додатку повинен обміняти авторизаційний код на токен доступу та перевірити, що токен доступу дійсний та виданий Casdoor. Функції GetOAuthToken() та ParseJwtToken() надаються Backend SDK Casdoor.

Наступний код показує, як отримати та перевірити токен доступу. Для реального прикладу Casnode (форумний веб-сайт, написаний на Go), дивіться: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

// 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() завершується без помилок, то користувач успішно увійшов до додатку. Повернуті claims можна використовувати для ідентифікації користувача пізніше.

4. Ідентифікація користувача за допомогою токена доступу​

інформація

Ця частина насправді є власною бізнес-логікою вашого додатку і не є частиною OIDC, OAuth або Casdoor. Ми просто надаємо хороші практики, оскільки багато людей не знають, що робити на наступному кроці.

У Casdoor токен доступу зазвичай ідентичний ID токену. Вони є одним і тим же. Отже, токен доступу містить всю інформацію про авторизованого користувача.

Змінна claims, повернута функцією ParseJwtToken(), визначена як:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: об'єкт користувача, що містить всю інформацію про авторизованого користувача, див. визначення за адресою: /docs/basic/core-concepts#user
  2. AccessToken: рядок токена доступу.
  3. jwt.RegisteredClaims: деякі інші значення, необхідні для JWT.

На цей момент додаток зазвичай має два способи запам'ятовування сесії користувача: session та JWT.

Session​

Метод встановлення сесії значно варіюється в залежності від мови та веб-фреймворку. Наприклад, 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​

accessToken, повернутий Casdoor, насправді є JWT. Отже, якщо ваш додаток використовує JWT для збереження сесії користувача, просто використовуйте токен доступу безпосередньо для цього:

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

5. (Необов'язково) Взаємодія з таблицею користувачів​

інформація

Ця частина надається Casdoor Public API і не є частиною OIDC або OAuth.

Casdoor Backend SDK надає багато допоміжних функцій, не обмежуючись:

  • GetUser(name string): отримати користувача за ім'ям користувача.
  • GetUsers(): отримати всіх користувачів.
  • AddUser(): додати користувача.
  • UpdateUser(): оновити користувача.
  • DeleteUser(): видалити користувача.
  • CheckUserPassword(auth.User): перевірити пароль користувача.

Ці функції реалізовані шляхом виконання RESTful викликів проти Casdoor Public API. Якщо функція не надається Backend SDK Casdoor, ви можете самостійно робити RESTful виклики.