Saltar al contenido principal

API Pública de Casdoor

La interfaz de usuario web del frontend de Casdoor es una SPA (Aplicación de Una Sola Página) desarrollada en React. El frontend de React consume la API RESTful de Casdoor expuesta por el código del backend en Go. Esta API RESTful se conoce como Casdoor Public API. En otras palabras, con llamadas HTTP, puedes hacer todo tal como lo hace la propia interfaz web de Casdoor. No hay otras limitaciones. La API puede ser utilizada por los siguientes:

  • Frontend de Casdoor
  • SDKs de cliente de Casdoor (por ejemplo, casdoor-go-sdk)
  • Cualquier otro código personalizado del lado de la aplicación

La referencia completa para la Casdoor Public API se puede encontrar en Swagger: https://door.casdoor.com/swagger. Estos documentos de Swagger se generan automáticamente utilizando la herramienta Bee de Beego. Si quieres generar los documentos de Swagger por ti mismo, consulta: Cómo generar el archivo swagger

Machine-to-Machine (M2M) Authentication​

Machine-to-machine (M2M) authentication is designed for scenarios where services, applications, or backend systems need to authenticate and communicate with APIs without user interaction. This is particularly useful for:

  • Backend services calling Casdoor APIs programmatically
  • CLI tools that need to interact with your APIs using access tokens
  • B2B enterprise scenarios where organizations need to generate tokens for API access (e.g., admin tokens for management operations, read tokens for data access)
  • Automated processes such as scheduled jobs, data synchronization, or system integrations
  • Microservices that need to authenticate with each other

Casdoor supports M2M authentication through the following methods:

  1. Client Credentials Grant (OAuth 2.0): The recommended approach for M2M scenarios. This uses the Client Credentials Grant flow where applications authenticate using their Client ID and Client Secret to obtain access tokens. See the OAuth Client Credentials Grant documentation for details on obtaining tokens via this flow.

  2. Direct API Authentication with Client ID and Secret: Use the application's credentials directly in API calls (see method #2 below).

Use Cases for M2M Authentication​

  • Organization-level API access: In B2B scenarios, you can create a Casdoor application for each organization. The application's client credentials provide admin-level permissions for that organization, enabling them to manage their users, generate tokens, and access organizational resources independently.

  • Token generation for downstream services: Generate access tokens programmatically (using Client Credentials Grant) that can be distributed to CLI tools, read-only services, or other applications that need scoped access to your APIs.

  • Service-to-service authentication: Backend services can authenticate as an "application" rather than as a user, with permissions equivalent to the organization admin.

Cómo autenticarse con Casdoor Public API​

1. Por Access token​

Podemos usar el token de acceso otorgado a un usuario autenticado para llamar a Casdoor Public API como el propio usuario.

¿Cómo obtener el token de acceso?​

La aplicación puede obtener el token de acceso para el usuario de Casdoor al final del proceso de inicio de sesión de OAuth (también conocido como obtener el token por código y estado). Los permisos para las llamadas a la API serán los mismos que los del usuario.

Los siguientes ejemplos muestran cómo llamar a la función GetOAuthToken() en Go a través de casdoor-go-sdk.

func (c *ApiController) Signin() {
    code := c.Input().Get("code")
    state := c.Input().Get("state")

    token, err := casdoorsdk.GetOAuthToken(code, state)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims, err := casdoorsdk.ParseJwtToken(token.AccessToken)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    if !claims.IsAdmin {
        claims.Type = "chat-user"
    }

    err = c.addInitialChat(&claims.User)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims.AccessToken = token.AccessToken
    c.SetSessionClaims(claims)

    c.ResponseOk(claims)
}

Todos los tokens de acceso otorgados también se pueden acceder a través de la interfaz de usuario web por un usuario administrador en la página de Tokens. Por ejemplo, visita: https://door.casdoor.com/tokens para el sitio de demostración.

¿Cómo autenticarse?​

  1. Parámetro HTTP GET, el formato de la URL es:

    /page?access_token=<The access token>

    Ejemplo del sitio de demostración: https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. Token Bearer HTTP, el formato de la cabecera HTTP es:

    Authorization: Bearer <The access token>

2. By Client ID and Client secret (Machine-to-Machine)​

This method is the primary approach for machine-to-machine (M2M) authentication. It allows applications, services, or backend systems to authenticate with Casdoor APIs without any user interaction.

¿Cómo obtener el ID de cliente y el secreto?​

La página de edición de la aplicación (por ejemplo, https://door.casdoor.com/applications/casbin/app-vue-python-example) mostrará el ID de cliente y el secreto para una aplicación. This authentication method is useful when you want to call the API as a "machine", "application", or a "service" instead of a user. The permissions for the API calls will be the same as the application (equivalent to the admin of the organization).

Use cases​

  • Service authentication: Backend services calling Casdoor APIs programmatically
  • Organization management: In B2B scenarios, create an application per organization to enable them to manage users and generate tokens independently
  • Token generation: Obtain access tokens via the OAuth Client Credentials Grant flow for distribution to CLI tools or other services

¿Cómo autenticarse?​

  1. Parámetro HTTP GET, el formato de la URL es:

    /page?clientId=<The client ID>&clientSecret=<the client secret>

    Ejemplo del sitio de demostración: https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. Autenticación Básica HTTP, el formato de la cabecera HTTP es:

    Authorization: Basic <The Base64 encoding of client ID and client secret joined by a single colon ":">

Si no estás familiarizado con la codificación Base64, puedes usar una biblioteca para hacerlo porque HTTP Basic Authentication es un estándar popular soportado por muchos lugares.

Obtaining access tokens with Client Credentials​

For machine-to-machine scenarios where you need to obtain an access token (rather than using client credentials directly), use the OAuth 2.0 Client Credentials Grant flow:

  1. Make a POST request to https://<CASDOOR_HOST>/api/login/oauth/access_token with:

    {
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
    }

  2. You will receive an access token response:

    {
        "access_token": "eyJhb...",
        "token_type": "Bearer",
        "expires_in": 10080,
        "scope": "openid"
    }

  3. Use the access_token to call Casdoor APIs (see method #1 above).

For more details, see the Client Credentials Grant documentation.

información

For B2B Enterprises: You can create separate Casdoor applications for each of your customer organizations. Each application has its own client_id and client_secret, which your customers can use to:

  • Authenticate as their organization (with admin privileges)
  • Generate access tokens for their users or services
  • Manage their organization's users and permissions independently
  • Integrate your APIs into their systems without UI-based login flows

This approach allows you to delegate organization management to your customers while maintaining security and isolation between different organizations.

3. Por Access key y Access secret​

Podemos usar la clave de acceso y el secreto de acceso de un usuario de Casdoor para llamar a Casdoor Public API como el propio usuario. La clave de acceso y el secreto de acceso se pueden configurar en la página de configuración del usuario por un administrador o el propio usuario. La API update-user también se puede llamar para actualizar estos campos. Los permisos para las llamadas a la API serán los mismos que los del usuario.

¿Cómo autenticarse?​

  1. Create a pair of accessKey and accessSecret in account setting page.

  2. Parámetro HTTP GET, el formato de la URL es:

    /page?accessKey=<The user's access key>&accessSecret=<the user's access secret>"

Ejemplo del sitio de demostración: https://door.casdoor.com/api/get-global-providers?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796/admin&accessSecret=79911517-fc36-4093-b115-65a9741f6b14

User Api Key

curl --location 'http://door.casdoor.com/api/user?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796&accessSecret=79911517-fc36-4093-b115-65a9741f6b14'

4. Por username y password​

precaución

Este método de autenticación no es seguro y se mantiene aquí solo por compatibilidad o fines de demostración. Recomendamos usar los tres métodos de autenticación anteriores en lugar de este.

¿Qué sucederá?​

Las credenciales del usuario se expondrán como parámetros GET en la URL de la solicitud. Además, las credenciales del usuario se podrán interceptar en texto plano por la red si estás usando HTTP en lugar de HTTPS.

Podemos usar el nombre de usuario y la contraseña de un usuario de Casdoor para llamar a Casdoor Public API como el propio usuario. El nombre de usuario tiene el formato de <El nombre de la organización del usuario>/<El nombre del usuario>. Los permisos para las llamadas a la API serán los mismos que los del usuario.

¿Cómo autenticarse?​

  1. Parámetro HTTP GET, el formato de la URL es:

    /page?username=<The user's organization name>/<The user name>&password=<the user's password>"

Ejemplo del sitio de demostración: https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123