درحال درخواست کدهای دسترسی و مجوز

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

در این موضوع، نحوه درخواست کردن برای دریافت کد دسترسی و کد صدور مجوز، پیکربندی نقطه‌های پایانی OAuth 2.0، و پیکربندی خط‌مشی‌ها برای هر نوع اعطای پشتیبانی‌شده را به شما نشان می‌دهیم.

کد نمونه

برای راحتی شما، خط‌مشی‌ها و نقاط پایانی که در این موضوع مورد بحث قرار گرفته‌اند در GitHub در پروژه oauth-doc-examples در مخزن Apigee api-platform-samples دردسترس هستند. می‌توانید کد نمونه را پیاده‌سازی کنید و درخواست‌های نمونه نشان‌داده‌شده در این موضوع را امتحان کنید. برای جزئیات، «من‌ومطالب» پروژه را ببینید.

درحال درخواست کردن کد دسترسی: نوع صدور کد احراز هویت

این بخش نحوه درخواست کردن کد دسترسی بااستفاده از جریان نوع اعطای کد مجوز را توضیح می‌دهد. برای آشنایی با انواع اعطای 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 تنظیم شود.
  • کد - کد مجوزی که از نقطه پایانی /authorize دریافت شده است (یا هر نامی که برای آن انتخاب کرده‌اید). برای درخواست کردن کد دسترسی در جریان نوع اعطای کد مجوز، ابتدا باید کد مجوز دریافت کنید. به درخواست کدهای مجوز در زیر مراجعه کنید. همچنین پیاده‌سازی نوع اعطای کد مجوز را ببینید.
  • redirect_uri - اگر پارامتر redirect_uri در درخواست کد مجوز قبلی گنجانده شده باشد، باید این پارامتر را ارائه دهید. اگر پارامتر redirect_uri در درخواست کد مجوز گنجانده نشده باشد، و اگر این پارامتر را ارائه نکنید، این خط‌مشی از مقدار «نشانی وب تماس برگشتی» که هنگام ثبت برنامه توسعه‌دهنده ارائه شده است استفاده می‌کند.

پارامترهای اختیاری

  • state - رشته‌ای که با پاسخ برگردانده می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین‌سایتی استفاده می‌شود.
  • scope - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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> روی false تنظیم شود، خط‌مشی پاسخی برنمی‌گرداند. درعوض، مجموعه متغیرهای جریان زیر را با داده‌های مربوط به اعطای کد دسترسی پر می‌کند.

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 تنظیم شود.

پارامترهای اختیاری

  • state - رشته‌ای که با پاسخ برگردانده می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین‌سایتی استفاده می‌شود.
  • scope - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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> روی false تنظیم شود، خط‌مشی پاسخی برنمی‌گرداند. درعوض، مجموعه متغیرهای جریان زیر را با داده‌های مربوط به اعطای کد دسترسی پر می‌کند.

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 مراجعه کنید.

برای جزئیات بیشتر درباره نوع اعطای گذرواژه، ازجمله ویدیو ۴ دقیقه‌ای که نحوه پیاده‌سازی آن را نشان می‌دهد، به پیاده‌سازی نوع اعطای گذرواژه مراجعه کنید.

درخواست نمونه

برای کسب اطلاعات درباره کدبندی سرصفحه اصالت‌سنجی پایه در تماس زیر، به «کدبندی اطلاعات اعتباری اصالت‌سنجی پایه» مراجعه کنید. 

$ 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 تنظیم شود.
  • نام کاربری - نام کاربری مالک منبع.
  • گذرواژه - گذرواژه مالک منبع.

پارامترهای اختیاری

  • state - رشته‌ای که با پاسخ برگردانده می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین‌سایتی استفاده می‌شود.
  • scope - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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> روی false تنظیم شود، خط‌مشی پاسخی برنمی‌گرداند. درعوض، مجموعه متغیرهای جریان زیر را با داده‌های مربوط به اعطای کد دسترسی پر می‌کند.

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 - اگر هنگام ثبت برنامه توسعه‌دهنده مشتری، «نشانی وب تماس برگشتی» ارائه نشده باشد، این پارامتر الزامی است. اگر «نشانی وب برگشت به تماس» در ثبت مشتری ارائه شده باشد، با این مقدار مقایسه می‌شود و باید دقیقاً مطابقت داشته باشد.

پارامترهای اختیاری

  • state - رشته‌ای که با پاسخ برگردانده می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین‌سایتی استفاده می‌شود.
  • دامنه - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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>، خط‌مشی یک تغییر مسیر «مکان ۳۰۲» در سرصفحه پاسخ برمی‌گرداند. هدایت به نشانی وب مشخص‌شده در پارامتر redirect_uri انجام می‌شود و کد دسترسی و زمان انقضای کد به آن اضافه می‌شود. توجه داشته باشید که نوع اعطای ضمنی از رمزهای بازآوری پشتیبانی نمی‌کند. برای مثال:

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

اگر <GenerateResponse> روی false تنظیم شود، خط‌مشی پاسخی برنمی‌گرداند. درعوض، مجموعه متغیرهای جریان زیر را با داده‌های مربوط به اعطای کد دسترسی پر می‌کند.

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 GenerateAuthorizationCode در /oauth/authorize نقطه پایانی پراکسی پیوست شده است (نقطه پایانی نمونه زیر را ببینید).

پارامترهای الزامی

به‌طور پیش‌فرض، این پارامترها باید پارامترهای پُرسمان باشند (همان‌طور که در نمونه بالا نشان داده شده است)؛ بااین‌حال، می‌توان با پیکربندی عناصر <ResponseType>، <ClientId>، و <RedirectUri> در خط‌مشی OAuthV2 که به این نقطه پایانی /authorize پیوست شده است، این پیش‌فرض را تغییر داد. برای جزئیات، خط‌مشی OAuthV2 را ببینید.

  • response_type - باید روی مقدار code تنظیم شود.
  • client_id - شناسه کارخواه برنامه توسعه‌دهنده ثبت‌شده.

پارامترهای اختیاری

  • redirect_uri - اگر «نشانی وب تماس برگشتی» کامل (نه جزئی) در برنامه کلاینت ثبت‌شده مشخص شده باشد، این پارامتر اختیاری است؛ درغیراین‌صورت، الزامی است. ‫callback نشانی وب جایی است که Edge کد مجوز جدید را ارسال می‌کند. همچنین ثبت برنامه‌ها و مدیریت کلیدهای میانای برنامه‌سازی کاربردی را ببینید.
  • state - رشته‌ای که با پاسخ برگردانده می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین‌سایتی استفاده می‌شود.
  • scope - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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 (نشانی وب تماس برگشتی) با کد مجوز پیوست‌شده برمی‌گرداند. این درخواست ازطریق هدایت مرورگر ۳۰۲ با نشانی وب در سرایند «مکان» پاسخ ارسال می‌شود. برای مثال: ?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 - به شما امکان می‌دهد فهرست محصولات API را که از توکن ضرب‌شده می‌توان با آن‌ها استفاده کرد فیلتر کنید. برای اطلاعات دقیق درباره حوزه، کار با حوزه‌های 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> روی false تنظیم شده باشد، خط‌مشی پاسخی برنمی‌گرداند. درعوض، مجموعه متغیرهای زمینه‌ای (جریان) زیر را با داده‌های مربوط به اعطای کد دسترسی پر می‌کند.

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

درحال کدبندی اعتبارنامه‌های اصالت‌سنجی پایه

وقتی برای درخواست کد اصالت‌سنجی یا کد دسترسی تماس API برقرار می‌کنید، بهتر است و مشخصات OAuth 2.0 توصیه می‌کند که مقادیر client_id و client_secret را به‌عنوان سرصفحه «اصالت‌سنجی پایه HTTP» ارسال کنید، همان‌طور که در IETF RFC 2617 توضیح داده شده است. برای انجام این کار، باید نتیجه پیوستن دو مقدار را با دونقطه به‌عنوان جداکننده آن‌ها، با پایه ۶۴ کدبندی کنید.

در شبه‌کد:

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

در این مثال، ns4fQc14Zg4hKFCNaSzArVuwszX95X شناسه کارخواه و ZIjFyTsNgQNyxI رمز کارخواه است.

صرف‌نظر از زبان برنامه‌نویسی که برای محاسبه مقدار کدبندی‌شده با ۶۴پایه استفاده می‌کنید، برای آن اطلاعات اعتباری مشتری، نتیجه کدبندی‌شده با ۶۴پایه این است: 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'

اگر از گزینه u- استفاده کنید، ابزار curl سرصفحه «پایه HTTP» را برایتان ایجاد می‌کند. مورد زیر معادل مورد بالا است:

$ 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 جدیداً تولیدشده بااستفاده از الگوریتمی که مشخص کرده‌اید ایجاد می‌کند. (اطلاعات مربوط به درهم‌سازی انبوه نشان‌های موجود در ادامه می‌آید.) از نشان‌های بدون درهم‌سازی در فراخوانی‌های API استفاده می‌شود و 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 تماس بگیرید.

موضوعات مرتبط