Casdoor SDKs

Introduction

Comparé au protocole OIDC standard, Casdoor fournit plus de fonctionnalités dans son SDK, comme la gestion des utilisateurs, le téléchargement de ressources, etc. Se connecter à Casdoor via Casdoor SDK prend plus de temps que d'utiliser une bibliothèque cliente OIDC standard mais fournira la meilleure flexibilité et l'API la plus puissante.

Les SDK Casdoor peuvent être divisés en deux catégories :

1. SDK Frontend : Comme le SDK Javascript, le SDK Vue pour les sites web, les SDK Android ou iOS pour les applications, etc. Casdoor prend en charge l'authentification pour les sites web et les applications mobiles.
2. SDK Backend : SDK pour les langages backend comme Go, Java, Node.js, Python, PHP, etc.

conseil

Si votre site web est développé de manière séparée entre le frontend et le backend, alors vous pouvez utiliser le SDK Javascript : casdoor-js-sdk ou le SDK React : casdoor-react-sdk ou le SDK Vue : casdoor-vue-sdk pour intégrer Casdoor en frontend. Si votre application web est un site web traditionnel développé par JSP ou PHP, vous pouvez simplement utiliser uniquement les SDK backend. Voir un exemple : casdoor-python-vue-sdk-example

SDK Mobile	Description	Code SDK	Code d'exemple
SDK Android	Pour les applications Android	casdoor-android-sdk	casdoor-android-example
SDK iOS	Pour les applications iOS	casdoor-ios-sdk	casdoor-ios-example
SDK React Native	Pour les applications React Native	casdoor-react-native-sdk	casdoor-react-native-example
SDK Flutter	Pour les applications Flutter	casdoor-flutter-sdk	casdoor-flutter-example
SDK Firebase	Pour les applications Google Firebase		casdoor-firebase-example
SDK de jeux Unity	Pour les jeux PC/Mobile 2D/3D Unity	casdoor-dotnet-sdk	casdoor-unity-example
SDK uni-app	Pour les applications uni-app	casdoor-uniapp-sdk	casdoor-uniapp-example

SDK de bureau	Description	Code SDK	Code d'exemple
SDK Electron	Pour les applications Electron	casdoor-js-sdk	casdoor-electron-example
SDK .NET de bureau	Pour les applications de bureau .NET	casdoor-dotnet-sdk	WPF: casdoor-dotnet-desktop-example WinForms: casdoor-dotnet-winform-example Avalonia UI: casdoor-dotnet-avalonia-example
SDK C/C++	Pour les applications de bureau C/C++	casdoor-cpp-sdk	casdoor-cpp-qt-example

SDK de frontend Web	Description	Code SDK	Code d'exemple
SDK Javascript	Pour les sites Web traditionnels non-SPA	casdoor-js-sdk	Backend Nodejs : casdoor-raw-js-example Backend Go : casdoor-go-react-sdk-example
SDK uniquement frontend	Pour les sites Web SPA uniquement frontend	casdoor-js-sdk	casdoor-react-only-example
SDK React	Pour les sites Web React	casdoor-react-sdk	Backend Nodejs : casdoor-nodejs-react-example Backend Java : casdoor-spring-security-react-example
SDK Next.js	Pour les sites Web Next.js		nextjs-auth
SDK Nuxt	Pour les sites Web 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	For Google Firebase apps		casdoor-firebase-example

Ensuite, utilisez l'un des SDK backend suivants en fonction du langage de votre backend :

SDK de backend Web	Description	Code du SDK	Code d'exemple
SDK Go	Pour les backends Go	casdoor-go-sdk	casdoor-go-react-sdk-example
SDK Java	Pour les backends Java	casdoor-java-sdk	casdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
SDK Node.js	Pour les backends Node.js	casdoor-nodejs-sdk	casdoor-nodejs-react-example
SDK Python	Pour les backends Python	casdoor-python-sdk	Flask: casdoor-python-vue-sdk-example Django: casdoor-django-js-sdk-example FastAPI: casdoor-fastapi-js-sdk-example
SDK PHP	Pour les backends PHP	casdoor-php-sdk	wordpress-casdoor-plugin
SDK .NET	Pour les backends ASP.NET	casdoor-dotnet-sdk	casdoor-dotnet-sdk-example
SDK Rust	Pour les backends Rust	casdoor-rust-sdk	casdoor-rust-example
SDK C/C++	Pour les backends C/C++	casdoor-cpp-sdk	casdoor-cpp-qt-example
SDK Dart	Pour les backends Dart	casdoor-dart-sdk
SDK Ruby	Pour les backends Ruby	casdoor-ruby-sdk

Pour une liste complète des SDK Casdoor officiels, veuillez voir : https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

Comment utiliser le SDK Casdoor ?

1. Configuration du SDK Backend

Lorsque votre application démarre, vous devez initialiser la configuration du SDK Casdoor en appelant la fonction InitConfig() avec les paramètres requis. Prenez casdoor-go-sdk comme exemple : 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)
}

Tous les paramètres pour InitConfig() sont expliqués comme suit :

Paramètre	Doit	Description
point de terminaison	Oui	URL du serveur Casdoor, comme https://door.casdoor.com ou http://localhost:8000
clientId	Oui	ID client pour l'application Casdoor
clientSecret	Oui	Secret client pour l'application Casdoor
jwtPublicKey	Oui	La clé publique pour le certificat de l'application Casdoor
organizationName	Oui	Le nom de l'organisation Casdoor
applicationName	Non	Le nom de l'application Casdoor

conseil

Le jwtPublicKey peut être géré dans la page Certs comme ci-dessous.

Vous pouvez trouver la clé publique dans la page d'édition du certificat, la copier ou la télécharger pour le sdk.

Ensuite, vous pouvez sélectionner le certificat dans la page d'édition de l'application.

2. Configuration Frontend

Tout d'abord, installez casdoor-js-sdk via NPM ou Yarn :

npm install casdoor-js-sdk

Ou :

yarn add casdoor-js-sdk

Ensuite, définissez les fonctions utilitaires suivantes (de préférence dans un fichier JS global comme 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;
}

Dans le fichier d'entrée de votre code frontend (comme index.js ou app.js dans React), vous devez initialiser le casdoor-js-sdk en appelant la fonction InitConfig() avec les paramètres requis. Les 4 premiers paramètres doivent utiliser la même valeur que le SDK backend Casdoor. Le dernier paramètre redirectPath est le chemin relatif pour l'URL redirigée, retournée par la page de connexion de Casdoor.

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

xxx.initCasdoorSdk(config);

(Optionnel) Parce que nous utilisons React comme exemple, notre chemin /callback atteint la route React. Nous utilisons le composant React suivant pour recevoir l'appel /callback et l'envoyer au backend. Vous pouvez ignorer cette étape si vous redirigez directement vers le backend (comme dans JSP ou 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. Obtenir les URL de connexion

Ensuite, vous pouvez montrer les boutons ou liens "S'inscrire" et "Se connecter" à vos utilisateurs. Les URL peuvent être récupérées soit dans le frontend soit dans le backend. Voir plus de détails à : /docs/basic/core-concepts#login-urls

4. Obtenir et vérifier le jeton d'accès

Voici les étapes :

1. L'utilisateur clique sur l'URL de connexion et est redirigé vers la page de connexion de Casdoor, comme : 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. L'utilisateur entre le nom d'utilisateur et le mot de passe et clique sur Sign In (ou clique simplement sur le bouton de connexion tiers comme Sign in with GitHub).
3. L'utilisateur est redirigé vers votre application avec le code d'autorisation émis par Casdoor (comme : https://forum.casbin.com?code=xxx&state=yyy), le backend de votre application doit échanger le code d'autorisation avec le jeton d'accès et vérifier que le jeton d'accès est valide et émis par Casdoor. Les fonctions GetOAuthToken() et ParseJwtToken() sont fournies par le SDK backend Casdoor.

Le code suivant montre comment obtenir et vérifier le jeton d'accès. Pour un exemple réel de Casnode (un site web de forum écrit en Go), voir : 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)
}

Si ParseJwtToken() se termine sans erreur, alors l'utilisateur s'est connecté avec succès à l'application. Les claims retournés peuvent être utilisés pour identifier l'utilisateur plus tard.

4. Identifier l'utilisateur avec le jeton d'accès

info

Cette partie est en fait la propre logique métier de votre application et ne fait pas partie d'OIDC, OAuth ou Casdoor. Nous fournissons juste de bonnes pratiques car beaucoup de gens ne savent pas quoi faire pour l'étape suivante.

Dans Casdoor, le jeton d'accès est généralement identique au jeton ID. Ce sont la même chose. Ainsi, le jeton d'accès contient toutes les informations pour l'utilisateur connecté.

La variable claims retournée par ParseJwtToken() est définie comme :

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}

1. User : l'objet Utilisateur, contenant toutes les informations pour l'utilisateur connecté, voir la définition à : /docs/basic/core-concepts#user
2. AccessToken : la chaîne de jeton d'accès.
3. jwt.RegisteredClaims : certaines autres valeurs requises par JWT.

À ce moment, l'application a généralement deux façons de se souvenir de la session utilisateur : session et JWT.

Session

La méthode pour définir la session varie grandement en fonction du langage et du framework web. Par exemple, Casnode utilise le framework web Beego et définit la session en appelant : 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

Le accessToken retourné par Casdoor est en fait un JWT. Donc, si votre application utilise JWT pour conserver la session utilisateur, utilisez simplement le jeton d'accès directement pour cela :

1. Envoyez le jeton d'accès au frontend, sauvegardez-le dans des endroits comme localStorage du navigateur.
2. Laissez le navigateur envoyer le jeton d'accès au backend pour chaque requête.
3. Appelez ParseJwtToken() ou votre propre fonction pour vérifier le jeton d'accès et obtenir les informations de l'utilisateur connecté dans votre backend.

5. (Optionnel) Interagir avec la table des utilisateurs

info

Cette partie est fournie par Casdoor Public API et ne fait pas partie de l'OIDC ou de l'OAuth.

Casdoor Backend SDK fournit beaucoup de fonctions d'aide, non limitées à :

• GetUser(name string) : obtenir un utilisateur par nom d'utilisateur.
• GetUsers() : obtenir tous les utilisateurs.
• AddUser() : ajouter un utilisateur.
• UpdateUser() : mettre à jour un utilisateur.
• DeleteUser() : supprimer un utilisateur.
• CheckUserPassword(auth.User) : vérifier le mot de passe de l'utilisateur.

Ces fonctions sont implémentées en effectuant des appels RESTful contre Casdoor Public API. Si une fonction n'est pas fournie dans Casdoor Backend SDK, vous pouvez effectuer des appels RESTful par vous-même.