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

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

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

کد نمونه

برای راحتی شما، خط‌مشی‌ها و نقاط پایانی مورد بحث در این مبحث در GitHub در پروژه oauth-doc-examples در مخزن Api-platform-samples Apigee موجود است. می توانید کد نمونه را اجرا کنید و نمونه درخواست های نشان داده شده در این مبحث را امتحان کنید. برای جزئیات به پروژه README مراجعه کنید.

درخواست رمز دسترسی: نوع اعطای کد مجوز

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

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

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

پارامترهای مورد نیاز

به طور پیش فرض، این پارامترها باید x-www-form-urlencoded و در بدنه درخواست مشخص شوند (همانطور که در نمونه بالا نشان داده شده است). با این حال، می‌توان این پیش‌فرض را با پیکربندی عناصر <GrantType> ، <Code> و <RedirectUri> در خط‌مشی OAuthV2 که به این نقطه پایانی /accesstoken متصل است، تغییر داد. برای جزئیات، به سیاست OAuthV2 مراجعه کنید.

  • grant_type - باید روی مقدار authorization_code تنظیم شود.
  • کد - کد مجوز دریافت شده از نقطه پایانی /authorize (یا هر نامی که انتخاب می کنید). برای درخواست رمز دسترسی در جریان نوع اعطای کد مجوز، ابتدا باید یک کد مجوز دریافت کنید. به درخواست کدهای مجوز در زیر مراجعه کنید. همچنین به اجرای نوع اعطای کد مجوز مراجعه کنید.
  • redirect_uri - اگر پارامتر redirect_uri در درخواست کد مجوز قبلی گنجانده شده باشد، باید این پارامتر را ارائه دهید. اگر پارامتر redirect_uri در درخواست کد مجوز گنجانده نشده است، و اگر این پارامتر را ارائه نکنید، این خط‌مشی از مقدار URL بازگشت به تماس استفاده می‌کند که هنگام ثبت برنامه برنامه‌نویس ارائه شده است.

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

  • state - رشته ای که همراه با پاسخ ارسال می شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می شود.
  • scope - به شما امکان می دهد لیست محصولات API را که می توان با آنها توکن ضرب شده استفاده کرد فیلتر کنید. برای اطلاعات دقیق در مورد دامنه، به کار با دامنه های OAuth2 مراجعه کنید.

احراز هویت

شما باید Client ID و Client Secret را به عنوان یک سرصفحه احراز هویت اولیه (با کدگذاری Base64) یا به عنوان پارامترهای فرم client_id و client_secret ارسال کنید. شما این مقادیر را از یک برنامه توسعه دهنده ثبت شده دریافت می کنید. همچنین به " رمزگذاری اعتبارنامه های اصلی احراز هویت " مراجعه کنید.

نقطه پایانی نمونه

در اینجا یک نمونه پیکربندی نقطه پایانی برای تولید یک نشانه دسترسی آمده است. این خط مشی GenerateAccessToken را اجرا می کند، که باید برای پشتیبانی از نوع اعطای autorization_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 مراجعه کنید.

احراز هویت

شما باید Client ID و Client Secret را به عنوان یک سرصفحه احراز هویت اولیه (با کدگذاری 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 مراجعه کنید.

برای جزئیات بیشتر در مورد نوع اعطای رمز عبور، از جمله یک ویدیوی 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 یا جاوا اسکریپت در برابر یک فروشگاه اعتبارسنجی تأیید می شود.

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

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

  • state - رشته ای که همراه با پاسخ ارسال می شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می شود.
  • scope - به شما امکان می دهد لیست محصولات API را که می توان با آنها توکن ضرب شده استفاده کرد فیلتر کنید. برای اطلاعات دقیق در مورد دامنه، به کار با دامنه های OAuth2 مراجعه کنید.

احراز هویت

شما باید Client ID و Client Secret را به عنوان یک سرصفحه احراز هویت اولیه (با کدگذاری 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 یا خط‌مشی جاوا اسکریپت در برابر یک فروشگاه اعتبارسنجی تأیید می‌شود.

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

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

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

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

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

  • redirect_uri - اگر یک URI کامل (نه جزئی) Callback در برنامه مشتری ثبت شده مشخص شده باشد، این پارامتر اختیاری است. در غیر این صورت، لازم است. Callback آدرسی است که Edge کد احراز هویت جدید را در آن ارسال می کند. همچنین به ثبت برنامه ها و مدیریت کلیدهای API مراجعه کنید.
  • 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 (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 - نشانه refresh مرتبط با نشانه دسترسی که می خواهید تمدید کنید.

به‌طور پیش‌فرض، این خط‌مشی به‌عنوان پارامترهای x-www-form-urlencoded مشخص‌شده در بدنه درخواست، همانطور که در مثال بالا نشان داده شده است، جستجو می‌کند. برای پیکربندی یک مکان جایگزین برای این ورودی‌ها، می‌توانید از عناصر <GrantType> و <RefreshToken> در خط‌مشی OAuthV2 استفاده کنید. برای جزئیات، به سیاست OAuthV2 مراجعه کنید.

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

  • state - رشته ای که همراه با پاسخ ارسال می شود. معمولاً برای جلوگیری از حملات جعل درخواست بین سایتی استفاده می شود.
  • scope - به شما امکان می دهد لیست محصولات API را که می توان با آنها توکن ضرب شده استفاده کرد فیلتر کنید. برای اطلاعات دقیق در مورد دامنه، به کار با دامنه های OAuth2 مراجعه کنید.

احراز هویت

  • client_id
  • client_secret

شما باید 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> روی 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، همانطور که در IETF RFC 2617 توضیح داده شده است، منتقل کنید. برای انجام این کار، باید نتیجه پیوستن این دو مقدار را با یک کولون که آنها را از هم جدا می کند، در base64-encode کنید.

در شبه کد:

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'

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

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