خط مشی 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>

در چندین مورد، برنامه مشتری باید شناسه مشتری را به سرور مجوز ارسال کند. این عنصر به شما امکان می دهد مشخص کنید که Edge کجا باید برای شناسه مشتری جستجو کند. تنها مکان معتبری که می‌توانید تنظیم کنید، مکان پیش‌فرض، متغیر جریان 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 ، سیاست زیر تأیید Token Access را تقویت می کند:

<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 انجام می شود ، تعداد زیادی از متغیرهای جریان در زمینه اجرای پروکسی جمع می شوند. این متغیرها ویژگی های مربوط به نشانه دسترسی ، برنامه توسعه دهنده ، توسعه دهنده و شرکت را به شما می دهد. به عنوان مثال می توانید از خط مشی AssignMessage یا JavaScript استفاده کنید تا هر یک از این متغیرها را بخوانید و از آنها در صورت نیاز در جریان استفاده کنید. این متغیرها همچنین می توانند برای اهداف اشکال زدایی مفید باشند.

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

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

این متغیرها مربوط به برنامه توسعه دهنده است که با نشانه همراه است.

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

اگر App.Apptype "شرکت" باشد ، آنگاه ویژگی های شرکت جمع می شوند و اگر App.apptype "توسعه دهنده" است ، ویژگی های توسعه دهنده جمع می شوند.

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

اگر App.Apptype "شرکت" باشد ، آنگاه ویژگی های شرکت جمع می شوند و اگر App.apptype "توسعه دهنده" است ، ویژگی های توسعه دهنده جمع می شوند.

عملیات GenerateauthorizationCode

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

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

مثال: oauthv2authcode.GenerateCodePolicy.code

عملیات GenerateAccessToken و RefreshaccessToken

این متغیرها هنگامی تنظیم می شوند که عملیات GenerateACCESSTOKEN و RefreshAccessToken با موفقیت انجام می شود. توجه داشته باشید که متغیرهای Token Token برای اعتبار اعتبار مشتری از نوع کمک هزینه استفاده نمی کنند.

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

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

ژنرال

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

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

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

ارجاع خطا

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime.

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

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

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

<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 با یک نقطه پایانی توکن OAUTH ارائه می شود. نقطه پایانی با سیاست های موجود در پروکسی API به نام OAuth پیش تنظیم می شود. به محض ایجاد یک حساب در Edge Apigee می توانید استفاده از نقطه انتهایی Token را شروع کنید. برای جزئیات بیشتر ، به درک نقاط پایانی OAUTH مراجعه کنید.

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

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

اگر برای ابر خصوصی در حاشیه هستید ، می توانید با تنظیم ویژگی های سازمانی همانطور که در این بخش توضیح داده شده است ، این پیش فرض را تغییر دهید. .

به روزرسانی تنظیمات پاک برای 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