خط مشی OAuthV2

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

چی

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

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

نمونه ها

VerifyAccessToken

VerifyAccessToken

این پیکربندی خط مشی OAuthV2 (با عملیات VerifyAccessToken) تأیید می کند که یک نشانه دسترسی ارسال شده به Apigee Edge معتبر است. هنگامی که این عملیات خط مشی راه اندازی می شود، Edge به دنبال یک نشانه دسترسی معتبر در درخواست می گردد. اگر رمز دسترسی معتبر باشد، درخواست اجازه ادامه دارد. اگر نامعتبر باشد، تمام پردازش متوقف می شود و یک خطا در پاسخ باز می گردد.

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

توجه: فقط توکن‌های حامل OAuth 2.0 پشتیبانی می‌شوند. کدهای احراز هویت پیام (MAC) پشتیبانی نمی شوند.

به عنوان مثال:

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

به طور پیش‌فرض، Edge توکن‌های دسترسی را در هدر Authorization با پیشوند Bearer می‌پذیرد. می توانید این پیش فرض را با عنصر <AccessToken> تغییر دهید.

GenerateAccessToken

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

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

GenerateAuthorizationCode

کد مجوز را ایجاد کنید

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

RefreshAccessToken

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

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

نشانه جریان پاسخ

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

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

ابتدا، بیایید به سیاست نمونه نگاه کنیم:

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

اگر این خط‌مشی را روی جریان پاسخ قرار دهید، با خطای 401 UnAuthorized با وجود اینکه پارامترهای ورود صحیح در خط‌مشی مشخص شده‌اند، با خطا مواجه می‌شود. برای حل این مشکل، باید یک هدر درخواست مجوز تنظیم کنید.

سرصفحه مجوز باید شامل یک طرح دسترسی پایه با Client_id:client_secret کدگذاری شده با Base64 باشد.

می‌توانید این هدر را با یک خط‌مشی جاوا اسکریپت که درست قبل از خط‌مشی OAuthV2 قرار داده شده است، اضافه کنید. متغیرهای "local_clientid" و "local_secret" باید قبلاً تنظیم شده و در جریان موجود باشند:

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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

عنصر <AccessToken>

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

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

مثالی که در آن <AccessToken>request.header.access_token</AccessToken> مشخص شده است:

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
مثالی که در آن <AccessToken>request.queryparam.access_token</AccessToken> مشخص شده است:

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

پیش فرض:

N/A

حضور:

اختیاری

نوع: رشته
مورد استفاده با عملیات:
  • VerifyAccessToken

عنصر <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

پیش فرض:

حامل

حضور:

اختیاری

نوع: رشته
مقادیر معتبر:

حامل

مورد استفاده با عملیات:
  • VerifyAccessToken

عنصر <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 با شناسه کاربر نهایی، شناسه برنامه یا هر دو مراجعه کنید.

پیش فرض:

N/A

حضور:

اختیاری

نوع: رشته
مقادیر معتبر:

هر متغیر جریان قابل دسترسی به سیاست در زمان اجرا.

مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • ضمنی
  • رمز عبور
  • client_credentials

<ویژگی ها/ویژگی>

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

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

پیش فرض:

N/A

حضور:

اختیاری

مقادیر معتبر:
  • name -نام ویژگی
  • ref - مقدار صفت. می تواند از یک متغیر جریان حاصل شود.
  • display - (اختیاری) به شما امکان می دهد مشخص کنید که آیا ویژگی های سفارشی در پاسخ ظاهر شوند یا خیر. اگر true ، ویژگی‌های سفارشی در پاسخ ظاهر می‌شوند (اگر GenerateResponse نیز فعال باشد). اگر false ، ویژگی های سفارشی در پاسخ گنجانده نمی شود. مقدار پیش فرض true است. به نمایش یا پنهان کردن ویژگی های سفارشی در پاسخ مراجعه کنید.
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • ضمنی
  • رمز عبور
  • client_credentials
  • refresh_token
  • همچنین می تواند با عملیات GenerateAuthorizationCode استفاده شود.

عنصر <ClientId>

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

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

پیش فرض:

request.formparam.client_id (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: متغیر جریان: request.formparam.client_id
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • رمز عبور
  • ضمنی
  • client_credentials

همچنین می تواند با عملیات GenerateAuthorizationCode استفاده شود.

عنصر <Code>

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

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

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

پیش فرض:

request.formparam.code (یک x-www-form-urlencode و مشخص شده در بدنه درخواست)

حضور:

اختیاری

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

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

پیش فرض:

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

حضور:

اختیاری

نوع: عدد صحیح
مقادیر معتبر:
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • ضمنی
  • رمز عبور
  • client_credentials
  • refresh_token

همچنین با عملیات GenerateAuthorizationCode استفاده می شود.

عنصر <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 شخص ثالث مراجعه کنید.

پیش فرض:

نادرست

حضور:

اختیاری

نوع: بولی
مقادیر معتبر: درست یا نادرست
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • رمز عبور
  • client_credentials

عنصر <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 بر حسب ثانیه در پاسخ بیان می شود.

پیش فرض:

نادرست

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: درست یا نادرست
مورد استفاده با انواع کمک هزینه:
  • ضمنی
  • رمز عبور
  • client_credentials
  • refresh_token
  • همچنین می تواند با عملیات GenerateAuthorizationCode استفاده شود.

عنصر <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

پیش فرض:

نادرست

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: درست یا نادرست
مورد استفاده با انواع کمک هزینه:
  • ضمنی
  • رمز عبور
  • client_credentials
  • refresh_token
  • همچنین می تواند با عملیات GenerateAuthorizationCode استفاده شود.

<GrantType>

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

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

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

پیش فرض:

request.formparam.grant_type (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: یک متغیر، همانطور که در بالا توضیح داده شد.
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • رمز عبور
  • ضمنی
  • client_credentials
  • refresh_token

عنصر <Operation>

<Operation>GenerateAuthorizationCode</Operation>

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

پیش فرض:

اگر <Operation> مشخص نشده باشد، Edge به لیست <SupportedGrantTypes> نگاه می کند. فقط عملیات بر روی آن انواع کمک هزینه موفقیت آمیز خواهد بود. به عبارت دیگر، اگر یک <GrantType> را در لیست <SupportedGrantTypes> مشخص کنید، می توانید <Operation> حذف کنید. اگر نه <Operation> و نه <SupportedGrantTypes> مشخص نشده باشد، نوع اعطای پیش فرض autorization_code است. به این معنی که درخواست های نوع اعطای autorization_code موفق خواهند شد، اما سایر درخواست ها با شکست مواجه خواهند شد.

حضور:

اختیاری

نوع: رشته
مقادیر معتبر:

عنصر <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 بستگی دارد که درخواست مقادیر را بازیابی کند و قبل از اجرای خط‌مشی تولید توکن به یک ارائه‌دهنده هویت ارسال کند.

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

پیش فرض:

request.formparam.password (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: هر متغیر جریانی که در زمان اجرا در اختیار سیاست قرار می گیرد.
مورد استفاده با انواع کمک هزینه: رمز عبور

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

پیش فرض:

request.formparam.redirect_uri (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: هر متغیر جریان قابل دسترسی در سیاست در زمان اجرا
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • ضمنی

همچنین با عملیات GenerateAuthorizationCode استفاده می شود.

عنصر <RefreshToken>

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

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

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

پیش فرض:

request.formparam.refresh_token (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: هر متغیر جریان قابل دسترسی در سیاست در زمان اجرا
مورد استفاده با انواع کمک هزینه:
  • 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

پیش فرض:

63072000000 ms (2 سال) (از 05 اوت 2024)

حضور:

اختیاری

نوع: عدد صحیح
مقادیر معتبر:
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • رمز عبور
  • refresh_token

عنصر <ResponseType>

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

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

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

پیش فرض:

request.formparam.response_type (یک x-www-form-urlencoded و مشخص شده در بدنه درخواست)

حضور:

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

نوع: رشته
مقادیر معتبر: code (برای نوع اعطای کد مجوز) یا token (برای نوع اعطای ضمنی)
مورد استفاده با انواع کمک هزینه:
  • ضمنی
  • همچنین با عملیات GenerateAuthorizationCode استفاده می شود.

عنصر <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

پیش فرض:

false

حضور:

اختیاری

نوع: بولی
مقادیر معتبر:

true یا false

مورد استفاده با نوع کمک هزینه:
  • refresh_token

عنصر <Scope>

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

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

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

<Scope>A B</Scope>

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

پیش فرض:

بدون دامنه

حضور:

اختیاری

نوع: رشته
مقادیر معتبر:

اگر با خط‌مشی‌های Generate* استفاده می‌شود، یک متغیر جریان.

اگر با VerifyAccessToken استفاده شود، فهرستی از نام‌های محدوده (رشته‌ها) از هم جدا شده است.

مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • ضمنی
  • رمز عبور
  • client_credentials
  • همچنین می تواند با عملیات GenerateAuthorizationCode و VerifyAccessToken استفاده شود.

عنصر <State>

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

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

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

پیش فرض:

بدون ایالت

حضور:

اختیاری

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

عنصر <StoreToken>

 <StoreToken>true</StoreToken> 

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

پیش فرض:

نادرست

حضور:

اختیاری

نوع: بولی
مقادیر معتبر: درست یا نادرست
مورد استفاده با انواع کمک هزینه:
  • مجوز_کد
  • رمز عبور
  • client_credentials

عنصر <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 با یک مطابقت دارد. از انواع کمک های مالی حمایت شده).

پیش فرض:

مجوز _کد و ضمنی

حضور:

مورد نیاز

نوع: رشته
مقادیر معتبر:
  • client_credentials
  • مجوز_کد
  • رمز عبور
  • ضمنی

عنصر <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 است که درخواست مقادیر را بازیابی کرده و آنها را قبل از اجرای سیاست تولید توکن به یک ارائه دهنده هویت ارسال کند.

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

پیش فرض:

Request.FormParam.Username (A X-WWW-Form-Urlencoded و در بدنه درخواست مشخص شده است)

حضور:

اختیاری

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

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

هنگامی که یک نقطه پایانی توکن برای یک پروکسی 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>
با دسترسی متغیری که انتظار می رود نشانه دسترسی در آن قرار داشته باشد. به عنوان مثال request.queryparam.accesstoken . به طور پیش فرض ، انتظار می رود که نشانه دسترسی توسط برنامه در عنوان HTTP مجوز ، مطابق مشخصات OAUTH 2.0 ارائه شود. اگر انتظار می رود که نشانه دسترسی در یک مکان غیر استاندارد مانند پارامتر پرس و جو یا یک عنوان HTTP با نامی غیر از مجوز ارائه شود ، از این تنظیم استفاده کنید.

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

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

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

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

متغیرها توضیحات
organization_name نام سازمانی که پروکسی در آن اجرا می کند.
developer.id شناسه توسعه دهنده مرتبط با برنامه مشتری ثبت شده.
developer.app.name نام توسعه دهنده مرتبط با برنامه مشتری ثبت شده.
client_id شناسه مشتری برنامه مشتری ثبت شده.
grant_type نوع کمک هزینه مرتبط با درخواست.
token_type نوع توکن مرتبط با درخواست.
access_token نشانه دسترسی که تأیید می شود.
accesstoken.{custom_attribute} یک ویژگی سفارشی نامگذاری شده در نشانه دسترسی.
issued_at تاریخی که نشانه دسترسی در دوره یونیکس در Milliseconds بیان شد.
expires_in زمان انقضا برای نشانه دسترسی. در ثانیه بیان شده است. اگرچه عنصر ExpiresIn انقضا را در میلی ثانیه ، در متغیرهای پاسخ و جریان توکن ، تعیین می کند ، اما مقدار در چند ثانیه نمایش داده می شود.
status وضعیت نشانه دسترسی (به عنوان مثال ، تأیید یا ابطال شده).
scope دامنه (در صورت وجود) مرتبط با نشانه دسترسی.
apiproduct.<custom_attribute_name> یک ویژگی سفارشی نامگذاری شده از محصول API مرتبط با برنامه مشتری ثبت شده.
apiproduct.name نام محصول API مرتبط با برنامه مشتری ثبت شده.
revoke_reason

(فقط Apigee Hybrid) نشان می دهد که چرا نشانه دسترسی ابطال می شود.

مقدار می تواند REVOKED_BY_APP ، REVOKED_BY_ENDUSER ، REVOKED_BY_APP_ENDUSER یا TOKEN_REVOKED .

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

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

متغیرها توضیحات
app.name
app.id
app.accessType
app.callbackUrl
app.status تأیید یا ابطال شده
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType به عنوان مثال: توسعه دهنده
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} یک ویژگی سفارشی نامگذاری شده از برنامه مشتری ثبت شده.

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

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

متغیرها توضیحات
متغیرهای خاص توسعه دهنده
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status فعال یا غیرفعال
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} یک ویژگی سفارشی نامگذاری شده از توسعه دهنده.

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

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

متغیرها توضیحات
company.id
company.displayName
company.apps
company.appOwnerStatus
company.created_by
company.created_at
company.last_modified_at
company.last_modified_by
company.{custom_attributes} یک ویژگی سفارشی نامگذاری شده از شرکت.

عملیات GenerateauthorizationCode

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

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

مثال: oauthv2authcode.GenerateCodePolicy.code

متغیر توضیحات
code کد مجوز هنگام اجرای سیاست ایجاد می شود.
redirect_uri URI تغییر مسیر مرتبط با برنامه مشتری ثبت شده.
scope دامنه OAUTH اختیاری که در درخواست مشتری منتقل شده است.
client_id شناسه مشتری در درخواست مشتری منتقل شد.

عملیات GenerateAccessToken و RefreshaccessToken

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

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

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

نام متغیر توضیحات
access_token نشانه دسترسی که تولید شده است.
client_id شناسه مشتری برنامه توسعه دهنده مرتبط با این نشانه.
expires_in مقدار انقضا برای نشانه. برای جزئیات بیشتر به عنصر <tevireSin> مراجعه کنید. توجه داشته باشید که در پاسخ ، منقضی شده در ثانیه بیان می شود.
scope لیست دامنه های موجود برای توکن پیکربندی شده است. به کار با Scopes OAuth2 مراجعه کنید.
status یا approved یا revoked .
token_type تنظیم شده است به BearerToken .
developer.email آدرس ایمیل توسعه دهنده ثبت شده که صاحب برنامه توسعه دهنده مرتبط با توکن است.
organization_name ارگ که در آن پروکسی اجرا می شود.
api_product_list لیستی از محصولات مرتبط با برنامه توسعه دهنده مربوطه توکن.
refresh_count
refresh_token نشانه تازه ای که تولید شده است. توجه داشته باشید که نشانه های تازه سازی برای نوع اعطای اعتبار مشتری ایجاد نمی شوند.
refresh_token_expires_in طول عمر توکن تازه ، در ثانیه.
refresh_token_issued_at این مقدار زمان بازنمایی رشته از مقدار زمانی 32 بیتی مربوطه است. به عنوان مثال ، "چهارشنبه ، 21 اوت 2013 19:16:47 UTC" با ارزش زمان بندی 1377112607413 مطابقت دارد.
refresh_token_status یا approved یا revoked .

ژنرال

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

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

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

متغیر توضیحات
oauthv2accesstoken.access_token نشانه دسترسی هنگام اجرای این سیاست ایجاد می شود.
oauthv2accesstoken.{policy_name}.expires_in مقدار انقضا برای نشانه ، در ثانیه. برای جزئیات بیشتر به عنصر <tevireSin> مراجعه کنید.

ارجاع خطا

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.

Fault code HTTP status Cause Thrown by operations
steps.oauth.v2.access_token_expired 401 The access token is expired.

VerifyAccessToken
InvalidateToken

steps.oauth.v2.access_token_not_approved 401 The access token was revoked. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 The requested resource does not exist any of the API products associated with the access token. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.

ValidateToken
InvalidateToken

steps.oauth.v2.InsufficientScope 403 The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 The access token sent from the client is invalid. VerifyAccessToken
steps.oauth.v2.invalid_client 401

This error name is returned when the <GenerateResponse> property of the policy is set to true and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names. See the 16.09.21 Release Notes for more information and an example.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidRequest 400 This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 The authorization header does not have the word "Bearer", which is required. For example: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401

The API proxy is not in the Product associated with the access token.

Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Create API products for details.

See also this Apigee Community post for more guidance on causes for this error.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

Note: In this situation, this error used to be called invalid_client. It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names. See the 16.09.21 Release Notes for more information and an example.

GenerateAccessToken
RefreshAccessToken

steps.oauth.v2.InvalidParameter 500 The policy must specify either an access token or an authorization code, but not both. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 The response type is token, but no grant types are specified. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element).

Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected.

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

Deployment errors

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

Error name Cause
InvalidValueForExpiresIn

For the <ExpiresIn> element, valid values are positive integers and -1.

InvalidValueForRefreshTokenExpiresIn For the <RefreshTokenExpiresIn> element, valid values are positive integers and -1.
InvalidGrantType An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired

You must specify an operation in this policy using the <Operation> element.

Note: If the <Operation> element is missing, the UI throws a schema validation error.

InvalidOperation

You must specify a valid operation in this policy using the <Operation> element.

Note: If the <Operation> element is invalid, the UI throws a schema validation error.

TokenValueRequired You must specify a token <Token> value in the <Tokens> element.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "InvalidRequest"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.fault.name = InvalidRequest

Note: For the VerifyAccessToken operation, the fault name includes this suffix: keymanagement.service
For example: keymanagement.service.invalid_access_token

oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

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

OAUTHV2 بازگشت: خاصیت سازگار با RFC:
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

(مقدار سازگار یک عدد است ، نه یک رشته.)

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

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

با این حال ، پاسخ سازگار با RFC:

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

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