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

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

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

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

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

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

يوضّح هذا القسم كيفية طلب رمز دخول باستخدام نوع منح رمز التفويض. التدفق. للاطّلاع على مقدمة عن أنواع منح بروتوكول 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'

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

بشكل تلقائي، يجب أن تكون المعلمة المطلوبة ويتميز بـ 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
  • اسم المستخدم - اسم المستخدم لمالك المورد.
  • 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.

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

  • 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 Generate مفعَّلةCode في الموضع نقطة نهاية الخادم الوكيل /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>

نموذج سياسة

هذه هي سياسة أساسية لـ Generate الترخيصCode. للحصول على معلومات عن الإعدادات الاختيارية العناصر التي يمكنك ضبطها باستخدام هذه السياسة، راجِع سياسة 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>
...

نموذج سياسة

هذه سياسة RefreshAccessToken أساسية تم ضبطها لقبول نوع منحة واحدة (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). إذا كانت الرموز المميزة غير مجزأة، فاستخدم عادي.

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

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

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