Zum Hauptinhalt springen

Casdoor SDKs

Einführung

Im Vergleich zum Standard-OIDC-Protokoll bietet Casdoor mehr Funktionalitäten in seinem SDK, wie Benutzerverwaltung, Ressourcen-Upload usw. Die Verbindung zu Casdoor über Casdoor SDK dauert länger als die Verwendung einer Standard-OIDC-Clientbibliothek, bietet aber die beste Flexibilität und die leistungsfähigste API.

Casdoor SDKs können in zwei Kategorien unterteilt werden:

  1. Frontend SDK: Wie Javascript SDK, Vue SDK für Websites, Android oder iOS SDKs für Apps usw. Casdoor unterstützt die Bereitstellung von Authentifizierung sowohl für Websites als auch für mobile Apps.
  2. Backend SDK: SDKs für Backend-Sprachen wie Go, Java, Node.js, Python, PHP usw.
Tipp

Wenn Ihre Website in einer getrennten Frontend- und Backend-Weise entwickelt wurde, dann können Sie das Javascript SDK: casdoor-js-sdk oder React SDK: casdoor-react-sdk oder Vue SDK: casdoor-vue-sdk verwenden, um Casdoor im Frontend zu integrieren. Wenn Ihre Webanwendung eine traditionelle Website ist, die mit JSP oder PHP entwickelt wurde, können Sie einfach nur die Backend-SDKs verwenden. Siehe ein Beispiel: 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 SDK | Für Vue-Websites | casdoor-vue-sdk | casdoor-python-vue-sdk-example |

Als Nächstes verwenden Sie eines der folgenden Backend-SDKs, basierend auf der Sprache Ihres Backends:

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

Für eine vollständige Liste der offiziellen Casdoor SDKs, siehe: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

Wie verwendet man das Casdoor SDK?

1. Backend SDK-Konfiguration

Wenn Ihre Anwendung startet, müssen Sie die Casdoor SDK-Konfiguration initialisieren, indem Sie die Funktion InitConfig() mit den erforderlichen Parametern aufrufen. Nehmen Sie casdoor-go-sdk als Beispiel: 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
organizationNameJaDer 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

Sie können den öffentlichen Schlüssel auf der Zertifikatsbearbeitungsseite finden, ihn kopieren oder für das SDK herunterladen.

Zertifikatsbearbeitung

Dann können Sie das Zertifikat auf der Anwendungsbearbeitungsseite auswählen.

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 der Eingabedatei Ihres Frontend-Codes (wie index.js oder app.js in React) müssen Sie das casdoor-js-sdk initialisieren, indem Sie die Funktion InitConfig() mit den erforderlichen Parametern aufrufen. 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) Da wir React als Beispiel verwenden, trifft unser /callback-Pfad auf die React-Route. Wir verwenden die folgende React-Komponente, um den /callback-Aufruf zu empfangen und an das Backend zu senden. Sie können diesen Schritt ignorieren, wenn Sie direkt zum Backend umleiten (wie in JSP oder 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

Als Nächstes können Sie Ihren Benutzern die Schaltflächen oder Links "Registrieren" und "Anmelden" anzeigen. Die URLs können entweder im Frontend oder Backend abgerufen werden. Weitere Details finden Sie unter: /docs/basic/core-concepts#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. Für ein echtes Beispiel von Casnode (eine Forum-Website geschrieben in Go), siehe: 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. Wenn eine Funktion nicht im Casdoor Backend SDK bereitgestellt wird, können Sie RESTful-Aufrufe selbst machen.