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

Casdoor SDKs

مقدمة​

Compared to the standard OIDC protocol, Casdoor's SDK provides additional functionality, such as user management and resource uploading. Connecting to Casdoor via the Casdoor SDK requires more time than using a standard OIDC client library but provides the best flexibility and the most powerful API.

يمكن تقسيم حزم تطوير البرمجيات SDKs الخاصة بـ Casdoor إلى فئتين:

  1. Frontend SDK: SDKs for websites (like Javascript SDK, Vue SDK) and mobile apps (Android or iOS SDKs). Casdoor supports providing authentication for both websites and mobile applications.
  2. Backend SDK: SDKs للغات الواجهة الخلفية مثل Go، Java، Node.js، Python، PHP، وغيرها.
نصيحة

If your website is developed with a frontend-backend separation architecture, you can use the Javascript SDK: casdoor-js-sdk, React SDK: casdoor-react-sdk, or Vue SDK: casdoor-vue-sdk to integrate Casdoor in the frontend. If your web application is a traditional website developed with JSP or PHP, you can use backend SDKs only. انظر مثال: casdoor-python-vue-sdk-example

Mobile SDKوصفكود SDKكود مثال
Android SDKلتطبيقات Androidcasdoor-android-sdkcasdoor-android-example
iOS SDKلتطبيقات iOScasdoor-ios-sdkcasdoor-ios-example
React Native SDKلتطبيقات React Nativecasdoor-react-native-sdkcasdoor-react-native-example
Flutter SDKلتطبيقات Fluttercasdoor-flutter-sdkcasdoor-flutter-example
Firebase SDKلتطبيقات Google Firebasecasdoor-firebase-example
Unity Games SDKلألعاب Unity ثنائية/ثلاثية الأبعاد للحاسوب/الجوالcasdoor-dotnet-sdkcasdoor-unity-example
uni-app SDKلتطبيقات uni-appcasdoor-uniapp-sdkcasdoor-uniapp-example
حزمة تطوير سطح المكتبوصفكود SDKكود مثال
حزمة تطوير إلكترونلتطبيقات إلكترونcasdoor-js-sdkcasdoor-electron-example
حزمة تطوير .NET لسطح المكتبلتطبيقات .NET سطح المكتبcasdoor-dotnet-sdkWPF: casdoor-dotnet-desktop-example
WinForms: casdoor-dotnet-winform-example
Avalonia UI: casdoor-dotnet-avalonia-example
حزمة تطوير C/C++لتطبيقات C/C++ سطح المكتبcasdoor-cpp-sdkcasdoor-cpp-qt-example
حزمة تطوير واجهة الويب الأماميةوصفكود حزمة تطوير البرمجياتكود مثال
حزمة تطوير جافاسكريبتللمواقع الإلكترونية التقليدية غير الـ SPAcasdoor-js-sdkNodejs backend: casdoor-raw-js-example
Go backend: casdoor-go-react-sdk-example
Frontend-only SDKلمواقع الويب SPA التي تعمل بواجهة المستخدم فقطcasdoor-js-sdkcasdoor-react-only-example
React SDKلمواقع الويب التي تستخدم Reactcasdoor-react-sdkNodejs backend: casdoor-nodejs-react-example
Java backend: casdoor-spring-security-react-example
Next.js SDKلمواقع الويب التي تستخدم Next.jsnextjs-auth
Nuxt SDKلمواقع الويب التي تستخدم Nuxtnuxt-auth
Vue SDKFor Vue websitescasdoor-vue-sdkcasdoor-python-vue-sdk-example
Angular SDKFor Angular websitescasdoor-angular-sdkcasdoor-nodejs-angular-example
Flutter SDKFor Flutter Web websitescasdoor-flutter-sdkcasdoor-flutter-example
ASP.NET SDKFor ASP.NET Blazor WASM websitesBlazor.BFF.OpenIDConnect.Templatecasdoor-dotnet-blazorwasm-oidc-example
Firebase SDKFor Google Firebase appscasdoor-firebase-example

بعد ذلك، استخدم إحدى حزم تطوير البرمجيات SDK الخلفية التالية بناءً على لغة البرمجة الخاصة بالخلفية لديك:

حزمة تطوير الويب الخلفيةالوصفكود حزمة تطوير البرمجياتكود مثال
حزمة تطوير Goللخوادم الخلفية لـ Gocasdoor-go-sdkcasdoor-go-react-sdk-example
حزمة تطوير Javaللخوادم الخلفية لـ Javacasdoor-java-sdkcasdoor-spring-boot-starter, casdoor-spring-boot-example, casdoor-spring-security-react-example
حزمة تطوير Node.jsللخوادم الخلفية لـ Node.jscasdoor-nodejs-sdkcasdoor-nodejs-react-example
حزمة تطوير Pythonللخوادم الخلفية لـ Pythoncasdoor-python-sdkFlask: casdoor-python-vue-sdk-example
Django: casdoor-django-js-sdk-example
FastAPI: casdoor-fastapi-js-sdk-example
حزمة تطوير PHPللخوادم الخلفية لـ PHPcasdoor-php-sdkwordpress-casdoor-plugin
حزمة تطوير .NETللخوادم الخلفية لـ ASP.NETcasdoor-dotnet-sdkcasdoor-dotnet-sdk-example
حزمة تطوير Rustللخوادم الخلفية لـ Rustcasdoor-rust-sdkcasdoor-rust-example
حزمة تطوير C/C++للخوادم الخلفية لـ C/C++casdoor-cpp-sdkcasdoor-cpp-qt-example
حزمة تطوير Dartللخوادم الخلفية لـ Dartcasdoor-dart-sdk
حزمة تطوير Rubyللخوادم الخلفية لـ Rubycasdoor-ruby-sdk

للحصول على قائمة كاملة بـ SDKs الرسمية لـ Casdoor، يرجى الاطلاع على: https://github.com/orgs/casdoor/repositories?q=sdk&type=all&language=&sort=

كيفية استخدام حزمة تطوير البرمجيات SDK الخاصة بـ Casdoor؟​

1. تكوين حزمة تطوير البرمجيات SDK الخلفية​

When your application starts up, you need to initialize the Casdoor SDK configuration by calling the InitConfig() function with the required parameters. Using casdoor-go-sdk as an example: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

var CasdoorEndpoint = "https://door.casdoor.com"
var ClientId = "541738959670d221d59d"
var ClientSecret = "66863369a64a5863827cf949bab70ed560ba24bf"
var CasdoorOrganization = "casbin"
var CasdoorApplication = "app-casnode"

//go:embed token_jwt_key.pem
var JwtPublicKey string

func init() {
    auth.InitConfig(CasdoorEndpoint, ClientId, ClientSecret, JwtPublicKey, CasdoorOrganization, CasdoorApplication)
}

جميع المعاملات لـ InitConfig() موضحة كما يلي:

المعامليجبالوصف
نقطة النهايةنعمعنوان URL لخادم Casdoor، مثل https://door.casdoor.com أو http://localhost:8000
clientIdنعممعرف العميل لتطبيق Casdoor
clientSecretنعمسر العميل لتطبيق Casdoor
jwtPublicKeyنعمالمفتاح العام لشهادة تطبيق Casdoor
organizationNameنعمالاسم لمنظمة Casdoor
applicationNameلاالاسم لتطبيق Casdoor
نصيحة

يمكن إدارة jwtPublicKey في صفحة Certs كما يلي.

إدارة الشهادات Certs Management

يمكنك العثور على المفتاح العام في صفحة تحرير الشهادة، انسخه أو قم بتنزيله لـ SDK.

تحرير الشهادات Certs Edit

ثم يمكنك اختيار الشهادة في صفحة تحرير التطبيق.

اختيار الشهادات Certs Select

2. تكوين الواجهة الأمامية​

أولاً، قم بتثبيت casdoor-js-sdk عبر NPM أو Yarn:

npm install casdoor-js-sdk

أو:

yarn add casdoor-js-sdk

ثم قم بتعريف الوظائف المساعدة التالية (من الأفضل في ملف JS عالمي مثل Setting.js):

import Sdk from "casdoor-js-sdk";

export function initCasdoorSdk(config) {
  CasdoorSdk = new Sdk(config);
}

export function getSignupUrl() {
  return CasdoorSdk.getSignupUrl();
}

export function getSigninUrl() {
  return CasdoorSdk.getSigninUrl();
}

export function getUserProfileUrl(userName, account) {
  return CasdoorSdk.getUserProfileUrl(userName, account);
}

export function getMyProfileUrl(account) {
  return CasdoorSdk.getMyProfileUrl(account);
}

export function getMyResourcesUrl(account) {
  return CasdoorSdk.getMyProfileUrl(account).replace("/account?", "/resources?");
}

export function signin() {
  return CasdoorSdk.signin(ServerUrl);
}

export function showMessage(type, text) {
  if (type === "") {
    return;
  } else if (type === "success") {
    message.success(text);
  } else if (type === "error") {
    message.error(text);
  }
}

export function goToLink(link) {
  window.location.href = link;
}

في ملف الدخول لكود الواجهة الأمامية لديك (مثل index.js أو app.js في React)، تحتاج إلى تهيئة casdoor-js-sdk عن طريق استدعاء وظيفة InitConfig() بالمعاملات المطلوبة. يجب استخدام نفس القيمة للمعاملات الأربعة الأولى كما هو الحال في SDK الخلفي لـ Casdoor. المعامل الأخير redirectPath هو مسار نسبي لعنوان URL المعاد توجيهه، الذي يعود من صفحة تسجيل الدخول الخاصة بـ Casdoor.

const config = {
  serverUrl: "https://door.casdoor.com",
  clientId: "014ae4bd048734ca2dea",
  organizationName: "casbin",
  appName: "app-casnode",
  redirectPath: "/callback",
};

xxx.initCasdoorSdk(config);

(اختياري) نظرًا لأننا نستخدم React كمثال، فإن مسار /callback يصل إلى مسار React. نستخدم المكون React التالي لاستقبال استدعاء /callback وإرساله إلى الواجهة الخلفية. يمكنك تجاهل هذه الخطوة إذا كنت تقوم بالتوجيه مباشرةً إلى الواجهة الخلفية (مثل في JSP أو PHP).

import React from "react";
import {Button, Result, Spin} from "antd";
import {withRouter} from "react-router-dom";
import * as Setting from "./Setting";

class AuthCallback extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      classes: props,
      msg: null,
    };
  }

  componentWillMount() {
    this.login();
  }

  login() {
    Setting.signin().then((res) => {
      if (res.status === "ok") {
        Setting.showMessage("success", `Logged in successfully`);
        Setting.goToLink("/");
      } else {
        this.setState({
          msg: res.msg,
        });
      }
    });
  }

  render() {
    return (
      <div style={{textAlign: "center"}}>
        {this.state.msg === null ? (
          <Spin
            size="large"
            tip="Signing in..."
            style={{paddingTop: "10%"}}
          />
        ) : (
          <div style={{display: "inline"}}>
            <Result
              status="error"
              title="Login Error"
              subTitle={this.state.msg}
              extra={[
                <Button type="primary" key="details">
                  Details
                </Button>,
                <Button key="help">Help</Button>,
              ]}
            />
          </div>
        )}
      </div>
    );
  }
}

export default withRouter(AuthCallback);

3. الحصول على عناوين URL لتسجيل الدخول​

بعد ذلك يمكنك عرض أزرار أو روابط "التسجيل" و"تسجيل الدخول" لمستخدميك. يمكن استرداد عناوين URL إما في الواجهة الأمامية أو الخلفية. لمزيد من التفاصيل، انظر: /docs/basic/core-concepts#login-urls

4. الحصول على رمز الوصول والتحقق منه​

إليك الخطوات:

  1. ينقر المستخدم على عنوان URL لتسجيل الدخول ويتم توجيهه إلى صفحة تسجيل الدخول الخاصة بـ Casdoor، مثل: https://door.casdoor.com/login/oauth/authorize?client_id=014ae4bd048734ca2dea&response_type=code&redirect_uri=https%3A%2F%2Fforum.casbin.com%2Fcallback&scope=read&state=app-casnode
  2. يدخل المستخدم اسم المستخدم وكلمة المرور وينقر على Sign In (أو ينقر فقط على زر تسجيل الدخول بواسطة جهة خارجية مثل Sign in with GitHub).
  3. يتم إعادة توجيه المستخدم إلى تطبيقك مع رمز التفويض الصادر عن Casdoor (مثل: https://forum.casbin.com?code=xxx&state=yyy)، يحتاج الخلفية لتطبيقك إلى تبادل رمز التفويض مع رمز الوصول والتحقق من صحة رمز الوصول وأنه صادر عن Casdoor. الوظائف GetOAuthToken() و ParseJwtToken() مقدمة من SDK الخلفي لـ Casdoor.

يوضح الكود التالي كيفية الحصول على رمز الوصول والتحقق منه. لمثال حقيقي عن Casnode (موقع منتدى مكتوب بلغة Go)، انظر: https://github.com/casbin/casnode/blob/6d4c55f5c9a3c4bd8c85f2493abad3553b9c7ac0/controllers/account.go#L51-L64

// get code and state from the GET parameters of the redirected URL
code := c.Input().Get("code")
state := c.Input().Get("state")

// exchange the access token with code and state
token, err := auth.GetOAuthToken(code, state)
if err != nil {
    panic(err)
}

// verify the access token
claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
    panic(err)
}

إذا انتهت وظيفة ParseJwtToken() بدون خطأ، فهذا يعني أن المستخدم قد سجل الدخول بنجاح إلى التطبيق. يمكن استخدام claims المُرجعة لتحديد هوية المستخدم لاحقًا.

4. تحديد هوية المستخدم بواسطة رمز الوصول​

معلومات

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

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

المتغير claims الذي يعيده ParseJwtToken() معرف كما يلي:

type Claims struct {
    User
    AccessToken string `json:"accessToken"`
    jwt.RegisteredClaims
}
  1. User: كائن المستخدم، يحتوي على جميع المعلومات للمستخدم الذي قام بتسجيل الدخول، انظر التعريف في: /docs/basic/core-concepts#user
  2. AccessToken: سلسلة رمز الوصول.
  3. jwt.RegisteredClaims: بعض القيم الأخرى المطلوبة بواسطة JWT.

في هذه اللحظة، عادةً ما يكون للتطبيق طريقتان لتذكر جلسة المستخدم: session و JWT.

Session​

طريقة تعيين الجلسة تختلف اختلافًا كبيرًا حسب اللغة وإطار العمل الويب. على سبيل المثال، يستخدم Casnode إطار عمل Beego ويعين الجلسة بالاستدعاء: c.SetSessionUser().

token, err := auth.GetOAuthToken(code, state)
if err != nil {
    panic(err)
}

claims, err := auth.ParseJwtToken(token.AccessToken)
if err != nil {
    panic(err)
}

claims.AccessToken = token.AccessToken
c.SetSessionUser(claims) // set session

JWT​

رمز الوصول accessToken الذي يعيده Casdoor هو في الواقع JWT. لذا إذا كان تطبيقك يستخدم JWT للحفاظ على جلسة المستخدم، فقط استخدم رمز الوصول مباشرةً لذلك:

  1. إرسال رمز الوصول إلى الواجهة الأمامية، وحفظه في أماكن مثل localStorage للمتصفح.
  2. دع المتصفح يرسل رمز الوصول إلى الواجهة الخلفية لكل طلب.
  3. استدعي ParseJwtToken() أو وظيفتك الخاصة للتحقق من رمز الوصول والحصول على معلومات المستخدم الذي قام بتسجيل الدخول في الواجهة الخلفية لتطبيقك.

5. (اختياري) التفاعل مع جدول المستخدمين​

معلومات

هذا الجزء مقدم من Casdoor Public API وليس جزءًا من OIDC أو OAuth.

يوفر Casdoor Backend SDK العديد من الوظائف المساعدة، وليس محدودًا بـ:

  • GetUser(name string): الحصول على مستخدم بواسطة اسم المستخدم.
  • GetUsers(): الحصول على جميع المستخدمين.
  • AddUser(): إضافة مستخدم.
  • UpdateUser(): تحديث مستخدم.
  • DeleteUser(): حذف مستخدم.
  • CheckUserPassword(auth.User): التحقق من كلمة مرور المستخدم.

هذه الوظائف مُنفذة من خلال إجراء استدعاءات RESTful ضد Casdoor Public API. إذا لم تكن وظيفة معينة متوفرة في SDK الخلفي لـ Casdoor، يمكنك إجراء استدعاءات RESTful بنفسك.