OAuth 2.0

مقدمة

يدعم Casdoor استخدام Access Token لمصادقة العملاء. في هذا القسم، سنوضح لك كيفية الحصول على Access Token، وكيفية التحقق من Access Token، وكيفية استخدام Access Token.

كيفية الحصول على Access Token

هناك طريقتان للحصول على Access Token: يمكنك استخدام Casdoor SDKs. للحصول على معلومات مفصلة، يرجى الرجوع إلى وثائق SDK. هنا، سنوضح لك بشكل رئيسي كيفية استخدام الواجهة البرمجية للحصول على Access Token.

يدعم Casdoor أربعة أنواع من منح OAuth: Authorization Code Grant، Implicit Grant، Resource Owner Password Credentials Grant، و Client Credentials Grant.

لأسباب أمنية، تطبيق Casdoor لديه وضع رمز التفويض مفعل بشكل افتراضي. إذا كنت بحاجة إلى استخدام أوضاع أخرى، يرجى الذهاب إلى التطبيق المناسب لضبطه.

Authorization Code Grant

أولاً، قم بإعادة توجيه مستخدميك إلى:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
response_type=code&
scope=openid&
state=STATE

النطاقات المتاحة

الاسم	الوصف
openid (no scope)	sub (معرف المستخدم)، iss (المصدر)، و aud (الجمهور)
profile	معلومات ملف تعريف المستخدم، بما في ذلك الاسم، displayName، والصورة الرمزية
email	عنوان البريد الإلكتروني للمستخدم
address	عنوان المستخدم
phone	رقم هاتف المستخدم

معلومات

يمكن لتطبيق OAuth الخاص بك طلب النطاقات في إعادة التوجيه الأولية. يمكنك تحديد نطاقات متعددة عن طريق فصلها بمسافة باستخدام %20:

https://<CASDOOR_HOST>/login/oauth/authorize?
client_id=...&
scope=openid%20email

لمزيد من التفاصيل، يرجى الاطلاع على معيار OIDC

بعد أن يتم مصادقة المستخدم مع Casdoor، سيقوم Casdoor بإعادة توجيههم إلى:

https://REDIRECT_URI?code=CODE&state=STATE

الآن بعد أن حصلت على رمز التفويض، قم بإجراء طلب POST إلى:

https://<CASDOOR_HOST>/api/login/oauth/access_token

في تطبيق الخادم الخلفي الخاص بك:

{
    "grant_type": "authorization_code",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "code": Code,
}

ستحصل على الاستجابة التالية:

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

ملاحظة

يدعم Casdoor أيضًا ميزة PKCE. عند الحصول على رمز التفويض، يمكنك إضافة معلمتين لتفعيل PKCE:

&code_challenge_method=S256&code_challenge=YOUR_CHANNELLENGE

عند الحصول على الرمز، تحتاج إلى تمرير معلمة code_verifier للتحقق من PKCE. من الجدير بالذكر أنه مع تفعيل PKCE، Client_Secret غير مطلوب، ولكن إذا قمت بتمريره، يجب أن يكون القيمة الصحيحة.

Implicit Grant

ربما لا يحتوي تطبيقك على خادم خلفي، وتحتاج إلى استخدام Implicit Grant. أولاً، تحتاج إلى التأكد من تفعيل Implicit Grant، ثم قم بإعادة توجيه مستخدميك إلى:

https://<CASDOOR_HOST>/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=token&scope=openid&state=STATE

بعد أن يتم مصادقة المستخدم مع Casdoor، سيقوم Casdoor بإعادة توجيههم إلى:

https://REDIRECT_URI/#access_token=ACCESS_TOKEN

يدعم Casdoor أيضًا id_token كـ response_type، وهي ميزة من OpenID.

Resource Owner Password Credentials Grant

إذا لم يكن لديك واجهة أمامية لتطبيقك تقوم بإعادة توجيه المستخدمين إلى Casdoor، فقد تحتاج إلى هذا.

أولاً، تحتاج إلى التأكد من تفعيل Password Credentials Grant وإرسال طلب POST إلى:

https://<CASDOOR_HOST>/api/login/oauth/access_token

{
    "grant_type": "password",
    "client_id": ClientId,
    "client_secret": ClientSecret,
    "username": Username,
    "password": Password,
}

ستحصل على الاستجابة التالية:

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

Client Credentials Grant

يمكنك أيضًا استخدام Client Credentials Grant عندما لا يحتوي تطبيقك على واجهة أمامية.

أولاً، عليك التأكد من تفعيل ميزة Client Credentials Grant وإرسال طلب POST إلى https://<CASDOOR_HOST>/api/login/oauth/access_token:

{
    "grant_type": "client_credentials",
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

ستحصل على الاستجابة التالية:

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

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

رمز التحديث

ربما ترغب في تحديث رمز الوصول الخاص بك، عندها يمكنك استخدام refreshToken الذي حصلت عليه أعلاه.

أولاً، عليك تحديد وقت انتهاء صلاحية رمز التحديث في التطبيق (الافتراضي هو 0 ساعات)، وإرسال طلب POST إلى https://<CASDOOR_HOST>/api/login/oauth/refresh_token

{
    "grant_type": "refresh_token",
    "refresh_token": REFRESH_TOKEN,
    "scope": SCOPE,
    "client_id": ClientId,
    "client_secret": ClientSecret,
}

ستحصل على استجابة مثل هذه:

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

كيفية التحقق من رمز الوصول

Casdoor يدعم حالياً نقطة النهاية لفحص الرمز token introspection. هذه النقطة محمية بواسطة Basic Authentication (ClientId:ClientSecret).

POST /api/login/oauth/introspect HTTP/1.1
Host: CASDOOR_HOST
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

token=ACCESS_TOKEN&token_type_hint=access_token

ستتلقى الاستجابة التالية:

{
    "active": true,
    "client_id": "c58c...",
    "username": "admin",
    "token_type": "Bearer",
    "exp": 1647138242,
    "iat": 1646533442,
    "nbf": 1646533442,
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "aud": [
        "c58c..."
    ],
    "iss": "http://localhost:8000"
}

كيفية استخدام AccessToken

يمكنك استخدام AccessToken للوصول إلى واجهات برمجة تطبيقات Casdoor التي تتطلب مصادقة.

على سبيل المثال، هناك طريقتان مختلفتان لطلب /api/userinfo.

النوع 1: معامل الاستعلام

https://<CASDOOR_HOST>/api/userinfo?accessToken=<your_access_token>

النوع 2: رمز الحامل HTTP

https://<CASDOOR_HOST>/api/userinfo with the header: "Authorization: Bearer <your_access_token>"

Casdoor سيقوم بتحليل access_token وإرجاع معلومات المستخدم المقابلة وفقاً لـ scope. ستتلقى الاستجابة نفسها، والتي تبدو مثل هذا:

{
    "sub": "7a6b4a8a-b731-48da-bc44-36ae27338817",
    "iss": "http://localhost:8000",
    "aud": "c58c..."
}

إذا كنت تتوقع مزيداً من معلومات المستخدم، أضف scope عند الحصول على AccessToken في الخطوة Authorization Code Grant.

الاختلافات بين واجهات برمجة التطبيقات userinfo و get-account

• /api/userinfo: تعيد هذه الواجهة معلومات المستخدم كجزء من بروتوكول OIDC. توفر معلومات محدودة، تشمل فقط المعلومات الأساسية المحددة في معايير OIDC. للحصول على قائمة بالنطاقات المتاحة التي يدعمها Casdoor، يرجى الرجوع إلى قسم النطاقات المتاحة.

• /api/get-account: تسترجع هذه الواجهة كائن المستخدم للحساب الذي تم تسجيل الدخول إليه حالياً. هي واجهة خاصة بـ Casdoor تتيح لك الحصول على كل معلومات المستخدم في Casdoor.