메인 콘텐츠로 건너뛰기

Casdoor 공개 API

Casdoor 프론트엔드 웹 UI는 React에서 개발된 SPA (Single-Page Application)입니다. React 프론트엔드는 Go 백엔드 코드에서 노출된 Casdoor RESTful API를 사용합니다. 이 RESTful API는 Casdoor Public API라고 불립니다. 다른 말로, HTTP 호출로 Casdoor 웹 UI 자체가 하는 것처럼 모든 것을 할 수 있습니다. 다른 제한은 없습니다. 다음에서 API를 사용할 수 있습니다:

  • Casdoor의 프론트엔드
  • Casdoor 클라이언트 SDK (예: casdoor-go-sdk)
  • 응용 프로그램 측에서의 다른 맞춤 코드

Casdoor Public API에 대한 전체 참조는 Swagger에서 찾을 수 있습니다: https://door.casdoor.com/swagger. 이 Swagger 문서는 Beego의 Bee 도구를 사용하여 자동으로 생성됩니다. Swagger 문서를 직접 생성하려면 다음을 참조하십시오: Swagger 파일 생성 방법

API Response Language​

Casdoor APIs support internationalized responses. The default response language is English. To receive error messages and other text content in your preferred language, include the Accept-Language header in your API requests:

# Example: Get error messages in French
curl -X GET https://door.casdoor.com/api/get-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept-Language: fr"

Supported language codes include en, zh, es, fr, de, ja, ko, and more. For a complete list and more details, see the Internationalization documentation.

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.

Casdoor Public API로 인증하는 방법​

1. Access token을 통해​

인증된 사용자에게 부여된 액세스 토큰을 사용하여 사용자 자신으로서 Casdoor Public API를 호출할 수 있습니다.

액세스 토큰을 어떻게 얻나요?​

응용 프로그램은 OAuth 로그인 프로세스의 끝에서 Casdoor 사용자의 액세스 토큰을 얻을 수 있습니다 (즉, 코드와 상태로 토큰을 얻습니다). API 호출에 대한 권한은 사용자와 동일할 것입니다.

아래 예제는 Go에서 casdoor-go-sdk를 통해 GetOAuthToken() 함수를 호출하는 방법을 보여줍니다.

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)
}

모든 부여된 액세스 토큰은 토큰 페이지에서 관리자 사용자가 웹 UI를 통해 액세스할 수도 있습니다. 예를 들어, 데모 사이트를 방문하십시오: https://door.casdoor.com/tokens

어떻게 인증하나요?​

  1. HTTP GET 매개변수, URL 형식은 다음과 같습니다:

    /page?access_token=<The access token>

    데모 사이트 예시: https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. HTTP Bearer 토큰, 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.

클라이언트 ID와 비밀번호를 어떻게 얻나요?​

응용 프로그램 편집 페이지 (예, https://door.casdoor.com/applications/casbin/app-vue-python-example)는 응용 프로그램에 대한 클라이언트 ID와 비밀을 표시합니다. 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

어떻게 인증하나요?​

  1. HTTP GET 매개변수, URL 형식은 다음과 같습니다:

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

    데모 사이트 예시: https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. HTTP 기본 인증, HTTP 헤더 형식은 다음과 같습니다:

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

Base64 인코딩에 익숙하지 않다면, 많은 곳에서 지원하는 인기 있는 표준인 HTTP Basic Authentication을 수행하기 위해 라이브러리를 사용할 수 있습니다.

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.

정보

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. Access key와 Access secret를 사용하여​

Casdoor 사용자의 액세스 키와 액세스 비밀을 사용하여 사용자 자체로 Casdoor Public API를 호출할 수 있습니다. 액세스 키와 액세스 비밀은 관리자 또는 사용자 자신에 의해 사용자 설정 페이지에서 구성할 수 있습니다. update-user API도 이러한 필드를 업데이트하기 위해 호출될 수 있습니다. API 호출에 대한 권한은 사용자와 동일할 것입니다.

어떻게 인증하나요?​

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

  2. HTTP GET 매개변수, URL 형식은 다음과 같습니다:

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

데모 사이트 예시: 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. username과 password를 사용하여​

주의

이 인증 방법은 안전하지 않으며 호환성 또는 데모 목적으로만 여기에 유지됩니다. 이전 세 가지 인증 방법을 사용하는 것을 권장합니다.

무슨 일이 일어날까요?​

사용자 자격 증명이 요청 URL에서 GET 매개변수로 노출됩니다. 게다가, HTTPS 대신 HTTP를 사용하면 네트워크에서 사용자 자격 증명이 평문으로 스니핑됩니다.

Casdoor 사용자의 사용자 이름과 비밀번호를 사용하여 사용자 자체로 Casdoor Public API를 호출할 수 있습니다. 사용자 이름은 <사용자의 조직 이름>/<사용자 이름> 형식을 취합니다. API 호출에 대한 권한은 사용자와 동일할 것입니다.

어떻게 인증하나요?​

  1. HTTP GET 매개변수, URL 형식은 다음과 같습니다:

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

데모 사이트 예시: https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123