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 web | Descripción | Código SDK | Código de ejemplo |
|---|---|---|---|
| SDK de Javascript | Para sitios web tradicionales no SPA | casdoor-js-sdk | Nodejs backend: casdoor-raw-js-example Go backend: casdoor-go-react-sdk-example |
| SDK solo para frontend | Para sitios web SPA solo frontend | casdoor-js-sdk | casdoor-react-only-example |
| SDK de React | Para sitios web de React | casdoor-react-sdk | Nodejs backend: casdoor-nodejs-react-example Java backend: casdoor-spring-security-react-example |
| SDK de Next.js | Para sitios web de Next.js | nextjs-auth | |
| SDK de Nuxt | Para sitios web de Nuxt | nuxt-auth | |
| Vue SDK | For Vue websites | casdoor-vue-sdk | casdoor-python-vue-sdk-example |
| Angular SDK | For Angular websites | casdoor-angular-sdk | casdoor-nodejs-angular-example |
| SDK de Flutter | For Flutter Web websites | casdoor-flutter-sdk | casdoor-flutter-example |
| ASP.NET SDK | For ASP.NET Blazor WASM websites | Blazor.BFF.OpenIDConnect.Template | casdoor-dotnet-blazorwasm-oidc-example |
| SDK de Firebase | Para aplicaciones de Google Firebase | casdoor-firebase-example |
SDKs de backend web
| SDK de backend web | Descripción | Código del SDK | Código de ejemplo |
|---|---|---|---|
| SDK de Go | Para backends de Go | casdoor-go-sdk | casdoor-go-react-sdk-example |
| SDK de Java | Para backends de Java | casdoor-java-sdk | casdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example, quarkus-casdoor-auth (Quarkus) |
| SDK de Node.js | Para backends de Node.js | casdoor-nodejs-sdk | casdoor-nodejs-react-example |
| SDK de Python | Para backends de Python | casdoor-python-sdk | Flask: casdoor-python-vue-sdk-example Django: casdoor-django-js-sdk-example FastAPI: casdoor-fastapi-js-sdk-example |
| SDK de PHP | Para backends de PHP | casdoor-php-sdk | wordpress-casdoor-plugin |
| SDK de .NET | Para backends de ASP.NET | casdoor-dotnet-sdk | casdoor-dotnet-sdk-example |
| SDK de Rust | Para backends de Rust | casdoor-rust-sdk | casdoor-rust-example |
| SDK de C/C++ | Para backends de C/C++ | casdoor-cpp-sdk | casdoor-cpp-qt-example |
| SDK de Dart | Para backends de Dart | casdoor-dart-sdk | |
| SDK de Ruby | Para backends de Ruby | casdoor-ruby-sdk |
SDKs para móviles
| SDK Móvil | Descripción | Código SDK | Código de ejemplo |
|---|---|---|---|
| SDK de Android | Para aplicaciones Android | casdoor-android-sdk | casdoor-android-example |
| SDK de iOS | Para aplicaciones iOS | casdoor-ios-sdk | casdoor-ios-example |
| SDK de React Native | Para aplicaciones React Native | casdoor-react-native-sdk | casdoor-react-native-example |
| SDK de Flutter | Para aplicaciones Flutter | casdoor-flutter-sdk | casdoor-flutter-example |
| SDK de Firebase | Para aplicaciones de Google Firebase | casdoor-firebase-example | |
| SDK de juegos Unity | Para juegos Unity 2D/3D PC/Móvil | casdoor-dotnet-sdk | casdoor-unity-example |
| SDK de uni-app | Para aplicaciones uni-app | casdoor-uniapp-sdk | casdoor-uniapp-example |
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 escritorio | Descripción | Código SDK | Código de ejemplo |
|---|---|---|---|
| SDK de Electron | Para aplicaciones Electron | casdoor-js-sdk | casdoor-electron-example |
| SDK de .NET Desktop | Para aplicaciones de escritorio .NET | casdoor-dotnet-sdk | WPF: 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-sdk | casdoor-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ámetro | Obligatorio | Descripción |
|---|---|---|
| endpoint | Sí | Casdoor Server URL, like https://door.casdoor.com or http://localhost:8000 |
| clientId | Sí | ID de Cliente para la aplicación Casdoor |
| clientSecret | Sí | Secreto de cliente para la aplicación Casdoor |
| jwtPublicKey | Sí | La clave pública para el certificado de la aplicación Casdoor |
| organizationName | Sí | El nombre de la organización Casdoor |
| applicationName | No | El nombre de la aplicación Casdoor |
Para obtener el valor de jwtPublicKey:
-
En la consola de administración de Casdoor, abra la página Certs.

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

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

Configurar el SDK del frontend
-
Instale
casdoor-js-sdkcon npm:npm install casdoor-js-sdkO con Yarn:
yarn add casdoor-js-sdk -
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;
} -
En el archivo de entrada del frontend, como
index.jsoapp.jsen React, inicialice el SDK. Use los mismos valores para las primeras cuatro configuraciones que en el SDK del backend.redirectPathes 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); -
Maneje la ruta de callback. En este ejemplo de React, un componente maneja
/callbacky 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);
Mostrar los enlaces de inicio de sesión y registro
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:
-
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 -
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.
-
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
}
| Field | Description |
|---|---|
User | The user, with all profile fields. See User |
AccessToken | The access token string |
jwt.RegisteredClaims | The 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:
- Envíe el token de acceso al frontend y guárdelo allí, por ejemplo en el
localStoragedel navegador. - Envíe el token de acceso al backend con cada solicitud.
- 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:
| Function | Description |
|---|---|
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
| Function | Description |
|---|---|
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.