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

Casdoor SDKs

Overview​

Casdoor SDKs extend standard OIDC with user management, resource uploads, and other features. They take a bit more setup than a generic OIDC client but give you the full Casdoor API.

Frontend SDKs — For web (JavaScript, React, Vue, etc.) and mobile (Android, iOS, React Native, Flutter).
Backend SDKs — For Go, Java, Node.js, Python, PHP, .NET, Rust, C++, and more.

порада

For a frontend/backend split, use a frontend SDK (e.g. casdoor-js-sdk, casdoor-react-sdk, casdoor-vue-sdk) in the UI and a backend SDK for token validation and API calls. For a traditional server-rendered app (JSP, PHP), a backend SDK may be enough. Example: 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

Pair the frontend with a backend SDK in your server’s language:

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

All official SDKs: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=.

Using the SDK​

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

On startup, call the SDK’s init function with your Casdoor endpoint, client ID, client secret, and (for JWT validation) the public key. Example with 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
organizationNameYesНазва для організації Casdoor
applicationNameНіНазва для додатку Casdoor
порада

jwtPublicKey можна керувати на сторінці Certs як показано нижче.

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

Copy or download the public key from the certificate edit page for use in the SDK.

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

Then select the cert on the application edit page.

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

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;
}

In your frontend entry file (e.g. index.js or app.js in React), initialize the casdoor-js-sdk by calling InitConfig() with the required parameters. Перші 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);

(Optional) This example uses React; the /callback route is handled by the component below, which forwards the call to the backend. Skip this if your callback goes directly to the backend (e.g. JSP or 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-адрес для входу​

Show "Sign up" and "Sign in" buttons or links to users; URLs can be obtained from the frontend or backend. See 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.

Наступний код показує, як отримати та перевірити токен доступу. For a real example of Casnode (a forum website written in Go), see: 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. If a function is not in the Casdoor Backend SDK, call the Public API directly.

6. (Optional) Manage Applications via SDK​

Casdoor SDKs also provide functions to manage applications programmatically:

  • AddApplication(): create a new application.
  • GetApplication(name string): get an application by name.
  • GetApplications(): get all applications.
  • UpdateApplication(): update an application.
  • DeleteApplication(): delete an application.

When creating applications via SDK using AddApplication(), Casdoor automatically initializes essential fields with sensible defaults. This includes signup items (ID, Username, Display name, Password, Confirm password, Email, Phone, Agreement), signin items, and signin methods. This ensures applications created programmatically work correctly in the UI without requiring manual configuration of these basic settings.