خط مشی OAuthV2

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

چه

OAuthV2 یک سیاست چندوجهی برای انجام عملیات اعطای مجوز OAuth 2.0 است. این سیاست اصلی مورد استفاده برای پیکربندی نقاط پایانی OAuth 2.0 در Apigee Edge است.

نکته: اگر می‌خواهید درباره OAuth در Apigee Edge بیشتر بدانید، به صفحه اصلی OAuth مراجعه کنید. این صفحه لینک‌هایی به منابع، نمونه‌ها، ویدیوها و موارد دیگر ارائه می‌دهد. برای نمایش خوب نحوه استفاده از این سیاست در یک برنامه کاربردی، به نمونه پیشرفته OAuth در GitHub مراجعه کنید.

نمونه‌ها

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

همچنین به « رمزگذاری اعتبارنامه‌های احراز هویت پایه » مراجعه کنید.

مرجع عنصر

مرجع سیاست، عناصر و ویژگی‌های سیاست OAuthV2 را شرح می‌دهد.

سیاست نمونه نشان داده شده در زیر یکی از پیکربندی‌های ممکن است. این نمونه، یک سیاست OAuthV2 پیکربندی شده برای عملیات GenerateAccessToken را نشان می‌دهد. این سیاست شامل عناصر الزامی و اختیاری است. برای جزئیات بیشتر به توضیحات عناصر در این بخش مراجعه کنید.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

ویژگی‌های <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

عنصر <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

به طور پیش‌فرض، VerifyAccessToken انتظار دارد که توکن دسترسی در هدر Authorization ارسال شود. شما می‌توانید این پیش‌فرض را با استفاده از این عنصر تغییر دهید. به عنوان مثال request.queryparam.access_token نشان می‌دهد که توکن دسترسی باید به عنوان یک پارامتر پرس‌وجو با نام access_token ارائه شود.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

عنصر <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

به طور پیش‌فرض، VerifyAccessToken انتظار دارد که توکن دسترسی در یک هدر مجوز (Authorization header) به عنوان توکن حامل (Bearer token) ارسال شود. برای مثال:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

در حال حاضر، Bearer تنها پیشوند پشتیبانی شده است.

عنصر <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

در مواردی که شناسه کاربر نهایی برنامه باید به سرور تأیید ارسال شود، این عنصر به شما امکان می‌دهد مشخص کنید که Edge کجا باید شناسه کاربر نهایی را جستجو کند. به عنوان مثال، می‌تواند به عنوان یک پارامتر پرس و جو یا در یک هدر HTTP ارسال شود.

برای مثال request.queryparam.app_enduser نشان می‌دهد که AppEndUser باید به عنوان یک پارامتر پرس‌وجو وجود داشته باشد، مانند ?app_enduser=ntesla@theramin.com . برای درخواست AppEndUser در یک هدر HTTP، این مقدار را به request.header.app_enduser تنظیم کنید.

ارائه این تنظیم به شما امکان می‌دهد تا شناسه کاربر نهایی برنامه را در توکن دسترسی وارد کنید. این ویژگی در صورتی مفید است که بخواهید توکن‌های دسترسی OAuth 2.0 را بر اساس شناسه کاربر نهایی بازیابی یا لغو کنید. برای اطلاعات بیشتر، به بخش «فعال کردن بازیابی و لغو توکن‌های دسترسی OAuth 2.0 بر اساس شناسه کاربر نهایی، شناسه برنامه یا هر دو» مراجعه کنید.

<ویژگی‌ها/صفت>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

از این عنصر برای افزودن ویژگی‌های سفارشی به یک توکن دسترسی یا کد مجوز استفاده کنید. برای مثال، ممکن است بخواهید یک شناسه کاربری یا شناسه جلسه را در یک توکن دسترسی جاسازی کنید که بتواند در زمان اجرا استخراج و بررسی شود.

این عنصر به شما امکان می‌دهد مقداری را در یک متغیر جریان یا از یک رشته‌ی تحت‌اللفظی مشخص کنید. اگر هم یک متغیر و هم یک رشته را مشخص کنید، مقداری که در متغیر جریان مشخص شده است استفاده می‌شود. اگر متغیر قابل حل نباشد، رشته پیش‌فرض است.

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

نمایش یا پنهان کردن ویژگی‌های سفارشی در پاسخ

به یاد داشته باشید که اگر عنصر GenerateResponse این خط‌مشی را روی true تنظیم کنید، نمایش کامل JSON از توکن، شامل هر ویژگی سفارشی که تنظیم کرده‌اید، در پاسخ بازگردانده می‌شود. در برخی موارد، ممکن است بخواهید برخی یا همه ویژگی‌های سفارشی خود را در پاسخ پنهان کنید تا برای برنامه‌های کلاینت قابل مشاهده نباشند.

به طور پیش‌فرض، ویژگی‌های سفارشی در پاسخ ظاهر می‌شوند. اگر می‌خواهید آنها را پنهان کنید، می‌توانید پارامتر نمایش را روی false تنظیم کنید. برای مثال:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

مقدار ویژگی display ذخیره نمی‌شود. فرض کنید شما یک توکن دسترسی (access token) با ویژگی‌های سفارشی ایجاد می‌کنید که می‌خواهید در پاسخ تولید شده پنهان شوند. تنظیم display=false این هدف را محقق می‌کند. با این حال، اگر بعداً یک توکن دسترسی جدید با استفاده از یک توکن تازه‌سازی (refresh token) ایجاد شود، ویژگی‌های سفارشی اصلی از توکن دسترسی در پاسخ توکن تازه‌سازی نمایش داده می‌شوند. دلیل این امر این است که Edge به خاطر نمی‌آورد که ویژگی display در ابتدا در سیاست تولید توکن دسترسی (generate access token) روی false تنظیم شده است - ویژگی سفارشی صرفاً بخشی از فراداده توکن دسترسی است.

اگر ویژگی‌های سفارشی را به یک کد مجوز اضافه کنید، همین رفتار را خواهید دید -- وقتی یک توکن دسترسی با استفاده از آن کد ایجاد می‌شود، آن ویژگی‌های سفارشی در پاسخ توکن دسترسی نمایش داده می‌شوند. باز هم، ممکن است این رفتاری نباشد که شما مد نظر دارید.

برای پنهان کردن ویژگی‌های سفارشی در این موارد، این گزینه‌ها را دارید:

• ویژگی‌های سفارشی را به طور صریح در سیاست refresh token بازنشانی کنید و نمایش آنها را روی false تنظیم کنید. در این حالت، ممکن است لازم باشد مقادیر سفارشی اصلی را با استفاده از سیاست GetOAuthV2Info از توکن دسترسی اصلی بازیابی کنید.
• از یک سیاست جاوا اسکریپت پس‌پردازش برای استخراج دستی هرگونه ویژگی سفارشی که نمی‌خواهید در پاسخ ببینید، استفاده کنید.

همچنین به بخش سفارشی‌سازی توکن‌ها و کدهای مجوز مراجعه کنید.

عنصر <ClientId>

<ClientId>request.formparam.client_id</ClientId>

در چندین مورد، برنامه کلاینت باید شناسه کلاینت را به سرور مجوز ارسال کند. این عنصر مشخص می‌کند که Apigee باید شناسه کلاینت را در متغیر جریان request.formparam.client_id جستجو کند. تنظیم ClientId روی هر متغیر دیگری پشتیبانی نمی‌شود. همچنین به درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <کد>

<Code>request.queryparam.code</Code>

در جریان نوع اعطای مجوز، کلاینت باید یک کد مجوز را به سرور مجوز (Apigee Edge) ارسال کند. این عنصر به شما امکان می‌دهد مشخص کنید که Edge کجا باید به دنبال کد مجوز بگردد. به عنوان مثال، می‌تواند به عنوان یک پارامتر پرس و جو، هدر HTTP یا پارامتر فرم (پیش‌فرض) ارسال شود.

متغیر request.queryparam.auth_code نشان می‌دهد که کد مجوز باید به عنوان یک پارامتر پرس‌وجو، مانند مثلاً ?auth_code=AfGlvs9 ، ارائه شود. برای درخواست کد مجوز در یک هدر HTTP، به عنوان مثال، این مقدار را روی request.header.auth_code تنظیم کنید. همچنین به بخش درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <منقضی می‌شود>

<ExpiresIn>10000</ExpiresIn>

زمان انقضای توکن‌های دسترسی و کدهای مجوز را بر حسب میلی‌ثانیه اعمال می‌کند. (برای توکن‌های تازه‌سازی، از <RefreshTokenExpiresIn> استفاده کنید.) مقدار زمان انقضا، مقداری است که توسط سیستم به علاوه‌ی مقدار <ExpiresIn> تولید می‌شود. اگر <ExpiresIn> روی -1 تنظیم شده باشد، توکن یا کد مطابق با حداکثر انقضای توکن دسترسی OAuth منقضی می‌شود. اگر <ExpiresIn> مشخص نشده باشد، سیستم مقدار پیش‌فرض پیکربندی‌شده در سطح سیستم را اعمال می‌کند.

زمان انقضا را می‌توان در زمان اجرا با استفاده از یک مقدار پیش‌فرض و کدنویسی شده یا با ارجاع به یک متغیر جریان تنظیم کرد. به عنوان مثال، می‌توانید مقدار انقضای توکن را در یک نگاشت مقدار کلید ذخیره کنید، آن را بازیابی کنید، به یک متغیر اختصاص دهید و در سیاست به آن ارجاع دهید. به عنوان مثال، kvm.oauth.expires_in .

با Apigee Edge برای فضای ابری عمومی ، Edge موجودیت‌های زیر را حداقل به مدت ۱۸۰ ثانیه پس از دسترسی به آنها در حافظه پنهان (cache) نگه می‌دارد.

• توکن‌های دسترسی OAuth. این بدان معناست که یک توکن لغو شده ممکن است تا سه دقیقه، تا زمانی که محدودیت حافظه پنهان آن منقضی شود، همچنان موفق باشد.
• موجودیت‌های سرویس مدیریت کلید (KMS) (برنامه‌ها، توسعه‌دهندگان، محصولات API).
• ویژگی‌های سفارشی روی توکن‌های OAuth و موجودیت‌های KMS.

بند زیر یک متغیر جریان و یک مقدار پیش‌فرض را نیز مشخص می‌کند. توجه داشته باشید که مقدار متغیر جریان بر مقدار پیش‌فرض مشخص‌شده اولویت دارد.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

اج از روشی برای اعمال محدودیت انقضای توکن پس از ایجاد آن پشتیبانی نمی‌کند. اگر نیاز به اعمال محدودیت انقضای توکن دارید (مثلاً بر اساس یک شرط)، یک راه حل ممکن در این پست انجمن Apigee شرح داده شده است.

به طور پیش‌فرض، توکن‌های دسترسی منقضی شده، ۳ روز پس از انقضا به طور خودکار از سیستم Apigee Edge پاک می‌شوند. همچنین به بخش پاک کردن توکن‌های دسترسی مراجعه کنید.

ابر خصوصی: برای نصب Edge برای ابر خصوصی، مقدار پیش‌فرض توسط ویژگی conf_keymanagement_oauth_auth_code_expiry_time_in_millis تنظیم می‌شود. برای تنظیم این ویژگی:

1. فایل message-processor.properties را در یک ویرایشگر باز کنید. اگر فایل وجود ندارد، آن را ایجاد کنید:

   vi /opt/apigee/customer/application/message-processor.properties

2. ویژگی را به دلخواه تنظیم کنید:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. مطمئن شوید که فایل properties متعلق به کاربر "apigee" است:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. پردازشگر پیام را مجدداً راه‌اندازی کنید.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

عنصر <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

به Apigee Edge می‌گوید که کجا یک توکن دسترسی خارجی (یک توکن دسترسی که توسط Apigee Edge تولید نشده است) را پیدا کند.

متغیر request.queryparam.external_access_token نشان می‌دهد که توکن دسترسی خارجی باید به عنوان یک پارامتر پرس‌وجو ارائه شود، مثلاً ?external_access_token=12345678 . برای درخواست توکن دسترسی خارجی در یک هدر HTTP، به عنوان مثال، این مقدار را روی request.header.external_access_token تنظیم کنید. همچنین به بخش استفاده از توکن‌های OAuth شخص ثالث مراجعه کنید.

عنصر <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

اگر این عنصر نادرست باشد یا وجود نداشته باشد، Edge به طور معمول client_id و client_secret را در برابر مخزن مجوز Apigee Edge اعتبارسنجی می‌کند. از این عنصر زمانی استفاده کنید که می‌خواهید با توکن‌های OAuth شخص ثالث کار کنید. برای جزئیات بیشتر در مورد استفاده از این عنصر، به بخش «استفاده از توکن‌های OAuth شخص ثالث» مراجعه کنید.

عنصر <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

به Apigee Edge می‌گوید که کجا یک کد تأیید خارجی (کد تأییدی که توسط Apigee Edge تولید نشده است) را پیدا کند.

متغیر request.queryparam.external_auth_code نشان می‌دهد که کد احراز هویت خارجی باید به عنوان یک پارامتر کوئری وجود داشته باشد، به عنوان مثال، ?external_auth_code=12345678 . برای درخواست کد احراز هویت خارجی در یک هدر HTTP، به عنوان مثال، این مقدار را روی request.header.external_auth_code تنظیم کنید. همچنین به بخش استفاده از توکن‌های OAuth شخص ثالث مراجعه کنید.

عنصر <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

به Apigee Edge می‌گوید که کجا یک توکن به‌روزرسانی خارجی (یک توکن به‌روزرسانی که توسط Apigee Edge تولید نشده است) پیدا کند.

متغیر request.queryparam.external_refresh_token نشان می‌دهد که توکن به‌روزرسانی خارجی باید به عنوان یک پارامتر پرس‌وجو ارائه شود، مثلاً ?external_refresh_token=12345678 . برای درخواست توکن به‌روزرسانی خارجی در یک هدر HTTP، به عنوان مثال، این مقدار را روی request.header.external_refresh_token تنظیم کنید. همچنین به بخش استفاده از توکن‌های OAuth شخص ثالث مراجعه کنید.

عنصر <GenerateResponse>

<GenerateResponse enabled='true'/>

اگر روی true تنظیم شود، این سیاست یک پاسخ تولید و برمی‌گرداند. برای مثال، برای GenerateAccessToken، پاسخ ممکن است مانند زیر باشد:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

اگر false ، هیچ پاسخی ارسال نمی‌شود. در عوض، مجموعه‌ای از متغیرهای جریان با مقادیری مرتبط با تابع سیاست پر می‌شوند. برای مثال، یک متغیر جریان به نام oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code با کد احراز هویت تازه ایجاد شده پر می‌شود. توجه داشته باشید که expires_in در پاسخ بر حسب ثانیه بیان می‌شود.

عنصر <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

اگر روی true تنظیم شود، سیاست پاسخی تولید و برمی‌گرداند اگر ویژگی ContinueOnError روی true تنظیم شده باشد. اگر false (پیش‌فرض) باشد، هیچ پاسخی ارسال نمی‌شود. در عوض، مجموعه‌ای از متغیرهای جریان با مقادیری مرتبط با تابع سیاست پر می‌شوند.

<نوع کمک هزینه>

<GrantType>request.queryparam.grant_type</GrantType>

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

برای مثال request.queryparam.grant_type نشان می‌دهد که رمز عبور باید به عنوان یک پارامتر پرس و جو، مانند ?grant_type=password ، ارائه شود. برای مثال، برای درخواست نوع اعطای دسترسی در یک هدر HTTP، این مقدار را روی request.header.grant_type تنظیم کنید. همچنین به درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <عملیات>

<Operation>GenerateAuthorizationCode</Operation>

عملیات OAuth 2.0 که توسط این سیاست اجرا شده است.

عنصر <PassWord>

<PassWord>request.queryparam.password</PassWord>

این عنصر فقط با نوع اعطای رمز عبور استفاده می‌شود . با نوع اعطای رمز عبور، اعتبارنامه‌های کاربر (رمز عبور و نام کاربری) باید در اختیار خط‌مشی OAuthV2 قرار گیرند. عناصر <PassWord> و <UserName> برای مشخص کردن متغیرهایی استفاده می‌شوند که Edge می‌تواند این مقادیر را در آنها پیدا کند. اگر این عناصر مشخص نشوند، خط‌مشی انتظار دارد مقادیر را (به طور پیش‌فرض) در پارامترهای فرم به نام username و password پیدا کند. اگر مقادیر یافت نشوند، خط‌مشی خطا می‌دهد. می‌توانید از عناصر <PassWord> و <UserName> برای ارجاع به هر متغیر جریانی که حاوی اعتبارنامه‌ها است استفاده کنید.

برای مثال، می‌توانید رمز عبور را در یک درخواست توکن با استفاده از یک پارامتر پرس‌وجو ارسال کنید و عنصر را به این صورت تنظیم کنید: <PassWord>request.queryparam.password</PassWord> . برای درخواست رمز عبور در یک هدر HTTP، این مقدار را روی request.header.password تنظیم کنید.

سیاست OAuthV2 هیچ کار دیگری با این مقادیر اعتبارنامه انجام نمی‌دهد؛ Edge صرفاً وجود آنها را تأیید می‌کند. این وظیفه توسعه‌دهنده API است که درخواست مقادیر را بازیابی کرده و آنها را قبل از اجرای سیاست تولید توکن به یک ارائه‌دهنده هویت ارسال کند.

همچنین به درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

مشخص می‌کند که Edge باید در کجای درخواست، پارامتر redirect_uri را جستجو کند.

درباره URI های تغییر مسیر

URI های تغییر مسیر با کد مجوز و انواع اعطای ضمنی استفاده می‌شوند. URI تغییر مسیر به سرور مجوز (Edge) می‌گوید که کد مجوز (برای نوع اعطای کد تأیید) یا توکن دسترسی (برای نوع اعطای ضمنی) را به کجا ارسال کند. درک این نکته مهم است که این پارامتر چه زمانی الزامی، چه زمانی اختیاری و چگونه استفاده می‌شود:

• (الزامی) اگر یک URL بازگشتی در برنامه توسعه‌دهنده ثبت شده باشد که با کلیدهای کلاینت درخواست مرتبط است، و اگر redirect_uri در درخواست وجود داشته باشد، این دو باید دقیقاً با هم مطابقت داشته باشند. اگر مطابقت نداشته باشند، خطایی بازگردانده می‌شود. برای اطلاعات در مورد ثبت برنامه‌های توسعه‌دهنده در Edge و تعیین URL بازگشتی، به ثبت برنامه‌ها و مدیریت کلیدهای API مراجعه کنید.

• (اختیاری) اگر یک URL برگشتی ثبت شده باشد و redirect_uri از درخواست حذف شده باشد، Edge به URL برگشتی ثبت شده هدایت می‌شود.
• (الزامی) اگر یک URL برگشتی ثبت نشده باشد، redirect_uri الزامی است. توجه داشته باشید که در این حالت، Edge هر URL را می‌پذیرد. این مورد می‌تواند یک مشکل امنیتی ایجاد کند و بنابراین فقط باید با برنامه‌های کلاینت قابل اعتماد استفاده شود. اگر برنامه‌های کلاینت قابل اعتماد نیستند، بهترین روش این است که همیشه ثبت یک URL برگشتی الزامی باشد.

می‌توانید این پارامتر را در یک پارامتر پرس‌وجو یا در یک هدر ارسال کنید. متغیر request.queryparam.redirect_uri نشان می‌دهد که RedirectUri باید به عنوان یک پارامتر پرس‌وجو وجود داشته باشد، مثلاً ?redirect_uri=login.myapp.com . برای درخواست RedirectUri در یک هدر HTTP، به عنوان مثال، این مقدار را روی request.header.redirect_uri تنظیم کنید. همچنین به درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

هنگام درخواست یک توکن دسترسی با استفاده از توکن تازه‌سازی، باید توکن تازه‌سازی را در درخواست ارائه دهید. این عنصر به شما امکان می‌دهد مشخص کنید که Edge کجا باید توکن تازه‌سازی را جستجو کند. به عنوان مثال، می‌تواند به عنوان یک پارامتر پرس‌وجو، هدر HTTP یا پارامتر فرم (پیش‌فرض) ارسال شود.

متغیر request.queryparam.refreshtoken نشان می‌دهد که توکن refresh باید به عنوان یک پارامتر query، مانند ?refresh_token=login.myapp.com ، ارائه شود. برای مثال، برای درخواست RefreshToken در یک هدر HTTP، این مقدار را روی request.header.refresh_token تنظیم کنید. همچنین به بخش درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

زمان انقضای توکن‌های به‌روزرسانی را بر حسب میلی‌ثانیه اعمال می‌کند. مقدار زمان انقضا، مقداری است که سیستم تولید می‌کند به علاوه‌ی مقدار <RefreshTokenExpiresIn> . اگر <RefreshTokenExpiresIn> روی ... تنظیم شده باشد. -1 ‎، توکن به‌روزرسانی طبق حداکثر انقضای توکن به‌روزرسانی OAuth منقضی می‌شود. اگر <RefreshTokenExpiresIn> مشخص نشده باشد، سیستم مقدار پیش‌فرض پیکربندی‌شده در سطح سیستم را اعمال می‌کند. برای اطلاعات بیشتر در مورد تنظیمات پیش‌فرض سیستم با پشتیبانی Apigee Edge تماس بگیرید.

زمان انقضا را می‌توان در زمان اجرا با استفاده از یک مقدار پیش‌فرض و کدنویسی شده یا با ارجاع به یک متغیر جریان تنظیم کرد. به عنوان مثال، می‌توانید مقدار انقضای توکن را در یک نگاشت مقدار کلید ذخیره کنید، آن را بازیابی کنید، به یک متغیر اختصاص دهید و در سیاست به آن ارجاع دهید. به عنوان مثال، kvm.oauth.expires_in .

بند زیر یک متغیر جریان و یک مقدار پیش‌فرض را نیز مشخص می‌کند. توجه داشته باشید که مقدار متغیر جریان بر مقدار پیش‌فرض مشخص‌شده اولویت دارد.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

ابر خصوصی: برای نصب Edge برای ابر خصوصی، مقدار پیش‌فرض توسط ویژگی conf_keymanagement_oauth_refresh_token_expiry_time_in_millis تنظیم می‌شود. برای تنظیم این ویژگی:

1. فایل message-processor.properties را در یک ویرایشگر باز کنید. اگر فایل وجود ندارد، آن را ایجاد کنید:

   vi /opt/apigee/customer/application/message-processor.properties

2. ویژگی را به دلخواه تنظیم کنید:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. مطمئن شوید که فایل properties متعلق به کاربر "apigee" است:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. پردازشگر پیام را مجدداً راه‌اندازی کنید.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

عنصر <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

این عنصر به Edge اطلاع می‌دهد که برنامه‌ی کلاینت کدام نوع مجوز را درخواست می‌کند. این عنصر فقط با کد مجوز و جریان‌های نوع مجوز ضمنی استفاده می‌شود.

به طور پیش‌فرض، Edge به دنبال مقدار نوع پاسخ در پارامتر پرس‌وجوی response_type می‌گردد. اگر می‌خواهید این رفتار پیش‌فرض را لغو کنید، از عنصر <ResponseType> برای پیکربندی یک متغیر جریان حاوی مقدار نوع پاسخ استفاده کنید. برای مثال، اگر این عنصر را روی request.header.response_type تنظیم کنید، Edge به دنبال نوع پاسخی می‌گردد که باید در هدر درخواست ارسال شود. همچنین به Requesting access tokens and authorization codes مراجعه کنید.

عنصر <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

وقتی روی true تنظیم شود، توکن به‌روزرسانی موجود تا زمان انقضا دوباره استفاده می‌شود. اگر false ، وقتی یک توکن به‌روزرسانی معتبر ارائه شود، یک توکن به‌روزرسانی جدید توسط Apigee Edge صادر می‌شود.

عنصر <scope>

<Scope>request.queryparam.scope</Scope>

اگر این عنصر در یکی از سیاست‌های GenerateAccessToken یا GenerateAuthorizationCode وجود داشته باشد، برای مشخص کردن اینکه کدام حوزه‌ها باید توکن یا کد را اعطا کنند، استفاده می‌شود. این مقادیر معمولاً در درخواست از یک برنامه کلاینت به سیاست ارسال می‌شوند. می‌توانید عنصر را طوری پیکربندی کنید که یک متغیر جریان را بپذیرد و به شما این امکان را می‌دهد که نحوه ارسال حوزه‌ها را در یک درخواست انتخاب کنید. در مثال زیر، request.queryparam.scope نشان می‌دهد که حوزه باید به عنوان یک پارامتر پرس و جو، به عنوان مثال، ?scope=READ ، ارائه شود. برای مثال، برای الزام حوزه در یک هدر HTTP، این مقدار را روی request.header.scope تنظیم کنید.

اگر این عنصر در یک سیاست "VerifyAccessToken" ظاهر شود، برای مشخص کردن محدوده‌هایی که سیاست باید اعمال کند، استفاده می‌شود. در این نوع سیاست، مقدار باید یک نام محدوده "کدگذاری شده" باشد -- نمی‌توانید از متغیرها استفاده کنید. برای مثال:

<Scope>A B</Scope>

همچنین به بخش کار با دامنه‌های OAuth2 و درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <State>

<State>request.queryparam.state</State>

در مواردی که برنامه کلاینت باید اطلاعات وضعیت را به سرور احراز هویت ارسال کند، این عنصر به شما امکان می‌دهد مشخص کنید که Edge کجا باید به دنبال مقادیر وضعیت بگردد. به عنوان مثال، می‌تواند به عنوان یک پارامتر پرس و جو یا در یک هدر HTTP ارسال شود. مقدار وضعیت معمولاً به عنوان یک اقدام امنیتی برای جلوگیری از حملات CSRF استفاده می‌شود.

برای مثال request.queryparam.state نشان می‌دهد که وضعیت باید به عنوان یک پارامتر پرس‌وجو، مانند ?state=HjoiuKJH32 ، ارائه شود. برای مثال، برای الزام وضعیت در یک هدر HTTP، این مقدار را روی request.header.state تنظیم کنید. همچنین به بخش درخواست توکن‌های دسترسی و کدهای مجوز مراجعه کنید.

عنصر <StoreToken>

 <StoreToken>true</StoreToken>

وقتی عنصر <ExternalAuthorization> true است، این عنصر را روی true تنظیم کنید. عنصر <StoreToken> به Apigee Edge می‌گوید که توکن دسترسی خارجی را ذخیره کند. در غیر این صورت، ذخیره نخواهد شد.

عنصر <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

انواع کمک‌هزینه پشتیبانی‌شده توسط یک نقطه پایانی توکن OAuth در Apigee Edge را مشخص می‌کند. یک نقطه پایانی ممکن است از چندین نوع کمک‌هزینه پشتیبانی کند (یعنی، یک نقطه پایانی می‌تواند برای توزیع توکن‌های دسترسی برای چندین نوع کمک‌هزینه پیکربندی شود.) برای اطلاعات بیشتر در مورد نقاط پایانی، به درک نقاط پایانی OAuth مراجعه کنید. نوع کمک‌هزینه در درخواست‌های توکن در یک پارامتر grant_type ارسال می‌شود.

اگر هیچ نوع کمک‌هزینه پشتیبانی‌شده‌ای مشخص نشده باشد، تنها انواع کمک‌هزینه مجاز authorization_code و implicit هستند. همچنین به عنصر <GrantType> مراجعه کنید (که یک عنصر سطح بالاتر است که برای مشخص کردن جایی که Apigee Edge باید پارامتر grant_type را که در درخواست کلاینت ارسال می‌شود، جستجو کند، استفاده می‌شود. Edge مطمئن می‌شود که مقدار پارامتر grant_type با یکی از انواع کمک‌هزینه پشتیبانی‌شده مطابقت دارد).

عنصر <Tokens>/<Token>

با عملیات ValidateToken و InvalidateToken استفاده می‌شود. همچنین به بخش تأیید و لغو توکن‌های دسترسی مراجعه کنید. عنصر <Token> متغیر جریانی را مشخص می‌کند که منبع توکنی را که باید لغو شود تعریف می‌کند. اگر از توسعه‌دهندگان انتظار می‌رود توکن‌های دسترسی را به عنوان پارامترهای پرس‌وجو با نام access_token ارسال کنند، برای مثال، request.queryparam.access_token استفاده کنید.

عنصر <نام کاربری>

<UserName>request.queryparam.user_name</UserName>

This element is used with the password grant type only . With the password grant type, user credentials (password and username) must be made available to the OAuthV2 policy. The <PassWord> and <UserName> elements are used to specify variables where Edge can find these values. If these elements are not specified, the policy expects to find the values (by default) in form parameters named username and password . If the values are not found, the policy throws an error. You can use the <PassWord> and <UserName> elements to reference any flow variable containing the credentials.

For example, you can pass the username in a query parameter and set the <UserName> element like this: <UserName>request.queryparam.username</UserName> . To require the username in an HTTP header, set this value to request.header.username .

The OAuthV2 policy doesn't do anything else with these credential values; Edge is simply verifying that they are present. It is up to the API developer to retrieve the values request and send them to an identity provider before the token generation policy executes.

See also Requesting access tokens and authorization codes .

Verifying access tokens

Once a token endpoint is set up for an API proxy, a corresponding OAuthV2 policy that specifies the VerifyAccessToken operation is attached to the Flow that exposes the protected resource.

For example, to ensure that all requests to an API are authorized, the following policy enforces access token verification:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

The policy is attached to the API resource to be protected. To ensure that all requests to an API are verified, attach the policy to the ProxyEndpoint request PreFlow, as follows:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

The following optional elements can be used to override the default settings for the VerifyAccessToken operation.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

See also Verifying access tokens and Requesting access tokens and authorization codes .

Specifying request variable locations

For each grant type, the policy makes assumptions about the location or required information in request messages. These assumptions are based on the OAuth 2.0 specification. If your apps need to deviate from the OAuth 2.0 specification, then you can specify the expected locations for each parameter. For example, when handling an authorization code, you can specify the location of the authorization code, the client ID, the redirect URI, and the scope. These can be specified as HTTP headers, query parameters, or form parameters.

The example below demonstrates how you can specify the location of required authorization code parameters as HTTP headers:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Or, if necessary to support your client app base, you can mix and match headers and query parameters:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Only one location can be configured per parameter.

Flow variables

The flow variables defined in this table are populated when the respective OAuth policies are executed, and hence are available to other policies or applications executing in the API proxy flow.

VerifyAccessToken operation

The VerifyAccessToken operation executes, a large number of flow variables are populated in the proxy's execution context. These variables give you properties related to the access token, developer app, developer, and company. You can use an AssignMessage or JavaScript policy, for example, to read any of these variables and use them as needed later in the flow. These variables can also be useful for debugging purposes.

Token-specific variables

App-specific variables

These variables are related to the Developer App that is associated with the token.

Developer-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

Company-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

GenerateAuthorizationCode operation

These variables are set when the GenerateAuthorizationCode operation executes successfully:

Prefix: oauthv2authcode.{policy_name}.{variable_name}

Example: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken and RefreshAccessToken operations

These variables are set when the GenerateAccessToken and RefreshAccessToken operations execute successfully. Note that refresh token variables do not apply for the client credentials grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

These variables are set when the GenerateAccessTokenImplicit operation executes successfully for the implicit grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.RefreshTokenPolicy.access_token

Error reference

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که این خط مشی خطایی را در زمان اجرا ایجاد کند.

نمونه پاسخ خطا

اگر عنصر <GenerateResponse> درست باشد، این پاسخ‌ها به مشتری بازگردانده می‌شوند.

اگر <GenerateResponse> درست باشد، خط مشی خطاهایی را در این قالب برای عملیاتی که توکن ها و کدها را تولید می کنند، برمی گرداند. برای فهرست کامل، به مرجع پاسخ به خطای HTTP OAuth مراجعه کنید.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

اگر <GenerateResponse> درست باشد، خط مشی خطاهایی را در این قالب برای تأیید و تأیید عملیات برمی‌گرداند. برای فهرست کامل، به مرجع پاسخ به خطای HTTP OAuth مراجعه کنید.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

مثال قانون خطا

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Policy schema

Each policy type is defined by an XML schema ( .xsd ). For reference, policy schemas are available on GitHub.

Working with the default OAuth configuration

Each organization (even a free trial org) on Apigee Edge is provisioned with an OAuth token endpoint. The endpoint is preconfigured with policies in the API proxy called oauth . You can begin using the token endpoint as soon as you create an account on Apigee Edge . For details, see Understanding OAuth endpoints .

Purging access tokens

By default, OAuth2 tokens are purged from the Apigee Edge system 3 days (259200 seconds) after both the access token and refresh token (if it exists) have expired. In some cases, you may want to change this default. For example, you may want to shorten the purge time to save disk space if a large number of tokens are being generated.

If you are on Edge for Private Cloud , you can change this default by setting organization properties as explained in this section. (The 3-day purge of expired tokens applies to Edge for Private Cloud version 4.19.01 and later. For earlier versions, the default purge interval is 180 days.)

Updating purge settings for Edge Private Cloud 4.16.01 and later versions

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Updating purge settings for Edge Private Cloud 4.15.07

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Non-RFC-compliant behavior

The OAuthV2 policy returns a token response that contains certain non- RFC-compliant properties. The following table shows the non-compliant properties returned by the OAuthV2 policy and the corresponding compliant properties.

Also, the error response for an expired refresh token when grant_type = refresh_token is:

{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}

However, the RFC-compliant response is:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

مباحث مرتبط

• Introduction to OAuth 2.0