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

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

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

کد نمونه

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

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

  • state - رشته‌ای که همراه با پاسخ ارسال می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می‌شود.
  • دامنه - به شما امکان می‌دهد لیست محصولات 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 - رشته‌ای که همراه با پاسخ ارسال می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می‌شود.
  • دامنه - به شما امکان می‌دهد لیست محصولات 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 ، توکن‌های refresh پشتیبانی نمی‌شوند. فقط یک توکن دسترسی ایجاد می‌شود. برای مثال: 

{
    "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 یا جاوا اسکریپت در برابر یک مخزن اعتبارسنجی اعتبارسنجی می‌شوند.

  • grant_type - باید روی مقدار password تنظیم شود.
  • نام کاربری - نام کاربری صاحب منبع.
  • رمز عبور - رمز عبور صاحب منبع.

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

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

  • response_type - باید روی مقدار token تنظیم شود.
  • client_id - شناسه کلاینت یک برنامه توسعه‌دهنده ثبت‌شده.
  • redirect_uri - این پارامتر در صورتی اجباری است که هنگام ثبت برنامه توسعه‌دهنده کلاینت، URL بازگشتی ارائه نشده باشد. اگر URL بازگشتی در زمان ثبت کلاینت ارائه شده باشد، با این مقدار مقایسه شده و باید دقیقاً مطابقت داشته باشد.

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

  • 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> ، این خط‌مشی یک تغییر مسیر موقعیت مکانی 302 در هدر پاسخ برمی‌گرداند. این تغییر مسیر به URL مشخص شده در پارامتر 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 - اگر یک URL کامل (نه جزئی) برای فراخوانی در برنامه کلاینت ثبت شده مشخص شده باشد، این پارامتر اختیاری است؛ در غیر این صورت، الزامی است. فراخوانی، URL ای است که Edge کد احراز هویت تازه ایجاد شده را به آن ارسال می‌کند. همچنین به Register apps and manage API keys مراجعه کنید.
  • state - رشته‌ای که همراه با پاسخ ارسال می‌شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می‌شود.
  • دامنه - به شما امکان می‌دهد لیست محصولات 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 (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

به‌روزرسانی یک توکن دسترسی

توکن تازه‌سازی (Refresh Token) یک اعتبارنامه است که شما برای دریافت توکن دسترسی از آن استفاده می‌کنید، معمولاً پس از اینکه توکن دسترسی منقضی شده یا نامعتبر می‌شود. وقتی توکن دسترسی دریافت می‌کنید، یک توکن تازه‌سازی در پاسخ بازگردانده می‌شود.

برای درخواست یک توکن دسترسی جدید با استفاده از توکن رفرش:

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

برای اطلاعات بیشتر در مورد رمزگذاری هدر احراز هویت پایه در فراخوانی زیر، به « رمزگذاری اعتبارنامه‌های احراز هویت پایه » مراجعه کنید. 

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

احراز هویت

  • شناسه_مشتری
  • راز_مشتری

شما باید شناسه‌ی کلاینت و راز کلاینت را یا به عنوان یک هدر احراز هویت پایه (رمزگذاری شده با Base64) یا به عنوان پارامترهای فرم client_id و client_secret ارسال کنید. همچنین به « رمزگذاری اعتبارنامه‌های احراز هویت پایه » مراجعه کنید.

هنگام به‌روزرسانی توکن دسترسی، هیچ احراز هویت مجددی برای کاربر انجام نمی‌شود.

در اینجا یک نمونه پیکربندی نقطه پایانی برای تولید یک توکن دسترسی با استفاده از توکن تازه‌سازی (refresh token) آورده شده است. این پیکربندی، سیاست 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> روی true تنظیم شده باشد، پاسخ بالا را دریافت می‌کنید. اگر <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-Basic Authentication ارسال کنید، همانطور که در IETF RFC 2617 توضیح داده شده است. برای انجام این کار، باید نتیجه اتصال دو مقدار را با استفاده از یک دونقطه (:) که آنها را از هم جدا می‌کند، به صورت base64-encode کنید.

در شبه کد: 

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

در این مثال، ns4fQc14Zg4hKFCNaSzArVuwszX95X شناسه کلاینت و 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'

اگر از گزینه -u استفاده کنید، ابزار curl در واقع هدر HTTP Basic را برای شما ایجاد می‌کند. دستور زیر معادل دستور فوق است: 

$ 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 هستید، برای تنظیم این ویژگی‌ها در سازمان خود و به صورت اختیاری برای هش کردن انبوه توکن‌های موجود، با پشتیبانی Apigee Edge تماس بگیرید.

مباحث مرتبط