Saltar al contenido principal

Iniciar sesión de usuarios con un SDK de Casdoor

Esta guía enumera los SDKs de Casdoor y explica cómo iniciar sesión de usuarios en una aplicación web con un SDK frontend y un SDK backend. Los ejemplos usan casdoor-js-sdk y casdoor-go-sdk. Los otros SDKs siguen los mismos pasos.


Resultados de aprendizaje​

  • Elegir los SDKs para su plataforma.
  • Configurar el SDK backend y el SDK frontend.
  • Intercambiar el código de autorización por un token de acceso y verificar el token.
  • Mantener al usuario conectado a su aplicación.
  • Gestionar usuarios y aplicaciones a través del SDK.

Lo que necesita​

  • Una instancia de Casdoor en ejecución
  • Una aplicación en Casdoor, con la URL de callback de su aplicación en Redirect URLs
  • El ID de cliente y el secreto de cliente de la aplicación, y la clave pública de su certificado

Acerca de los SDKs​

Los SDKs de Casdoor se basan en OpenID Connect (OIDC) y añaden funciones de la API de Casdoor, como la gestión de usuarios y la subida de archivos. Requieren un poco más de configuración que un cliente OIDC estándar y le ofrecen la API completa de Casdoor.

  • SDKs Frontend: Para frontends web, aplicaciones móviles y aplicaciones de escritorio. Construyen la URL de inicio de sesión y manejan el callback en la interfaz de usuario.
  • SDKs Backend: Para su servidor. Intercambian el código de autorización, verifican los tokens y llaman a la API de Casdoor.

Si su aplicación tiene un frontend y un backend separados, use un SDK frontend en la interfaz de usuario y un SDK backend en el servidor. Para ver un ejemplo, consulte casdoor-python-vue-sdk-example. Si su aplicación renderiza páginas en el servidor, como hacen las aplicaciones JSP y PHP, un solo SDK backend puede ser suficiente.

Elegir un SDK​

Todos los SDKs oficiales están en la organización casdoor en GitHub.

SDKs de frontend web​

SDK de frontend webDescripciónCódigo SDKCódigo de ejemplo
SDK de JavascriptPara sitios web tradicionales no SPAcasdoor-js-sdkNodejs backend: casdoor-raw-js-example
Go backend: 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-sdkNodejs backend: casdoor-nodejs-react-example
Java backend: 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
SDK de FlutterFor Flutter Web websitescasdoor-flutter-sdkcasdoor-flutter-example
ASP.NET SDKFor ASP.NET Blazor WASM websitesBlazor.BFF.OpenIDConnect.Templatecasdoor-dotnet-blazorwasm-oidc-example
SDK de FirebasePara aplicaciones de Google Firebasecasdoor-firebase-example

SDKs de backend web​

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

SDKs para móviles​

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
consejo

Una aplicación móvil que inicia sesión de forma nativa, sin usar un navegador, puede utilizar el grant de código de verificación para iniciar sesión por SMS o correo electrónico con registro automático. Los usuarios que hayan iniciado sesión también pueden aprobar el código QR en la página de inicio de sesión de su sitio web desde la app.

SDKs para escritorio​

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

Configurar el SDK del backend​

Cuando su backend se inicie, inicialice el SDK con la dirección de Casdoor y las credenciales de la aplicación. Con 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() acepta los siguientes parámetros:

ParámetroObligatorioDescripción
endpointSíCasdoor Server URL, like https://door.casdoor.com or 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

Para obtener el valor de jwtPublicKey:

  1. En la consola de administración de Casdoor, abra la página Certs.

    Certs page with the list of certificates

  2. Abra el certificado y copie o descargue su clave pública.

    Certificate edit page with the public key

  3. En la página de edición de la aplicación, seleccione el mismo certificado en Cert.

    Application edit page with the certificate selected

Configurar el SDK del frontend​

  1. Instale casdoor-js-sdk con npm:

    npm install casdoor-js-sdk

    O con Yarn:

    yarn add casdoor-js-sdk
  2. Defina funciones auxiliares en un archivo compartido, 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;
    }
  3. En el archivo de entrada del frontend, como index.js o app.js en React, inicialice el SDK. Use los mismos valores para las primeras cuatro configuraciones que en el SDK del backend. redirectPath es la ruta de su aplicación a la que Casdoor redirige al usuario después de iniciar sesión.

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

    xxx.initCasdoorSdk(config);
  4. Maneje la ruta de callback. En este ejemplo de React, un componente maneja /callback y reenvía el código al backend. Omita este paso si Casdoor redirige directamente a su backend, como en aplicaciones JSP y 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);

Proporcione a los usuarios un botón o enlace Sign in y otro Sign up. Obtenga las URL desde el SDK del frontend o el SDK del backend. Consulte URLs de inicio de sesión y registro.

Obtener y verificar el token de acceso​

El flujo de inicio de sesión tiene tres pasos:

  1. El usuario hace clic en el enlace de inicio de sesión y llega a la página de inicio de sesión de Casdoor, por ejemplo:

    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 introduce un nombre de usuario y una contraseña y hace clic en Sign In, o hace clic en el botón de un proveedor, como el botón de GitHub.

  3. Casdoor redirige al usuario a su aplicación con un código de autorización, por ejemplo https://forum.casbin.com?code=xxx&state=yyy.

Su backend intercambia luego el código por un token de acceso con GetOAuthToken() y verifica el token con 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)
}

Si ParseJwtToken() no devuelve ningún error, el token es válido y fue emitido por Casdoor. El usuario ha iniciado sesión. Use los claims devueltos para identificar al usuario. Para ver un ejemplo completo, consulte el manejador de inicio de sesión de Casnode, un foro escrito en Go.

Mantener al usuario conectado​

Cómo su aplicación recuerda al usuario es una decisión de diseño propia y no forma parte de OIDC, OAuth 2.0 ni Casdoor. Esta sección describe dos formas comunes.

Los claims que devuelve ParseJwtToken() tienen el siguiente tipo:

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)

En Casdoor, el token de acceso lleva las mismas claims de usuario que el ID token, por lo que contiene información sobre el usuario conectado. Los dos siguen siendo tokens separados, con una claim tokenType diferente y posiblemente un aud diferente. Consulte Access token and ID token.

Usar una sesión en el lado del servidor​

Almacene las claims en la sesión de su framework web. Cómo hacerlo depende del lenguaje y del framework. Casnode usa el framework Beego y almacena al usuario con 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

Usar el token de acceso como JWT​

El token de acceso es un JWT. Si su aplicación mantiene sesiones en JWTs, use el token de acceso directamente:

  1. Envíe el token de acceso al frontend y guárdelo allí, por ejemplo en el localStorage del navegador.
  2. Envíe el token de acceso al backend con cada solicitud.
  3. En el backend, verifique el token con ParseJwtToken() o con su propia función, y lea desde él al usuario conectado.

Gestionar usuarios mediante el SDK​

Los SDKs del backend envuelven la API de Casdoor. Esta parte no es OIDC ni OAuth 2.0. Las funciones incluyen:

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)Comprueba la contraseña de un usuario

Si el SDK no tiene una función para un endpoint, llame directamente a la API de Casdoor.

Gestionar aplicaciones mediante el SDK​

FunctionDescription
AddApplication()Creates an application
GetApplication(name string)Obtiene una aplicación por nombre
GetApplications()Gets all applications
UpdateApplication()Updates an application
DeleteApplication()Deletes an application

Cuando crea una aplicación con AddApplication(), Casdoor completa los elementos de registro predeterminados (ID, Username, Display name, Password, Confirm password, Email, Phone, Agreement), los elementos de inicio de sesión y los métodos de inicio de sesión. La aplicación funciona en la interfaz de usuario sin configuración adicional.

Véase también​