طلب رموز الدخول ورموز التفويض

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

في هذا الموضوع، سنوضِّح لك كيفية طلب رموز الدخول ورموز التفويض، وضبط نقاط نهاية OAuth 2.0، وإعداد السياسات لكل نوع منح متوافق.

نموذج التعليمات البرمجية

للتيسير عليك، تتوفّر السياسات ونقاط النهاية التي تمت مناقشتها في هذا الموضوع على GitHub في مشروع oauth-doc-examples في مستودع نماذج واجهة برمجة التطبيقات Apigee. يمكنك نشر الرمز النموذجي وتجربة نماذج الطلبات المعروضة في هذا الموضوع. انظر المشروع README لمزيد من التفاصيل.

طلب رمز الدخول: نوع منح رمز التفويض

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

نموذج طلب

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

المَعلمات المطلوبة

بشكل تلقائي، يجب أن تكون هذه المَعلمات x-www-form-urlencoded وأن يتم تحديدها في نص الطلب (كما هو موضّح في النموذج أعلاه)، ولكن من الممكن تغيير هذا الإعداد التلقائي من خلال ضبط العناصر <GrantType> و<Code> و<RedirectUri> في سياسة OAuthV2 المرتبطة بنقطة النهاية /accesstoken هذه. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

  • grant_type - يجب ضبطه على القيمة authorization_code.
  • code (الرمز): هو رمز التفويض الذي يتم استلامه من نقطة النهاية /authorize (أو أي اسم آخر تختاره). لطلب رمز دخول خلال مسار نوع منح رمز التفويض، يجب أولاً الحصول على رمز التفويض. راجِع طلب رموز التفويض أدناه. راجِع أيضًا تنفيذ نوع منح رمز التفويض.
  • redirect_uri: يجب تقديم هذه المَعلمة إذا تمّ تضمين المَعلمة redirect_uri في طلب رمز التفويض السابق. إذا لم يتم تضمين المَعلمة redirect_uri في طلب رمز التفويض، وإذا لم تقدِّم هذه المَعلمة، ستستخدم هذه السياسة قيمة عنوان URL لمعاودة الاتصال التي تم توفيرها عند تسجيل تطبيق المطوِّر.

المَعلمات الاختيارية

  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

يجب ضبط معرِّف العميل وسر العميل إما على أنّه عنوان مصادقة أساسية (بترميز Base64) أو كمَعلمتَي نموذج client_id وclient_secret. يمكنك الحصول على هذه القيم من تطبيق مطوّر برامج مسجَّل. يمكنك أيضًا الاطّلاع على "ترميز بيانات اعتماد المصادقة الأساسية".

نموذج لنقطة نهاية

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

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

نموذج سياسة

هذه سياسة GenerateAccessToken أساسية مضبوطة على قبول نوع المنح "authorization_code". ولمزيد من المعلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة استجابة JSON التي تتضمّن رمز الدخول، كما هو موضّح أدناه. ينشئ نوع المنحة authorization_code رمز دخول ورمزان مميزان لإعادة التحميل، لذلك قد يبدو الردّ على النحو التالي:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

وفي حال ضبط السياسة <GenerateResponse> على "خطأ"، لن تعرِض السياسة أي استجابة. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات التدفق بالبيانات المتعلقة بمنح رمز الدخول.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

مثال:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

طلب رمز دخول: نوع منح بيانات اعتماد العميل

يوضّح هذا القسم طريقة طلب رمز الدخول باستخدام مسار نوع منح بيانات اعتماد العميل. للاطلاع على مقدمة عن أنواع منح بروتوكول OAuth 2.0، راجع مقدمة عن OAuth 2.0.

نموذج طلب

للحصول على معلومات عن ترميز عنوان المصادقة الأساسية في الاستدعاء التالي، يمكنك الاطّلاع على "ترميز بيانات اعتماد المصادقة الأساسية". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

المَعلمات المطلوبة

بشكل تلقائي، يجب أن تكون مَعلمة asset_type المطلوبة هي x-www-form-urlencoded وأن تكون محدّدة في نص الطلب (كما هو موضّح في النموذج أعلاه)، ولكن من الممكن تغيير هذا الإعداد التلقائي من خلال ضبط العنصر <GrantType> في سياسة OAuthV2 المرتبطة بنقطة نهاية /accesstoken هذه. على سبيل المثال، يمكنك اختيار تمرير المعلَمة في معلَمات طلب البحث. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

  • grant_type - يجب ضبطه على القيمة client_credentials.

المَعلمات الاختيارية

  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

يجب ضبط معرِّف العميل وسر العميل إما على أنّه عنوان مصادقة أساسية (بترميز Base64) أو كمَعلمتَين للنموذج client_id وclient_secret. يمكنك الحصول على هذه القيم من تطبيق المطوّر المسجَّل المرتبط بالطلب. راجِع أيضًا "ترميز بيانات اعتماد المصادقة الأساسية".

نموذج لنقطة نهاية

إليك نموذج لإعداد نقطة النهاية لإنشاء رمز دخول. وسينفِّذ سياسة GenerateAccessToken، التي يجب إعدادها لإتاحة نوع منح client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

نموذج سياسة

هذه سياسة GenerateAccessToken أساسية مضبوطة على قبول نوع المنح "client_credentials". ولمزيد من المعلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة استجابة JSON. ويُرجى العلم بأنّ الرموز المميّزة لإعادة التحميل غير متوافقة مع نوع منح الإذن client_credentials. يتم استخراج رمز الدخول فقط. مثال:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

وفي حال ضبط السياسة <GenerateResponse> على "خطأ"، لن تعرِض السياسة أي استجابة. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات التدفق بالبيانات المتعلقة بمنح رمز الدخول.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

مثال:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

طلب رمز دخول: نوع منح كلمة المرور

يوضِّح هذا القسم طريقة طلب رمز دخول باستخدام مسار نوع منح بيانات اعتماد كلمة مرور مالك المورد (كلمة المرور). للاطلاع على مقدمة عن أنواع منح بروتوكول OAuth 2.0، راجِع مقدمة عن OAuth 2.0.

للحصول على مزيد من التفاصيل حول نوع منح كلمة المرور، بما في ذلك فيديو مدته 4 دقائق يعرض كيفية تنفيذه، يمكنك الاطّلاع على تنفيذ نوع منح كلمة المرور.

نموذج طلب

للحصول على معلومات عن ترميز عنوان المصادقة الأساسية في الاستدعاء التالي، يمكنك الاطّلاع على "ترميز بيانات اعتماد المصادقة الأساسية". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

المَعلمات المطلوبة

بشكل تلقائي، يجب أن تكون هذه المَعلمات x-www-form-urlencoded وأن يتم تحديدها في نص الطلب (كما هو موضّح في النموذج أعلاه)، ولكن من الممكن تغيير هذا الإعداد التلقائي من خلال ضبط العناصر <GrantType> و<Username> و<Password> في سياسة OAuthV2 المرتبطة بنقطة النهاية /token هذه. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

يتم عادةً التحقق من بيانات اعتماد المستخدم من خلال وحدة تخزين بيانات الاعتماد باستخدام سياسة LDAP أو JavaScript.

  • grant_type - يجب الضبط على القيمة password.
  • username - اسم المستخدم لمالك المورد.
  • password - كلمة مرور مالك المورد.

المَعلمات الاختيارية

  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

يجب ضبط معرِّف العميل وسر العميل إما على أنّه عنوان مصادقة أساسية (بترميز Base64) أو كمَعلمتَين للنموذج client_id وclient_secret. يمكنك الحصول على هذه القيم من تطبيق المطوّر المسجَّل المرتبط بالطلب. راجِع أيضًا "ترميز بيانات اعتماد المصادقة الأساسية".

نموذج لنقطة نهاية

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

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

نموذج سياسة

هذه سياسة GenerateAccessToken أساسية تم إعدادها لقبول نوع منح كلمة المرور. لمزيد من المعلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة استجابة JSON. وتجدُر الإشارة إلى أنّه عند استخدام نوع منح كلمة المرور، يتم استخراج كل من رمز الدخول والرمز المميّز لإعادة التحميل. على سبيل المثال:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

وفي حال ضبط السياسة <GenerateResponse> على "خطأ"، لن تعرِض السياسة أي استجابة. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات التدفق بالبيانات المتعلقة بمنح رمز الدخول.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

مثال:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

طلب رمز الدخول: نوع المنح الضمني

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

نموذج طلب

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

المَعلمات المطلوبة

بشكل تلقائي، يجب أن تكون هذه المَعلمات معلَمات طلب بحث (كما هو موضّح في النموذج أعلاه)، ومع ذلك، من الممكن تغيير هذا الإعداد التلقائي من خلال ضبط العناصر <ResponseType> و<ClientId> و<RedirectUri> في سياسة OAuthV2 المرتبطة بنقطة نهاية /token هذه. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

يتم عادةً التحقق من بيانات اعتماد المستخدم من خلال وحدة تخزين بيانات الاعتماد باستخدام وسيلة شرح أو سياسة JavaScript لخدمة LDAP.

  • response_type: يجب ضبطها على القيمة token.
  • client_id - معرِّف العميل لتطبيق المطوِّر المسجَّل.
  • redirect_uri - هذه المَعلمة إلزامية إذا لم يتم تقديم معرّف الموارد المنتظم (URI) لمعاودة الاتصال أثناء تسجيل تطبيق مطوِّر العميل. وإذا تم تقديم عنوان URL لمعاودة الاتصال عند تسجيل العميل، ستتم مقارنته بهذه القيمة ويجب أن يتطابق تمامًا.

المَعلمات الاختيارية

  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

لا تتطلب المنحة الضمنية مصادقة أساسية. ستحتاج إلى تمرير معرّف العميل باعتباره معلَمة طلب، كما هو موضّح هنا.

نموذج لنقطة نهاية

إليك نموذج لإعداد نقطة النهاية لإنشاء رمز دخول. ينفِّذ سياسة GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

نموذج سياسة

هذه سياسة أساسية GenerateAccessTokenImplicitGrant تعالج طلبات الرموز المميزة لتدفق نوع المنح الضمني. للاطّلاع على معلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة إعادة التوجيه 302 للموقع الجغرافي في عنوان الاستجابة. تشير عملية إعادة التوجيه إلى عنوان URL المحدّد في المعلَمة redirect_uri، ويتم إلحاقها برمز الدخول ووقت انتهاء صلاحية الرمز المميّز. ويُرجى العلم بأنّ نوع المنح الضمني لا يتيح استخدام الرموز المميّزة لإعادة التحميل. مثال:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

وفي حال ضبط السياسة <GenerateResponse> على "خطأ"، لن تعرِض السياسة أي استجابة. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات التدفق بالبيانات المتعلقة بمنح رمز الدخول.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

مثال:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

طلب رمز تفويض

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

نموذج طلب

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

حيث يتم إرفاق سياسة OAuthV2 GenerateAuthCode في نقطة نهاية الخادم الوكيل /oauth/authorize (اطّلِع على نموذج نقطة النهاية أدناه).

المَعلمات المطلوبة

بشكل تلقائي، يجب أن تكون هذه المَعلمات معلَمات طلب بحث (كما هو موضّح في النموذج أعلاه)، ومع ذلك، من الممكن تغيير هذا الإعداد التلقائي من خلال ضبط العناصر <ResponseType> و<ClientId> و<RedirectUri> في سياسة OAuthV2 المرتبطة بنقطة نهاية /authorize هذه. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

  • response_type: يجب ضبطها على القيمة code.
  • client_id - معرِّف العميل لتطبيق المطوِّر المسجَّل.

المَعلمات الاختيارية

  • redirect_uri - إذا تم تحديد معرّف موارد منتظم (URI) لمعاودة الاتصال كامل (وليس جزئي) في تطبيق العميل المسجّل، تكون هذه المَعلمة اختيارية، وإلا تكون مطلوبة. معاودة الاتصال هي عنوان URL الذي يرسل إليه Edge رمز المصادقة الذي تم صينه حديثًا. اطّلِع أيضًا على تسجيل التطبيقات وإدارة مفاتيح واجهة برمجة التطبيقات.
  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

لا يتطلب الطلب مصادقة أساسية، ولكن يجب إدخال معرّف العميل لتطبيق العميل المسجَّل في الطلب.

نموذج لنقطة نهاية

في ما يلي نموذج لإعداد نقطة النهاية لإنشاء رمز تفويض:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

نموذج سياسة

هذه هي النهج الأساسي لـ GenerateAuthorizationCode. ولمزيد من المعلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة معلمة طلب البحث ?code إلى الموقع الجغرافي redirect_uri (معرّف الموارد المنتظم (URI) لمعاودة الاتصال) مع إرفاق رمز التفويض. يتم إرساله من خلال عملية إعادة توجيه 302 في المتصفّح مع عنوان URL في عنوان الاستجابة "الموقع الجغرافي". مثلاً: ?code=123456

في حال ضبط السياسة <GenerateResponse> على false، لن تعرِض السياسة ردًا. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات التدفق بالبيانات المتعلقة برمز التفويض.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

مثال:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

إعادة تحميل رمز الدخول

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

لطلب رمز دخول مميّز جديد باستخدام رمز مميّز لإعادة التحميل، اتّبِع الخطوات التالية:

نموذج طلب

للحصول على معلومات عن ترميز عنوان المصادقة الأساسية في الاستدعاء التالي، يمكنك الاطّلاع على "ترميز بيانات اعتماد المصادقة الأساسية". 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

المَعلمات المطلوبة

  • grant_type - يجب الضبط على القيمة refresh_token.
  • refresh_token: الرمز المميّز لإعادة التحميل المرتبط برمز الدخول الذي تريد تجديده.

تبحث السياسة تلقائيًا عن هذه مَعلمات x-www-form-urlencoded المحددة في نص الطلب، كما هو موضّح في المثال أعلاه. لضبط موقع بديل لهذه الإدخالات، يمكنك استخدام العنصرَين <GrantType> و<RefreshToken> في سياسة OAuthV2. لمعرفة التفاصيل، يُرجى الاطّلاع على سياسة OAuthV2.

المَعلمات الاختيارية

  • state - سلسلة سيتم إرسالها مع الرد. تُستخدم هذه المعلومات عادةً لمنع هجمات تزييف الطلبات من عدة مواقع إلكترونية.
  • scope: تسمح لك هذه السمة بفلترة قائمة منتجات واجهة برمجة التطبيقات التي يمكن استخدام الرمز المميّز الذي تم إنشاؤها من خلاله. للحصول على معلومات تفصيلية عن النطاق، يُرجى الاطّلاع على العمل باستخدام نطاقات OAuth2.

المصادقة

  • client_id
  • client_secret

يجب ضبط معرِّف العميل وسر العميل إما على أنّه عنوان مصادقة أساسية (بترميز Base64) أو كمَعلمتَي نموذج client_id وclient_secret. راجِع أيضًا "ترميز بيانات اعتماد المصادقة الأساسية".

عند إعادة تحميل رمز الدخول، لا تتم إعادة مصادقة المستخدم.

في ما يلي نموذج لإعدادات نقطة النهاية لإنشاء رمز دخول باستخدام رمز مميّز لإعادة التحميل. سينفذ السياسة refreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

نموذج سياسة

هذه سياسة RegisterAccessToken أساسية مضبوطة على قبول نوع منح الإذن refresh_token. ولمزيد من المعلومات عن عناصر الضبط الاختيارية التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

المرتجعات

عند تفعيل <GenerateResponse>، تعرض السياسة استجابة JSON تحتوي على رمز الدخول الجديد. يتيح نوع منح الإذن refresh_token سكّ كل من الرموز المميّزة للوصول والرموز الجديدة لإعادة التحميل. مثال:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

يُرجى العلم أنّه بعد النقر على رمز مميّز جديد للتحديث، لا يكون الرمز الأصلي صالحًا.

الرد أعلاه هو ما ستحصل عليه إذا تم ضبط <GenerateResponse> على "صحيح". وفي حال ضبط سياسة <GenerateResponse> على "خطأ"، لن تعرض السياسة أي استجابة. بدلاً من ذلك، تتم تعبئة المجموعة التالية من متغيّرات السياق (التدفق) بالبيانات المتعلقة بمنح رمز الدخول.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

مثال:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

ترميز بيانات اعتماد المصادقة الأساسية

ننصح باستخدام مواصفات OAuth 2.0 عند إجراء طلب بيانات من واجهة برمجة التطبيقات لطلب رمز مميّز أو رمز مصادقة، من أجل تمرير قيمتَي client_id وclient_secret كعنوان مصادقة HTTP الأساسية على النحو الموضّح في IETF RFC 2617. لإجراء ذلك، عليك ترميز نتيجة Base64 إلى نتيجة ضم القيمتَين مع نقطتَين يفصل بينهما.

بالرمز الزائف:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

في هذا المثال، ns4fQc14Zg4hKFCNaSzArVuwszX95X هو client_id وZIjFyTsNgQNyxI هو سر العميل.

بغض النظر عن لغة البرمجة التي تستخدمها لحساب القيمة بترميز base64، بالنسبة إلى بيانات اعتماد العميل هذه، تكون النتيجة التي بترميز base64 هي: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

بعد ذلك، يمكنك تقديم طلب الرمز المميّز على النحو التالي:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

ستنشئ الأداة المساعدة curl لك عنوان HTTP الأساسي إذا كنت تستخدم الخيار -u. يعادل ما يلي ما ورد أعلاه:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

قد تحتوي بيئات البرمجة الأخرى على اختصارات مشابهة تُنشئ تلقائيًا العنوان بترميز base64.

الرموز المميزة للتجزئة في قاعدة البيانات

لحماية الدخول عبر OAuth والرموز المميزة لإعادة التحميل في حال حدوث اختراق لأمان قاعدة البيانات، يمكنك تفعيل التجزئة التلقائية للرموز المميّزة في مؤسستك التي تستخدم Edge. عند تفعيل هذه الميزة، ينشئ Edge تلقائيًا نسخة مجزأة من الرموز المميزة للدخول وإعادة التحميل إلى OAuth التي تم إنشاؤها حديثًا باستخدام الخوارزمية التي تحدّدها. (في ما يلي معلومات حول الرموز المميّزة الحالية المرتبطة بالتجزئة المجمّعة). تُستخدم الرموز المميّزة غير المجزّأة في طلبات البيانات من واجهة برمجة التطبيقات، ويتحقّق منها Edge مقارنةً بالنسخ المجزّأة في قاعدة البيانات.

تتحكّم الخصائص التالية على مستوى المؤسسة في تجزئة رمز OAuth المميّز.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

إذا كانت لديك حاليًا رموز مميزة مجزّأة وتريد الاحتفاظ بها إلى أن تنتهي صلاحيتها، اضبط السمات التالية في مؤسستك، حيث تتطابق خوارزمية التجزئة مع الخوارزمية الحالية (على سبيل المثال، SHA1، أي خوارزمية Edge التلقائية السابقة). وإذا لم تكن الرموز المميّزة مجزّأة، استخدِم PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

إذا كنت أحد عملاء Edge على السحابة الإلكترونية، يمكنك التواصل مع فريق دعم Apigee Edge لضبط هذه السمات على مؤسستك، واختياريًا من أجل تجميع الرموز المميّزة الحالية للتجزئة.

مواضيع ذات صلة