التخطي إلى المحتوى الرئيسي

واجهة برمجة التطبيقات العامة لـ Casdoor

واجهة المستخدم الأمامية لـ Casdoor هي SPA (تطبيق صفحة واحدة) تم تطويرها في React. واجهة React الأمامية تستهلك واجهة برمجة التطبيقات RESTful التي يكشف عنها كود الخلفية Go. يُشار إلى هذه الواجهة البرمجية RESTful باسم Casdoor Public API. بعبارة أخرى، بواسطة استدعاءات HTTP، يمكنك القيام بكل شيء تمامًا كما تفعل واجهة المستخدم الويب لـ Casdoor نفسها. لا توجد قيود أخرى. يمكن استخدام الواجهة البرمجية من قبل الآتي:

  • واجهة المستخدم الأمامية لـ Casdoor
  • حزم تطوير العميل لـ Casdoor (مثل، casdoor-go-sdk)
  • أي شيفرة مخصصة أخرى من جانب التطبيق

يمكن العثور على المرجع الكامل لـ Casdoor Public API على Swagger: https://door.casdoor.com/swagger. تم إنشاء وثائق Swagger هذه تلقائيًا باستخدام أداة Bee من Beego. إذا كنت ترغب في إنشاء وثائق 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 كالمستخدم نفسه.

كيفية الحصول على رمز الوصول؟​

يمكن للتطبيق الحصول على رمز الوصول لمستخدم Casdoor في نهاية عملية تسجيل الدخول OAuth (أي الحصول على الرمز بواسطة الكود والحالة). ستكون أذونات استدعاءات الواجهة البرمجية هي نفسها كالمستخدم.

توضح الأمثلة أدناه كيفية استدعاء وظيفة GetOAuthToken() في Go عبر 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)
}

يمكن أيضًا الوصول إلى جميع رموز الوصول الممنوحة عبر واجهة المستخدم الويب من قبل مستخدم مسؤول في صفحة الرموز. على سبيل المثال، قم بزيارة: 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، تنسيق رأس 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.

كيفية الحصول على معرف العميل والسر؟​

ستعرض صفحة تحرير التطبيق (مثل، https://door.casdoor.com/applications/casbin/app-vue-python-example) معرف العميل والسر لتطبيق. 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 Basic Authentication، تنسيق رأس 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. بواسطة مفتاح الدخول و السر الخاص بالدخول​

يمكننا استخدام مفتاح الدخول والسر الخاص بالدخول لمستخدم Casdoor لاستدعاء واجهة برمجة تطبيقات Casdoor العامة كالمستخدم نفسه. يمكن تكوين مفتاح الدخول والسر الخاص بالدخول في صفحة إعدادات المستخدم من قبل المدير أو المستخدم نفسه. يمكن أيضًا استدعاء واجهة برمجة التطبيقات update-user لتحديث هذه الحقول. ستكون أذونات استدعاءات الواجهة البرمجية هي نفسها كالمستخدم.

كيفية المصادقة؟​

  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'

٤. بواسطة username و password​

تحذير

هذه الطريقة في المصادقة غير آمنة ومحتفظ بها هنا فقط لأغراض التوافق أو العرض التوضيحي. نوصي باستخدام الطرق الثلاثة السابقة للمصادقة بدلاً من ذلك.

ماذا سيحدث؟​

سيتم كشف بيانات اعتماد المستخدم كمعاملات GET في عنوان URL للطلب. علاوة على ذلك، سيتم التقاط بيانات اعتماد المستخدم بنص عادي عبر الشبكة إذا كنت تستخدم HTTP بدلاً من HTTPS.

يمكننا استخدام اسم المستخدم وكلمة المرور لمستخدم Casdoor لاستدعاء Casdoor Public API كالمستخدم نفسه. يأخذ اسم المستخدم التنسيق <اسم منظمة المستخدم>/<اسم المستخدم>. ستكون الأذونات لاستدعاءات واجهة برمجة التطبيقات هي نفسها كالمستخدم.

كيفية المصادقة؟​

  1. معامل GET لبروتوكول HTTP، تنسيق الرابط هو:

    /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

CORS (Cross-Origin Resource Sharing)​

Casdoor implements flexible CORS handling to allow secure cross-origin API requests. The server validates the Origin header and returns appropriate Access-Control-Allow-Origin headers based on the following rules:

Allowed origins:

  • Origins matching your application's redirect URIs (configured in the application settings)
  • Origins matching the Casdoor server's own hostname
  • The configured origin in Casdoor's settings
  • Special endpoint exceptions: requests to /api/login/oauth/access_token and /api/userinfo endpoints, and requests with origin appleid.apple.com

How it works:

When you make a cross-origin API request, Casdoor validates the origin through multiple checks: localhost/intranet addresses, matching redirect URIs in any application, matching the server's hostname, or configured origins. If any validation passes, the server includes CORS headers in the response allowing the request. For preflight OPTIONS requests, Casdoor returns appropriate headers including allowed methods (POST, GET, OPTIONS, DELETE) and credentials support.

Configuration:

To enable CORS for your application, add your frontend's origin to the application's Redirect URIs in the Casdoor admin panel. This allows your application to make authenticated API calls from the browser.