Pular para o conteúdo principal

API Pública Casdoor

A interface web do frontend do Casdoor é uma SPA (Aplicação de Página Única) desenvolvida em React. O frontend em React consome a API RESTful do Casdoor exposta pelo código backend em Go. Esta API RESTful é referida como Casdoor Public API. Em outras palavras, com chamadas HTTP, você pode fazer tudo exatamente como a interface web do Casdoor faz. Não há outras limitações. A API pode ser utilizada pelos seguintes:

  • Frontend do Casdoor
  • SDKs de cliente do Casdoor (por exemplo, casdoor-go-sdk)
  • Qualquer outro código personalizado do lado da aplicação

A referência completa para a Casdoor Public API pode ser encontrada no Swagger: https://door.casdoor.com/swagger. Estes documentos do Swagger são gerados automaticamente usando a ferramenta Bee do Beego. Se você quiser gerar os documentos do Swagger por si mesmo, veja: Como gerar o arquivo 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.

Como autenticar com a Casdoor Public API​

1. Por Token de acesso​

Podemos usar o token de acesso concedido para um usuário autenticado para chamar a Casdoor Public API como o próprio usuário.

Como obter o token de acesso?​

A aplicação pode obter o token de acesso para o usuário do Casdoor no final do processo de login OAuth (também conhecido como obter o token por código e estado). As permissões para as chamadas de API serão as mesmas que as do usuário.

Os exemplos abaixo mostram como chamar a função GetOAuthToken() em Go através do 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 os tokens de acesso concedidos também podem ser acessados via interface web por um usuário administrador na página de Tokens. Por exemplo, visite: https://door.casdoor.com/tokens para o site de demonstração.

Como autenticar?​

  1. Parâmetro HTTP GET, o formato da URL é:

    /page?access_token=<The access token>

    Exemplo do site de demonstração: https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. Token Bearer HTTP, o formato do cabeçalho HTTP é:

    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.

Como obter o ID do cliente e o segredo?​

A página de edição da aplicação (por exemplo, https://door.casdoor.com/applications/casbin/app-vue-python-example) mostrará o ID do cliente e o segredo para uma aplicação. 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

Como autenticar?​

  1. Parâmetro HTTP GET, o formato da URL é:

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

    Exemplo do site de demonstração: https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. Autenticação Básica HTTP, o formato do cabeçalho HTTP é:

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

Se você não está familiarizado com a codificação Base64, você pode usar uma biblioteca para fazer isso porque a Autenticação Básica HTTP é um padrão popular suportado por muitos 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.

informação

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 e Access secret​

Podemos usar a chave de acesso e o segredo de acesso de um usuário do Casdoor para chamar a Casdoor Public API como o próprio usuário. A chave de acesso e o segredo de acesso podem ser configurados na página de configurações do usuário por um administrador ou pelo próprio usuário. a API update-user também pode ser chamada para atualizar esses campos. As permissões para as chamadas de API serão as mesmas que as do usuário.

Como autenticar?​

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

  2. Parâmetro HTTP GET, o formato da URL é:

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

Exemplo do site de demonstração: 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 e password​

cuidado

Este método de autenticação não é seguro e é mantido aqui apenas para fins de compatibilidade ou demonstração. Recomendamos usar os três métodos de autenticação anteriores em vez deste.

O que acontecerá?​

As credenciais do usuário serão expostas como parâmetros GET na URL da solicitação. Além disso, as credenciais do usuário serão capturadas em texto simples pela rede se você estiver usando HTTP em vez de HTTPS.

Podemos usar o nome de usuário e senha de um usuário do Casdoor para chamar a Casdoor Public API como o próprio usuário. O nome de usuário tem o formato de <Nome da organização do usuário>/<Nome do usuário>. As permissões para as chamadas de API serão as mesmas que as do usuário.

Como autenticar?​

  1. Parâmetro HTTP GET, o formato da URL é:

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

Exemplo do site de demonstração: https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123