Passer au contenu principal

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.

conseil

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.

SDK MobileDescriptionCode SDKCode d'exemple
SDK AndroidPour les applications Androidcasdoor-android-sdkcasdoor-android-example
SDK iOSPour les applications iOScasdoor-ios-sdkcasdoor-ios-example
SDK React NativePour les applications React Nativecasdoor-react-native-sdkcasdoor-react-native-example
SDK FlutterPour les applications Fluttercasdoor-flutter-sdkcasdoor-flutter-example
SDK FirebasePour les applications Google Firebasecasdoor-firebase-example
SDK de jeux UnityPour les jeux PC/Mobile 2D/3D Unitycasdoor-dotnet-sdkcasdoor-unity-example
SDK uni-appPour les applications uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
SDK de bureauDescriptionCode SDKCode d'exemple
SDK ElectronPour les applications Electroncasdoor-js-sdkcasdoor-electron-example
SDK .NET de bureauPour les applications de bureau .NETcasdoor-dotnet-sdkWPF: 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-sdkcasdoor-cpp-qt-example
SDK de frontend WebDescriptionCode SDKCode d'exemple
SDK JavascriptPour les sites Web traditionnels non-SPAcasdoor-js-sdkBackend Nodejs : casdoor-raw-js-example
Backend Go : casdoor-go-react-sdk-example
SDK uniquement frontendPour les sites Web SPA uniquement frontendcasdoor-js-sdkcasdoor-react-only-example
SDK ReactPour les sites Web Reactcasdoor-react-sdkBackend Nodejs : casdoor-nodejs-react-example
Backend Java : casdoor-spring-security-react-example
SDK Next.jsPour les sites Web Next.jsnextjs-auth
SDK NuxtPour les sites Web 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 de backend WebDescriptionCode du SDKCode d'exemple
SDK GoPour les backends Gocasdoor-go-sdkcasdoor-go-react-sdk-example
SDK JavaPour les backends Javacasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
SDK Node.jsPour les backends Node.jscasdoor-nodejs-sdkcasdoor-nodejs-react-example
SDK PythonPour les backends Pythoncasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
SDK PHPPour les backends PHPcasdoor-php-sdkwordpress-casdoor-plugin
SDK .NETPour les backends ASP.NETcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
SDK RustPour les backends Rustcasdoor-rust-sdkcasdoor-rust-example
SDK C/C++Pour les backends C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
SDK DartPour les backends Dartcasdoor-dart-sdk
SDK RubyPour les backends Rubycasdoor-ruby-sdk

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

Using the SDK​

1. Configuration du SDK Backend​

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

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

ParamètreDoitDescription
point de terminaisonOuiURL du serveur Casdoor, comme https://door.casdoor.com ou http://localhost:8000
clientIdOuiID client pour l'application Casdoor
clientSecretOuiSecret client pour l'application Casdoor
jwtPublicKeyOuiLa clé publique pour le certificat de l'application Casdoor
organizationNameYesLe nom de l'organisation Casdoor
applicationNameNonLe nom de l'application Casdoor
conseil

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

Gestion des certificats

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

Édition des certificats

Then select the cert on the application edit page.

Sélection des certificats

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

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. 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);

(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. Obtenir les URL de connexion​

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

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. 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.