خط مشی 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 انتظار دارد که نشانه دسترسی در یک سرصفحه مجوز به‌عنوان یک توکن حامل ارسال شود. به عنوان مثال:

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

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

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

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

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

عنصر <ClientId>

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

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

عنصر <Code>

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

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

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

عنصر <ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

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

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

با Apigee Edge for Public Cloud ، Edge موجودیت های زیر را حداقل 180 ثانیه پس از دسترسی به موجودیت ها در حافظه پنهان نگه می دارد.

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

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

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

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

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

Private Cloud: برای نصب Edge برای Private Cloud، مقدار پیش‌فرض توسط ویژگی 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. مطمئن شوید که فایل خواص متعلق به کاربر "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 نشان می دهد که نشانه refresh خارجی باید به عنوان یک پارامتر پرس و جو وجود داشته باشد، به عنوان مثال، ?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>

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

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

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

عنصر <Operation>

<Operation>GenerateAuthorizationCode</Operation>

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

عنصر <PassWord>

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

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

به عنوان مثال، می توانید رمز عبور را در یک درخواست رمز با استفاده از پارامتر query ارسال کنید و عنصر را به این صورت تنظیم کنید: <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 بازگشت به تماس داشته باشید.

می توانید این پارامتر را در یک پارامتر query یا در یک هدر ارسال کنید. متغیر 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 باید به عنوان یک پارامتر پرس و جو وجود داشته باشد، به عنوان مثال، ?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>

Private Cloud: برای نصب Edge برای Private Cloud، مقدار پیش‌فرض توسط ویژگی 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. مطمئن شوید که فایل خواص متعلق به کاربر "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 به دنبال مقدار نوع پاسخ در یک پارامتر query response_type می گردد. اگر می‌خواهید این رفتار پیش‌فرض را لغو کنید، از عنصر <ResponseType> برای پیکربندی متغیر جریان حاوی مقدار نوع پاسخ استفاده کنید. برای مثال، اگر این عنصر را روی request.header.response_type تنظیم کنید، Edge به دنبال نوع پاسخی است که باید در هدر درخواست ارسال شود. همچنین به درخواست رمزهای دسترسی و کدهای مجوز مراجعه کنید.

عنصر <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>

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

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

به عنوان مثال، می توانید نام کاربری را در یک پارامتر query ارسال کنید و عنصر <UserName> را به این صورت تنظیم کنید: <UserName>request.queryparam.username</UserName> . برای نیاز به نام کاربری در هدر HTTP، این مقدار را روی request.header.username تنظیم کنید.

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

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

تایید نشانه های دسترسی

هنگامی که یک نقطه پایانی توکن برای یک پراکسی API تنظیم می شود، یک خط مشی مربوطه OAuthV2 که عملیات VerifyAccessToken را مشخص می کند به جریانی که منبع محافظت شده را در معرض دید قرار می دهد، متصل می شود.

به عنوان مثال، برای اطمینان از اینکه همه درخواست‌ها به یک API مجاز هستند، خط‌مشی زیر تأیید توکن دسترسی را اعمال می‌کند:

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

این خط مشی به منبع API پیوست شده است تا محافظت شود. برای اطمینان از اینکه همه درخواست‌های یک API تأیید می‌شوند، خط‌مشی را به درخواست ProxyEndpoint PreFlow، به شرح زیر پیوست کنید:

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

عناصر اختیاری زیر را می توان برای لغو تنظیمات پیش فرض برای عملیات VerifyAccessToken استفاده کرد.

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

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

تعیین مکان متغیر درخواست

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

مثال زیر نشان می دهد که چگونه می توانید مکان پارامترهای کد مجوز مورد نیاز را به عنوان هدر HTTP مشخص کنید:

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

یا در صورت لزوم برای پشتیبانی از پایگاه برنامه مشتری خود، می توانید سرصفحه ها و پارامترهای پرس و جو را با هم ترکیب و مطابقت دهید:

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

فقط یک مکان را می توان در هر پارامتر پیکربندی کرد.

متغیرهای جریان

متغیرهای جریان تعریف‌شده در این جدول زمانی که سیاست‌های OAuth مربوطه اجرا می‌شوند پر می‌شوند و از این رو برای سایر سیاست‌ها یا برنامه‌هایی که در جریان پروکسی API اجرا می‌شوند در دسترس هستند.

عملیات VerifyAccessToken

عملیات VerifyAccessToken اجرا می شود، تعداد زیادی از متغیرهای جریان در زمینه اجرای پروکسی پر می شوند. این متغیرها ویژگی های مربوط به نشانه دسترسی، برنامه توسعه دهنده، توسعه دهنده و شرکت را به شما می دهند. به عنوان مثال، می‌توانید از یک خط‌مشی AssignMessage یا JavaScript برای خواندن هر یک از این متغیرها استفاده کنید و در صورت لزوم در ادامه جریان از آنها استفاده کنید. این متغیرها همچنین می توانند برای اهداف اشکال زدایی مفید باشند.

متغیرهای خاص توکن

متغیرهای خاص برنامه

این متغیرها مربوط به Developer App است که با توکن مرتبط است.

متغیرهای خاص توسعه دهنده

اگر app.appType "Company" باشد، مشخصه های شرکت پر می شوند و اگر app.appType "Developer" باشد، ویژگی های توسعه دهنده پر می شوند.

متغیرهای خاص شرکت

اگر app.appType "Company" باشد، مشخصه های شرکت پر می شوند و اگر app.appType "Developer" باشد، ویژگی های توسعه دهنده پر می شوند.

عملیات GenerateAuthorizationCode

این متغیرها زمانی تنظیم می شوند که عملیات GenerateAuthorizationCode با موفقیت اجرا شود:

پیشوند: oauthv2authcode.{policy_name}.{variable_name}

مثال: oauthv2authcode.GenerateCodePolicy.code

عملیات GenerateAccessToken و RefreshAccessToken

این متغیرها زمانی تنظیم می شوند که عملیات GenerateAccessToken و RefreshAccessToken با موفقیت اجرا شوند. توجه داشته باشید که متغیرهای نشانه رفرش برای جریان نوع اعطای اعتبار مشتری اعمال نمی شود.

پیشوند: oauthv2accesstoken.{policy_name}.{variable_name}

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

این متغیرها زمانی تنظیم می شوند که عملیات GenerateAccessTokenImplicit برای جریان نوع اعطای ضمنی با موفقیت اجرا شود.

پیشوند: oauthv2accesstoken.{policy_name}.{variable_name}

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط 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>

طرح سیاست

هر نوع خط مشی توسط یک طرح XML ( .xsd ) تعریف می شود. برای مرجع، طرح‌های خط‌مشی در GitHub در دسترس هستند.

کار با پیکربندی پیش فرض OAuth

هر سازمان (حتی یک سازمان آزمایشی رایگان) در Apigee Edge دارای یک نقطه پایانی نشانه OAuth است. نقطه پایانی با خط‌مشی‌هایی در پروکسی API به نام oauth از قبل پیکربندی شده است. به محض ایجاد یک حساب کاربری در Apigee Edge می‌توانید از نقطه پایانی نشانه استفاده کنید. برای جزئیات، به درک نقاط پایانی OAuth مراجعه کنید.

پاک کردن نشانه های دسترسی

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

اگر در Edge برای Private Cloud هستید، می‌توانید این پیش‌فرض را با تنظیم ویژگی‌های سازمان همانطور که در این بخش توضیح داده شد تغییر دهید. (پاکسازی 3 روزه توکن های منقضی شده برای Edge برای Private Cloud نسخه 4.19.01 و جدیدتر اعمال می شود. برای نسخه های قبلی، فاصله پاکسازی پیش فرض 180 روز است.)

به‌روزرسانی تنظیمات پاکسازی برای Edge Private Cloud 4.16.01 و نسخه‌های جدیدتر

توجه: فقط نشانه هایی که پس از اعمال این تنظیمات تولید می شوند تحت تأثیر قرار می گیرند. تنظیمات برای توکن هایی که قبلا تولید شده اند اعمال نمی شود.

به روز رسانی تنظیمات پاکسازی برای Edge Private Cloud 4.15.07

توجه: فقط نشانه هایی که پس از اعمال این تنظیمات تولید می شوند تحت تأثیر قرار می گیرند. تنظیمات برای توکن هایی که قبلا تولید شده اند اعمال نمی شود.

رفتار غیر منطبق با RFC

خط مشی OAuthV2 یک پاسخ توکن را برمی گرداند که حاوی ویژگی های غیر منطبق با RFC است. جدول زیر ویژگی های غیرمنطبق برگردانده شده توسط خط مشی OAuthV2 و ویژگی های سازگار مربوطه را نشان می دهد.

همچنین، پاسخ خطا برای یک نشانه رفرش منقضی شده، زمانی که grant_type = refresh_token است:

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

با این حال، پاسخ مطابق با RFC این است:

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

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

• مقدمه ای بر OAuth 2.0