Zum Hauptinhalt springen

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.

Tipp

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 SDKBeschreibungSDK-CodeBeispielcode
Android SDKFür Android-Appscasdoor-android-sdkcasdoor-android-example
iOS SDKFür iOS-Appscasdoor-ios-sdkcasdoor-ios-example
React Native SDKFür React Native-Appscasdoor-react-native-sdkcasdoor-react-native-example
Flutter SDKFür Flutter-Appscasdoor-flutter-sdkcasdoor-flutter-example
Firebase SDKFür Google Firebase-Appscasdoor-firebase-example
Unity Games SDKFür Unity 2D/3D PC/Mobile-Spielecasdoor-dotnet-sdkcasdoor-unity-example
uni-app SDKFür uni-app-Appscasdoor-uniapp-sdkcasdoor-uniapp-example
Desktop SDKBeschreibungSDK-CodeBeispielcode
Electron SDKFür Electron-Appscasdoor-js-sdkcasdoor-electron-example
.NET Desktop SDKFür .NET-Desktop-Appscasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
C/C++ SDKFür C/C++-Desktop-Appscasdoor-cpp-sdkcasdoor-cpp-qt-example
Web-Frontend-SDKBeschreibungSDK-CodeBeispielcode
Javascript SDKFür traditionelle Nicht-SPA-Websitescasdoor-js-sdkNodejs-Backend: casdoor-raw-js-example
Go-Backend: casdoor-go-react-sdk-example
Frontend-only SDKFür Frontend-only-SPA-Websitescasdoor-js-sdkcasdoor-react-only-example
React SDKFür React-Websitescasdoor-react-sdkNodejs-Backend: casdoor-nodejs-react-example
Java-Backend: casdoor-spring-security-react-example
Next.js SDKFür Next.js-Websitesnextjs-auth
Nuxt SDKFür Nuxt-Websitesnuxt-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:

Web-Backend-SDKBeschreibungSDK-CodeBeispielcode
Go SDKFür Go-Backendscasdoor-go-sdkcasdoor-go-react-sdk-example
Java SDKFür Java-Backendscasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
Node.js SDKFür Node.js-Backendscasdoor-nodejs-sdkcasdoor-nodejs-react-example
Python SDKFür Python-Backendscasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
PHP SDKFür PHP-Backendscasdoor-php-sdkwordpress-casdoor-plugin
.NET SDKFür ASP.NET-Backendscasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
Rust SDKFür Rust-Backendscasdoor-rust-sdkcasdoor-rust-example
C/C++ SDKFür C/C++-Backendscasdoor-cpp-sdkcasdoor-cpp-qt-example
Dart SDKFür Dart-Backendscasdoor-dart-sdk
Ruby SDKFür Ruby-Backendscasdoor-ruby-sdk

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

Using the SDK​

1. Backend SDK-Konfiguration​

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

Alle Parameter für InitConfig() werden wie folgt erklärt:

ParameterMussBeschreibung
EndpunktJaCasdoor Server-URL, wie https://door.casdoor.com oder http://localhost:8000
clientIdJaClient-ID für die Casdoor-Anwendung
clientSecretJaClient-Geheimnis für die Casdoor-Anwendung
jwtPublicKeyJaDer öffentliche Schlüssel für das Zertifikat der Casdoor-Anwendung
organizationNameYesDer Name für die Casdoor-Organisation
applicationNameNeinDer Name für die Casdoor-Anwendung
Tipp

Der jwtPublicKey kann auf der Seite Certs wie unten verwaltet werden.

Zertifikatsverwaltung

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

Zertifikatsbearbeitung

Then select the cert on the application edit page.

Zertifikatsauswahl

2. Frontend-Konfiguration​

Zuerst installieren Sie casdoor-js-sdk über NPM oder Yarn:

npm install casdoor-js-sdk

Oder:

yarn add casdoor-js-sdk

Dann definieren Sie die folgenden Hilfsfunktionen (besser in einer globalen JS-Datei wie 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. Die ersten 4 Parameter sollten denselben Wert wie das Casdoor Backend SDK verwenden. Der letzte Parameter redirectPath ist der relative Pfad für die umgeleitete URL, die von der Login-Seite von Casdoor zurückgegeben wird.

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. Login-URLs erhalten​

Show "Sign up" and "Sign in" buttons or links to users; URLs can be obtained from the frontend or backend. See Login URLs.

4. Zugriffstoken abrufen und überprüfen​

Hier sind die Schritte:

  1. Der Benutzer klickt auf die Login-URL und wird zur Login-Seite von Casdoor weitergeleitet, wie: 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. Der Benutzer gibt Benutzernamen & Passwort ein und klickt auf Sign In (oder klickt einfach auf den Button für den Login über Drittanbieter wie Sign in with GitHub).
  3. Der Benutzer wird mit dem von Casdoor ausgestellten Autorisierungscode zurück zu Ihrer Anwendung umgeleitet (wie: https://forum.casbin.com?code=xxx&state=yyy), das Backend Ihrer Anwendung muss den Autorisierungscode mit dem Zugriffstoken austauschen und überprüfen, dass das Zugriffstoken gültig ist und von Casdoor ausgestellt wurde. Die Funktionen GetOAuthToken() und ParseJwtToken() werden vom Casdoor Backend SDK bereitgestellt.

Der folgende Code zeigt, wie man das Zugriffstoken abruft und überprüft. 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)
}

Wenn ParseJwtToken() ohne Fehler abgeschlossen wird, hat sich der Benutzer erfolgreich in der Anwendung angemeldet. Die zurückgegebenen claims können später verwendet werden, um den Benutzer zu identifizieren.

4. Benutzer mit Zugriffstoken identifizieren​

Info

Dieser Teil ist eigentlich die eigene Geschäftslogik Ihrer Anwendung und nicht Teil von OIDC, OAuth oder Casdoor. Wir bieten nur bewährte Praktiken, da viele Leute nicht wissen, was sie als nächsten Schritt tun sollen.

In Casdoor ist das Zugriffstoken normalerweise identisch mit dem ID-Token. Sie sind dasselbe. Also enthält das Zugriffstoken alle Informationen für den eingeloggten Benutzer.

Die Variable claims, die von ParseJwtToken() zurückgegeben wird, ist definiert als:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: das User-Objekt, das alle Informationen für den eingeloggten Benutzer enthält, siehe Definition unter: /docs/basic/core-concepts#user
  2. AccessToken: der Zugriffstoken-String.
  3. jwt.RegisteredClaims: einige andere Werte, die von JWT benötigt werden.

In diesem Moment hat die Anwendung normalerweise zwei Möglichkeiten, die Benutzersitzung zu speichern: session und JWT.

Session​

Die Methode zum Setzen der Sitzung variiert stark je nach Sprache und Web-Framework. Z.B. verwendet Casnode das Beego Web-Framework und setzt die Sitzung durch Aufrufen von: 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​

Das von Casdoor zurückgegebene accessToken ist tatsächlich ein JWT. Wenn Ihre Anwendung JWT verwendet, um die Benutzersitzung zu halten, verwenden Sie einfach das Zugriffstoken direkt dafür:

  1. Senden Sie das Zugriffstoken an das Frontend, speichern Sie es an Orten wie dem localStorage des Browsers.
  2. Lassen Sie den Browser das Zugriffstoken für jede Anfrage an das Backend senden.
  3. Rufen Sie ParseJwtToken() oder Ihre eigene Funktion auf, um das Zugriffstoken zu überprüfen und Informationen über den eingeloggten Benutzer in Ihrem Backend zu erhalten.

5. (Optional) Interaktion mit der Benutzertabelle​

Info

Dieser Teil wird von Casdoor Public API bereitgestellt und ist nicht Teil von OIDC oder OAuth.

Casdoor Backend SDK bietet viele Hilfsfunktionen, nicht nur beschränkt auf:

  • GetUser(name string): einen Benutzer anhand des Benutzernamens abrufen.
  • GetUsers(): alle Benutzer abrufen.
  • AddUser(): einen Benutzer hinzufügen.
  • UpdateUser(): einen Benutzer aktualisieren.
  • DeleteUser(): einen Benutzer löschen.
  • CheckUserPassword(auth.User): Passwort des Benutzers überprüfen.

Diese Funktionen werden implementiert, indem RESTful-Aufrufe gegen Casdoor Public API gemacht werden. 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.