Перейти к основному содержанию

Casdoor SDKs

Введение​

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

SDK Casdoor можно разделить на две категории:

  1. Фронтенд SDK: Как Javascript SDK, Vue SDK для веб-сайтов, Android или iOS SDK для приложений и т.д. Casdoor поддерживает предоставление аутентификации как для веб-сайтов, так и для мобильных приложений.
  2. Бэкенд SDK: SDK для бэкенд языков, таких как Go, Java, Node.js, Python, PHP и т.д.
совет

Если ваш сайт разработан в разделенном на фронтенд и бэкенд стиле, тогда вы можете использовать Javascript SDK: casdoor-js-sdk или React SDK: casdoor-react-sdk или Vue SDK: casdoor-vue-sdk для интеграции Casdoor во фронтенд. Если ваше веб-приложение - это традиционный сайт, разработанный на JSP или PHP, вы можете просто использовать только бэкенд SDK. Смотрите пример: casdoor-python-vue-sdk-example

Мобильный SDKОписаниеКод SDKПример кода
Android SDKДля приложений Androidcasdoor-android-sdkcasdoor-android-example
iOS SDKДля приложений iOScasdoor-ios-sdkcasdoor-ios-example
React Native SDKДля приложений React Nativecasdoor-react-native-sdkcasdoor-react-native-example
Flutter SDKДля приложений Fluttercasdoor-flutter-sdkcasdoor-flutter-example
Firebase SDKДля приложений Google Firebasecasdoor-firebase-example
Unity Games SDKДля игр Unity 2D/3D на ПК/мобильных устройствахcasdoor-dotnet-sdkcasdoor-unity-example
uni-app SDKДля приложений uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
Desktop SDKОписаниеКод SDKПример кода
Electron SDKДля приложений Electroncasdoor-js-sdkcasdoor-electron-example
.NET Desktop SDKДля .NET desktop приложенийcasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
C/C++ SDKДля C/C++ desktop приложенийcasdoor-cpp-sdkcasdoor-cpp-qt-example
Web frontend SDKОписаниеКод SDKПример кода
Javascript SDKДля традиционных не-SPA веб-сайтовcasdoor-js-sdkNodejs backend: casdoor-raw-js-example
Go backend: casdoor-go-react-sdk-example
Frontend-only 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

Затем используйте один из следующих SDK для бэкенда на основе языка вашего бэкенда:

Web 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.jscasdoor-nodejs-sdkcasdoor-nodejs-react-example
Python SDKДля бэкендов Pythoncasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
PHP SDKДля бэкендов PHPcasdoor-php-sdkwordpress-casdoor-plugin
.NET SDKДля бэкендов ASP.NETcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
Rust SDKДля бэкендов Rustcasdoor-rust-sdkcasdoor-rust-example
C/C++ SDKДля бэкендов C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
Dart SDKДля бэкендов Dartcasdoor-dart-sdk
Ruby SDKДля бэкендов Rubycasdoor-ruby-sdk

Для полного списка официальных SDK Casdoor, пожалуйста, смотрите: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

Как использовать SDK Casdoor?​

1. Конфигурация SDK на стороне сервера​

Когда ваше приложение запускается, вам нужно инициализировать конфигурацию Casdoor SDK, вызвав функцию 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() объясняются следующим образом:

ПараметрДолженОписание
конечная точкаДаURL сервера Casdoor, например https://door.casdoor.com или http://localhost:8000
clientIdДаID клиента для приложения Casdoor
clientSecretДаСекрет клиента для приложения Casdoor
jwtPublicKeyДаОткрытый ключ для сертификата приложения Casdoor
organizationNameДаНазвание для организации Casdoor
applicationNameНетНазвание для приложения Casdoor
совет

jwtPublicKey можно управлять на странице Certs ниже.

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

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

Редактирование сертификатов

Затем вы можете выбрать сертификат на странице редактирования приложения.

Выбор сертификатов

2. Конфигурация на стороне клиента​

Сначала установите 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;
}

В файле входа вашего фронтенд-кода (например, index.js или app.js в React), вам нужно инициализировать casdoor-js-sdk, вызвав функцию InitConfig() с необходимыми параметрами. Первые 4 параметра должны использовать то же значение, что и бэкенд 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 и отправки его на бэкенд. Вы можете проигнорировать этот шаг, если перенаправляете на бэкенд напрямую (как в 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-ы могут быть получены как на фронтенде, так и на бэкенде. Подробнее смотрите по адресу: /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. Пользователь вводит имя пользователя и пароль и нажимает Войти (или просто нажимает кнопку входа через стороннего поставщика, например, Войти через GitHub).
  3. Пользователь перенаправляется обратно в ваше приложение с кодом авторизации, выданным Casdoor (например: https://forum.casbin.com?code=xxx&state=yyy), бэкенд вашего приложения должен обменять код авторизации на токен доступа и проверить, что токен доступа действителен и выдан Casdoor. Функции GetOAuthToken() и ParseJwtToken() предоставляются бэкенд 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: объект User, содержащий всю информацию для вошедшего в систему пользователя, см. определение по адресу: /docs/basic/core-concepts#user
  2. AccessToken: строка токена доступа.
  3. jwt.RegisteredClaims: некоторые другие значения, требуемые JWT.

На данный момент приложение обычно имеет два способа запомнить сессию пользователя: session и JWT.

Session​

Метод установки сессии сильно варьируется в зависимости от языка и веб-фреймворка. Например, Casnode использует Beego web framework и устанавливает сессию, вызывая: 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. Отправьте токен доступа на клиентскую сторону, сохраните его в таких местах, как localStorage браузера.
  2. Позвольте браузеру отправлять токен доступа на бэкенд для каждого запроса.
  3. Вызовите ParseJwtToken() или вашу собственную функцию для проверки токена доступа и получения информации о вошедшем в систему пользователе на вашем бэкенде.

5. (Необязательно) Взаимодействие с таблицей пользователей​

информация

Эта часть предоставляется Casdoor Public API и не является частью OIDC или OAuth.

Casdoor Backend SDK предоставляет множество вспомогательных функций, не ограничиваясь:

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

Эти функции реализованы путем выполнения RESTful вызовов к Casdoor Public API. Если функция не предоставлена в Casdoor Backend SDK, вы можете сделать RESTful вызовы самостоятельно.