Saltar al contenido principal

Casdoor SDKs

Introducción​

Compared to the standard OIDC protocol, Casdoor's SDK provides additional functionality, such as user management and resource uploading. Connecting to Casdoor via the Casdoor SDK requires more time than using a standard OIDC client library but provides the best flexibility and the most powerful API.

Los SDKs de Casdoor se pueden dividir en dos categorías:

  1. Frontend SDK: SDKs for websites (like Javascript SDK, Vue SDK) and mobile apps (Android or iOS SDKs). Casdoor supports providing authentication for both websites and mobile applications.
  2. SDK de Backend: SDKs para lenguajes de backend como Go, Java, Node.js, Python, PHP, etc.
consejo

If your website is developed with a frontend-backend separation architecture, you can use the Javascript SDK: casdoor-js-sdk, React SDK: casdoor-react-sdk, or Vue SDK: casdoor-vue-sdk to integrate Casdoor in the frontend. If your web application is a traditional website developed with JSP or PHP, you can use backend SDKs only. Ver un ejemplo: casdoor-python-vue-sdk-example

SDK MóvilDescripciónCódigo SDKCódigo de ejemplo
SDK de AndroidPara aplicaciones Androidcasdoor-android-sdkcasdoor-android-example
SDK de iOSPara aplicaciones iOScasdoor-ios-sdkcasdoor-ios-example
SDK de React NativePara aplicaciones React Nativecasdoor-react-native-sdkcasdoor-react-native-example
SDK de FlutterPara aplicaciones Fluttercasdoor-flutter-sdkcasdoor-flutter-example
SDK de FirebasePara aplicaciones de Google Firebasecasdoor-firebase-example
SDK de juegos UnityPara juegos Unity 2D/3D PC/Móvilcasdoor-dotnet-sdkcasdoor-unity-example
SDK de uni-appPara aplicaciones uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
SDK de escritorioDescripciónCódigo SDKCódigo de ejemplo
SDK de ElectronPara aplicaciones Electroncasdoor-js-sdkcasdoor-electron-example
SDK de .NET DesktopPara aplicaciones de escritorio .NETcasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
SDK de C/C++Para aplicaciones de escritorio C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
SDK de frontend webDescripciónCódigo SDKCódigo de ejemplo
SDK de JavascriptPara sitios web tradicionales no SPAcasdoor-js-sdkBackend de Nodejs: casdoor-raw-js-example
Backend de Go: casdoor-go-react-sdk-example
SDK solo para frontendPara sitios web SPA solo frontendcasdoor-js-sdkcasdoor-react-only-example
SDK de ReactPara sitios web de Reactcasdoor-react-sdkBackend de Nodejs: casdoor-nodejs-react-example
Backend de Java: casdoor-spring-security-react-example
SDK de Next.jsPara sitios web de Next.jsnextjs-auth
SDK de NuxtPara sitios web de 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

A continuación, use uno de los siguientes SDKs de backend basados en el lenguaje de su backend:

SDK de backend webDescripciónCódigo del SDKCódigo de ejemplo
SDK de GoPara backends de Gocasdoor-go-sdkcasdoor-go-react-sdk-example
SDK de JavaPara backends de Javacasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
SDK de Node.jsPara backends de Node.jscasdoor-nodejs-sdkcasdoor-nodejs-react-example
SDK de PythonPara backends de Pythoncasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
SDK de PHPPara backends de PHPcasdoor-php-sdkwordpress-casdoor-plugin
SDK de .NETPara backends de ASP.NETcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
SDK de RustPara backends de Rustcasdoor-rust-sdkcasdoor-rust-example
SDK de C/C++Para backends de C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
SDK de DartPara backends de Dartcasdoor-dart-sdk
SDK de RubyPara backends de Rubycasdoor-ruby-sdk

Para obtener una lista completa de los SDKs oficiales de Casdoor, consulte: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

¿Cómo usar el SDK de Casdoor?​

1. Configuración del SDK de backend​

When your application starts up, you need to initialize the Casdoor SDK configuration by calling the InitConfig() function with the required parameters. Using casdoor-go-sdk as an example: 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)
}

Todos los parámetros para InitConfig() se explican a continuación:

ParámetroDebeDescripción
punto finalSíURL del servidor Casdoor, como https://door.casdoor.com o http://localhost:8000
clientIdSíID de cliente para la aplicación Casdoor
clientSecretSíSecreto de cliente para la aplicación Casdoor
jwtPublicKeySíLa clave pública para el certificado de la aplicación Casdoor
organizationNameSíEl nombre de la organización Casdoor
applicationNameNoEl nombre de la aplicación Casdoor
consejo

La jwtPublicKey se puede gestionar en la página de Certs como se muestra a continuación.

Gestión de Certificados

Puede encontrar la clave pública en la página de edición de certificados, copiarla o descargarla para el sdk.

Edición de Certificados

Luego puede seleccionar el certificado en la página de edición de la aplicación.

Selección de Certificados

2. Configuración del frontend​

Primero, instale casdoor-js-sdk a través de NPM o Yarn:

npm install casdoor-js-sdk

O:

yarn add casdoor-js-sdk

Luego defina las siguientes funciones de utilidad (mejor en un archivo JS global como 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;
}

En el archivo de entrada de su código frontend (como index.js o app.js en React), necesita inicializar el casdoor-js-sdk llamando a la función InitConfig() con los parámetros requeridos. Los primeros 4 parámetros deben usar el mismo valor que el SDK de backend de Casdoor. El último parámetro redirectPath es la ruta relativa para la URL redirigida, devuelta desde la página de inicio de sesión de Casdoor.

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

xxx.initCasdoorSdk(config);

(Opcional) Debido a que estamos usando React como ejemplo, nuestra ruta /callback está llegando a la ruta de React. Usamos el siguiente componente de React para recibir la llamada /callback y enviarla al backend. Puede ignorar este paso si está redirigiendo directamente al backend (como en JSP o 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. Obtener URLs de inicio de sesión​

A continuación, puede mostrar los botones o enlaces de "Registrarse" y "Iniciar sesión" a sus usuarios. Las URLs se pueden recuperar tanto en el frontend como en el backend. Ver más detalles en: /docs/basic/core-concepts#login-urls

4. Obtener y verificar token de acceso​

Aquí están los pasos:

  1. El usuario hace clic en la URL de inicio de sesión y es redirigido a la página de inicio de sesión de Casdoor, como: 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. El usuario ingresa nombre de usuario & contraseña y hace clic en Sign In (o simplemente hace clic en el botón de inicio de sesión de terceros como Sign in with GitHub).
  3. El usuario es redirigido de vuelta a su aplicación con el código de autorización emitido por Casdoor (como: https://forum.casbin.com?code=xxx&state=yyy), el backend de su aplicación necesita intercambiar el código de autorización con el token de acceso y verificar que el token de acceso es válido y emitido por Casdoor. Las funciones GetOAuthToken() y ParseJwtToken() son proporcionadas por el SDK de backend de Casdoor.

El siguiente código muestra cómo obtener y verificar el token de acceso. Para un ejemplo real de Casnode (un sitio web de foro escrito en Go), vea: 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() termina sin error, entonces el usuario ha iniciado sesión con éxito en la aplicación. Los claims devueltos se pueden usar para identificar al usuario más tarde.

4. Identificar usuario con token de acceso​

información

Esta parte es en realidad la lógica de negocio propia de su aplicación y no parte de OIDC, OAuth o Casdoor. Solo proporcionamos buenas prácticas ya que mucha gente no sabe qué hacer para el siguiente paso.

En Casdoor, el token de acceso suele ser idéntico al token de ID. Son la misma cosa. Así que el token de acceso contiene toda la información para el usuario que ha iniciado sesión.

La variable claims devuelta por ParseJwtToken() se define como:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: el objeto Usuario, que contiene toda la información para el usuario que ha iniciado sesión, ver definición en: /docs/basic/core-concepts#user
  2. AccessToken: la cadena de token de acceso.
  3. jwt.RegisteredClaims: algunos otros valores requeridos por JWT.

En este momento, la aplicación generalmente tiene dos formas de recordar la sesión del usuario: session y JWT.

Session​

El método para establecer la sesión varía mucho dependiendo del lenguaje y el marco web. Por ejemplo, Casnode utiliza el marco web Beego y establece la sesión llamando a: 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​

El accessToken devuelto por Casdoor es en realidad un JWT. Así que si su aplicación usa JWT para mantener la sesión del usuario, simplemente use el token de acceso directamente para ello:

  1. Enviar el token de acceso al frontend, guardarlo en lugares como localStorage del navegador.
  2. Permita que el navegador envíe el token de acceso al backend para cada solicitud.
  3. Llame a ParseJwtToken() o su propia función para verificar el token de acceso y obtener información del usuario que ha iniciado sesión en su backend.

5. (Opcional) Interactuar con la tabla de Usuarios​

información

Esta parte es proporcionada por Casdoor Public API y no es parte de OIDC o OAuth.

El SDK de backend de Casdoor proporciona muchas funciones de ayuda, no limitadas a:

  • GetUser(name string): obtener un usuario por nombre de usuario.
  • GetUsers(): obtener todos los usuarios.
  • AddUser(): agregar un usuario.
  • UpdateUser(): actualizar un usuario.
  • DeleteUser(): eliminar un usuario.
  • CheckUserPassword(auth.User): verificar la contraseña del usuario.

Estas funciones se implementan realizando llamadas RESTful contra Casdoor Public API. Si una función no se proporciona en el SDK de Backend de Casdoor, puede realizar llamadas RESTful por sí mismo.