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

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

نموذج الرموز البرمجية

لتسهيل الأمر عليك، تتوفّر السياسات ونقاط النهاية التي تمت مناقشتها في هذا الموضوع على GitHub في مشروع oauth-doc-examples ضمن مستودع Apigee api-platform-samples. يمكنك نشر رمز نموذجي وتجربة نماذج الطلبات المعروضة في هذا الموضوع. راجِع ملف 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 لصفحة إعادة التوجيه التي تم تقديمها عند تسجيل تطبيق المطوّر.

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

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

المصادقة

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

نقطة نهاية العيّنة

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

...
       <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'

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

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

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

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

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

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

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

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

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

طلب رمز تفويض

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

نموذج طلب

$ 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 GenerateAuthorizationCode بنقطة نهاية الخادم الوكيل /oauth/authorize (راجِع نموذج نقطة النهاية أدناه).

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

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

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

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

  • redirect_uri: إذا تم تحديد معرّف موارد منتظم (URI) كامل (وليس جزئيًا) لعنوان URL لرد الاتصال في تطبيق العميل المسجَّل، تكون هذه المَعلمة اختيارية، وإلا تكون مطلوبة. عنوان URL الذي يرسل إليه Edge رمز التفويض الجديد. يمكنك أيضًا الاطّلاع على تسجيل التطبيقات وإدارة مفاتيح واجهة برمجة التطبيقات.
  • الحالة: سلسلة سيتم إرسالها مرة أخرى مع الرد. يُستخدم عادةً لمنع هجمات تزوير الطلبات من موقع إلكتروني مختلف.
  • 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 في رأس Location الخاص بالاستجابة. على سبيل المثال: ?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.

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

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

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

عند إجراء طلب بيانات من واجهة برمجة التطبيقات لطلب رمز مميّز أو رمز التفويض، يُنصح بتمرير قيمتَي معرِّف العميل وسر العميل كعنوان HTTP-Basic Authentication، كما هو موضّح في مجموعة مهندسي شبكة الإنترنت (IETF) RFC 2617، وذلك وفقًا لمواصفات OAuth 2.0. لإجراء ذلك، عليك ترميز نتيجة دمج القيمتَين معًا باستخدام 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 تلقائيًا نسخة مجزأة من رموز الدخول وإعادة التحميل الجديدة التي تم إنشاؤها باستخدام الخوارزمية التي تحدّدها. (في ما يلي معلومات عن التجزئة المجمّعة للرموز المميّزة الحالية). يتم استخدام الرموز المميّزة غير المجزّأة في طلبات البيانات من واجهة برمجة التطبيقات، ويتأكّد 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 Cloud، يُرجى التواصل مع فريق دعم Apigee Edge لضبط هذه الخصائص في مؤسستك، ويمكنك أيضًا تجزئة الرموز المميزة الحالية بشكل مجمّع.

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