Zum Hauptinhalt springen

Benutzer mit einem Casdoor SDK anmelden

Dieser Leitfaden listet die Casdoor SDKs auf und erklärt, wie man Benutzer über ein Frontend-SDK und ein Backend-SDK in einer Web-Anwendung anmeldet. Die Beispiele verwenden casdoor-js-sdk und casdoor-go-sdk. Die anderen SDKs folgen denselben Schritten.

Lernziele​

  • Wählen Sie die SDKs für Ihre Plattform aus.
  • Konfigurieren Sie das Backend-SDK und das Frontend-SDK.
  • Tauschen Sie den Autorisierungscode gegen ein Access Token aus und überprüfen Sie das Token.
  • Halten Sie den Benutzer in Ihrer Anwendung angemeldet.
  • Verwalten Sie Benutzer und Anwendungen über das SDK.

Voraussetzungen​

  • Eine laufende Casdoor-Instanz
  • Eine Anwendung in Casdoor, mit der Callback-URL Ihrer Anwendung in Redirect URLs
  • Die Client ID und das Client Secret der Anwendung sowie der öffentliche Schlüssel ihres Zertifikats

Über die SDKs​

Die Casdoor SDKs basieren auf OpenID Connect (OIDC) und fügen Funktionen der Casdoor API hinzu, wie Benutzerverwaltung und Datei-Upload. Sie erfordern etwas mehr Einrichtung als ein standardmäßiger OIDC-Client und bieten Ihnen die volle Casdoor API.

  • Frontend SDKs: Für Web-Frontends, mobile Apps und Desktop-Apps. Sie erstellen die Anmelde-URL und verarbeiten den Callback in der UI.
  • Backend SDKs: Für Ihren Server. Sie tauschen den Autorisierungscode aus, verifizieren Tokens und rufen die Casdoor API auf.

Wenn Ihre Anwendung ein separates Frontend und Backend hat, verwenden Sie ein Frontend-SDK in der UI und ein Backend-SDK auf dem Server. Ein Beispiel finden Sie unter casdoor-python-vue-sdk-example. Wenn Ihre Anwendung Seiten serverseitig rendert, wie JSP- und PHP-Anwendungen, kann ein Backend-SDK allein ausreichend sein.

SDK auswählen​

Alle offiziellen SDKs befinden sich in der casdoor Organisation auf GitHub.

Web-Frontend-SDKs​

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 SDKFür Google Firebase-Appscasdoor-firebase-example

Web-Backend-SDKs​

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, quarkus-casdoor-auth (Quarkus)
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

Mobile SDKs​

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
Tipp

Eine mobile App, die Benutzer nativ ohne Browser anmeldet, kann den verification code grant für die Anmeldung per SMS oder E-Mail mit automatischer Registrierung verwenden. Angemeldete Benutzer können auch den QR-Code auf der Anmeldeseite Ihrer Website über die App genehmigen.

Desktop-SDKs​

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

Backend-SDK konfigurieren​

Wenn Ihr Backend startet, initialisieren Sie das SDK mit der Adresse von Casdoor und den Anmeldeinformationen der Anwendung. Mit casdoor-go-sdk:

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() akzeptiert die folgenden Parameter:

KonfigurationsparameterMussBeschreibung
EndpunktJaCasdoor Server URL, like https://door.casdoor.com or 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

So erhalten Sie den Wert von jwtPublicKey:

  1. Öffnen Sie in der Casdoor-Admin-Konsole die Seite Certs.

    Certs page with the list of certificates

  2. Öffnen Sie das Zertifikat und kopieren oder laden Sie dessen öffentlichen Schlüssel herunter.

    Certificate edit page with the public key

  3. Wählen Sie auf der Bearbeitungsseite der Anwendung dasselbe Zertifikat unter Cert aus.

    Application edit page with the certificate selected

Frontend-SDK konfigurieren​

  1. Installieren Sie casdoor-js-sdk mit npm:

    npm install casdoor-js-sdk

    Oder mit Yarn:

    yarn add casdoor-js-sdk

  2. Definieren Sie Hilfsfunktionen in einer gemeinsamen Datei, z. B. 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;
    }

  3. Initialisieren Sie das SDK in der Einstiegsdatei des Frontends, z. B. index.js oder app.js in React. Verwenden Sie dieselben Werte für die ersten vier Einstellungen wie im Backend-SDK. redirectPath ist der Pfad Ihrer Anwendung, zu dem Casdoor den Benutzer nach der Anmeldung zurückleitet.

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

    xxx.initCasdoorSdk(config);

  4. Behandeln Sie die Callback-Route. In diesem React-Beispiel verarbeitet eine Komponente /callback und leitet den Code an das Backend weiter. Überspringen Sie diesen Schritt, wenn Casdoor direkt an Ihr Backend weiterleitet, wie es bei JSP- und PHP-Anwendungen der Fall ist.

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

Stellen Sie Benutzern eine Sign in- und eine Sign up-Schaltfläche oder einen Link bereit. Rufen Sie die URLs vom Frontend-SDK oder Backend-SDK ab. Siehe URLs für Anmeldung und Registrierung.

Zugriffstoken abrufen und überprüfen​

Der Anmeldeablauf umfasst drei Schritte:

  1. Der Benutzer klickt auf den Anmelde-Link und gelangt zur Casdoor-Anmeldeseite, zum Beispiel:

    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 einen Benutzernamen und ein Passwort ein und klickt auf Sign In, oder klickt auf die Schaltfläche eines Providers, z. B. die GitHub-Schaltfläche.

  3. Casdoor leitet den Benutzer mit einem Autorisierungscode an Ihre Anwendung weiter, zum Beispiel https://forum.casbin.com?code=xxx&state=yyy.

Ihr Backend tauscht dann den Code gegen ein Zugriffstoken mit GetOAuthToken() aus und überprüft das Token mit ParseJwtToken():

// 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() keinen Fehler zurückgibt, ist das Token gültig und wurde von Casdoor ausgestellt. Der Benutzer ist angemeldet. Verwenden Sie die zurückgegebenen claims, um den Benutzer zu identifizieren. Ein vollständiges Beispiel finden Sie im Anmeldehandler von Casnode, einem in Go geschriebenen Forum.

Benutzer angemeldet halten​

Wie Ihre Anwendung sich an den Benutzer erinnert, ist eine eigene Designentscheidung und nicht Teil von OIDC, OAuth 2.0 oder Casdoor. Dieser Abschnitt beschreibt zwei gängige Methoden.

Die claims, die ParseJwtToken() zurückgibt, haben den folgenden Typ:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
FieldDescription
UserThe user, with all profile fields. See User
AccessTokenThe access token string
jwt.RegisteredClaimsThe standard claims of a JSON Web Token (JWT)

In Casdoor trägt das Zugriffstoken dieselben Benutzer-Claims wie das ID-Token, enthält also Informationen über den angemeldeten Benutzer. Es handelt sich dennoch um zwei separate Tokens mit unterschiedlichem tokenType-Claim und möglicherweise unterschiedlichem aud. Siehe Zugriffstoken und ID-Token.

Serverseitige Sitzung verwenden​

Speichern Sie die Claims in der Sitzung Ihres Web-Frameworks. Wie Sie das tun, hängt von der Sprache und dem Framework ab. Casnode verwendet das Beego-Framework und speichert den Benutzer mit 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

Zugriffstoken als JWT verwenden​

Das Zugriffstoken ist ein JWT. Wenn Ihre Anwendung Sitzungen in JWTs speichert, verwenden Sie das Zugriffstoken direkt:

  1. Senden Sie das Zugriffstoken an das Frontend und speichern Sie es dort, z. B. im localStorage des Browsers.
  2. Senden Sie das Zugriffstoken bei jeder Anfrage an das Backend.
  3. Überprüfen Sie das Token im Backend mit ParseJwtToken() oder einer eigenen Funktion und lesen Sie den angemeldeten Benutzer daraus.

Benutzer über das SDK verwalten​

Die Backend-SDKs kapseln die Casdoor API. Dieser Teil ist weder OIDC noch OAuth 2.0. Die Funktionen umfassen:

FunctionDescription
GetUser(name string)Gets a user by username
GetUsers()Gets all users
AddUser()Adds a user
UpdateUser()Updates a user
DeleteUser()Deletes a user
CheckUserPassword(auth.User)Überprüft das Passwort eines Benutzers

Wenn das SDK keine Funktion für einen Endpunkt hat, rufen Sie die Casdoor API direkt auf.

Anwendungen über das SDK verwalten​

FunctionDescription
AddApplication()Creates an application
GetApplication(name string)Ruft eine Anwendung anhand des Namens ab
GetApplications()Gets all applications
UpdateApplication()Updates an application
DeleteApplication()Deletes an application

Wenn Sie eine Anwendung mit AddApplication() erstellen, füllt Casdoor die Standard-Registrierungselemente (ID, Username, Display name, Password, Confirm password, Email, Phone, Agreement), Anmeldeelemente und Anmeldeverfahren automatisch aus. Die Anwendung funktioniert in der Benutzeroberfläche ohne weitere Konfiguration.

Siehe auch​