خط‌مشی 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 Bearer Tokens پشتیبانی می‌شود. از نشانه‌های کد اصالت‌سنجی پیام (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 باشد.

می‌توانید این سرایند را با خط‌مشی JavaScript که درست قبل‌از خط‌مشی 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">

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

صفت توضیحات پیش فرض حضور
name

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

درست است اختیاری
async

این ویژگی منسوخ شده است.

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

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

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

پیش‌فرض:

موجود نیست

حضور:

اختیاری

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

عنصر <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

درحال‌حاضر، فقط پیشوند «حامل» پشتیبانی می‌شود.

پیش‌فرض:

حامل

حضور:

اختیاری

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

حامل

استفاده‌شده با عملیات:
  • VerifyAccessToken

عنصر <AppEndUser>

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

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

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

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

پیش‌فرض:

موجود نیست

حضور:

اختیاری

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

هر متغیر جریانی که در زمان اجرا برای خط‌مشی دردسترس باشد.

استفاده با انواع کمک مالی:
  • authorization_code
  • ضمنی
  • گذرواژه
  • client_credentials

<Attributes/Attribute>

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

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

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

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

برای پنهان کردن مشخصه‌های سفارشی در این موارد، این انتخاب‌ها را دارید:

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

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

پیش‌فرض:

N/A

حضور:

اختیاری

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

عنصر <ClientId>

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

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

پیش‌فرض:

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

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: متغیر جریان: request.formparam.client_id
استفاده با انواع کمک مالی:
  • authorization_code
  • گذرواژه
  • ضمنی
  • 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-urlencoded و در متن درخواست مشخص شده است)

حضور:

اختیاری

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

عنصر <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

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

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

با Apigee Edge برای «ابر عمومی»، پس‌از دسترسی به نهادها، Edge نهادهای زیر را حداقل ۱۸۰ ثانیه در حافظه نهان نگه می‌دارد.

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

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

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

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

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

ابر خصوصی: برای نصب Edge for 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

پیش‌فرض:

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

حضور:

اختیاری

نوع: عدد صحیح
مقادیر معتبر:
  • هر عدد صحیح مثبت غیرصفر. زمان انقضا را به میلی‌ثانیه مشخص کنید. اگرچه مقدار این عنصر برحسب میلی‌ثانیه است، مقدار تنظیم‌شده در دارایی expires_in نشان و در متغیر جریان expires_in برحسب ثانیه بیان می‌شود.
  • ‫-۱ طبق حداکثر انقضای کد دسترسی OAuth منقضی خواهد شد.

    توجه: مشخص کردن هر عدد صحیح منفی یا صفر دیگری باعث خطای استقرار می‌شود.

    همچنین الگوی ضد: تنظیم زمان انقضای طولانی برای کدهای OAuth را ببینید.

استفاده با انواع کمک مالی:
  • authorization_code
  • ضمنی
  • گذرواژه
  • 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 طرف سوم مراجعه کنید.

پیش‌فرض:

نادرست

حضور:

اختیاری

نوع: بولی
مقادیر معتبر: درست یا نادرست
استفاده با انواع کمک مالی:
  • authorization_code
  • گذرواژه
  • 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 نشان می‌دهد که رمز بازآوری خارجی باید به‌عنوان پارامتر پُرسمان وجود داشته باشد، مثلاً ?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 روی درست تنظیم شده باشد، خط‌مشی پاسخی تولید و برمی‌گرداند. اگر 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 و در بدنه درخواست مشخص شده است)

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: متغیری که در بالا توضیح داده شد.
استفاده با انواع کمک مالی:
  • authorization_code
  • گذرواژه
  • ضمنی
  • client_credentials
  • refresh_token

عنصر <Operation>

<Operation>GenerateAuthorizationCode</Operation>

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

پیش‌فرض:

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

حضور:

اختیاری

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

عنصر <PassWord>

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

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

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

خط‌مشی OAuthV2 کار دیگری با این مقادیر اطلاعات اعتباری انجام نمی‌دهد؛ Edge صرفاً حضور آن‌ها را درستی‌سنجی می‌کند. توسعه‌دهنده API باید درخواست مقادیر را بازیابی کند و قبل‌از اجرای خط‌مشی تولید کد، آن‌ها را به ارائه‌دهنده هویت ارسال کند.

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

پیش‌فرض:

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

حضور:

اختیاری

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

عنصر <RedirectUri>

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

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

درباره شناسه‌های URI هدایت

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

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

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

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

پیش‌فرض:

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

حضور:

اختیاری

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

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

عنصر <RefreshToken>

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

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

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

ابر خصوصی: برای نصب Edge for 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

پیش‌فرض:

‫۶۳۰۷۲۰۰۰۰۰۰۰ میلی‌ثانیه (۲ سال) (از ۵ اوت ۲۰۲۴ اعمال می‌شود)

حضور:

اختیاری

نوع: عدد صحیح
مقادیر معتبر:
استفاده با انواع کمک مالی:
  • authorization_code
  • گذرواژه
  • refresh_token

عنصر <ResponseType>

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

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

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

پیش‌فرض:

بدون حوزه

حضور:

اختیاری

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

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

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

استفاده با انواع کمک مالی:
  • authorization_code
  • ضمنی
  • گذرواژه
  • 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 می‌گوید رمز دسترسی خارجی را ذخیره کند. درغیراین‌صورت، این تنظیمات حفظ نخواهد شد.

پیش‌فرض:

نادرست

حضور:

اختیاری

نوع: بولی
مقادیر معتبر: درست یا نادرست
استفاده با انواع کمک مالی:
  • authorization_code
  • گذرواژه
  • 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
  • authorization_code
  • گذرواژه
  • ضمنی

عنصر <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> برای ارجاع به هر متغیر جریانی که حاوی اطلاعات اعتباری است استفاده کنید.

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

خط‌مشی OAuthV2 کار دیگری با این مقادیر اطلاعات اعتباری انجام نمی‌دهد؛ Edge صرفاً حضور آن‌ها را درستی‌سنجی می‌کند. توسعه‌دهنده API باید درخواست مقادیر را بازیابی کند و قبل‌از اجرای خط‌مشی تولید کد، آن‌ها را به ارائه‌دهنده هویت ارسال کند.

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

پیش‌فرض:

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

حضور:

اختیاری

نوع: رشته
مقادیر معتبر: هر تنظیم متغیری.
استفاده با انواع کمک مالی: گذرواژه

درحال درستی‌سنجی کدهای دسترسی

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

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

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

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

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

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

نام شرح
حوزه

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

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken متغیری که انتظار می‌رود کد دسترسی در آن قرار داشته باشد. برای مثال request.queryparam.accesstoken. به‌طور پیش‌فرض، انتظار می‌رود برنامه کد دسترسی را براساس مشخصات OAuth 2.0 در سرصفحه HTTP «مجوز» ارائه دهد. اگر انتظار می‌رود که توکن دسترسی در مکانی غیرمعمول ارائه شود، مثلاً پارامتر پُرسمان یا سرایند HTTP با نامی غیر از «مجوز»، از این تنظیم استفاده کنید.

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

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

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

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

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

متغیر شرح
organization_name نام سازمانی که کارگزار در آن اجرا می‌شود.
developer.id شناسه توسعه‌دهنده مرتبط با برنامه کارخواه ثبت‌شده.
developer.app.name نام توسعه‌دهنده مرتبط با برنامه مشتری ثبت‌شده.
client_id شناسه کارخواه برنامه کارخواه ثبت‌شده.
grant_type نوع صدور مرتبط با درخواست.
token_type نوع نشان مرتبط با درخواست.
access_token نمودار دسترسی که درستی‌سنجی می‌شود.
accesstoken.{custom_attribute} مشخصه سفارشی نام‌گذاری‌شده در کد دسترسی.
issued_at تاریخ صدور کد دسترسی که به زمان یونیکس در میلی‌ثانیه بیان شده است.
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

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

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

مثال: oauthv2authcode.GenerateCodePolicy.code

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

عملیات GenerateAccessToken و RefreshAccessToken

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

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

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

نام متغیر شرح
access_token کد دسترسی تولیدشده.
client_id شناسه مشتری برنامه توسعه‌دهنده مرتبط با این کد.
expires_in مقدار انقضای رمز. برای جزئیات، عنصر <ExpiresIn> را ببینید. توجه داشته باشید که در پاسخ، expires_in به ثانیه بیان می‌شود.
scope فهرست محدوده‌های دردسترس پیکربندی‌شده برای این کد. کار با محدوده‌های 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 این مقدار زمان نمایش رشته‌ای مُهر زمان ۳۲ بیتی مربوط به مقدار است. برای مثال، «Wed, 21 Aug 2013 19:16:47 UTC» با مقدار مُهر زمان ‏۱۳۷۷۱۱۲۶۰۷۴۱۳ مطابقت دارد.
refresh_token_status یا approved یا revoked.

GenerateAccessTokenImplicitGrant

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

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

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

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

مرجع خطا

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

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

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

کد خطا وضعیت HTTP علت پرتاب‌شده توسط عملیات
steps.oauth.v2.access_token_expired 401 کد دسترسی منقضی شده است.

VerifyAccessToken
InvalidateToken

steps.oauth.v2.access_token_not_approved 401 کد دسترسی باطل شد. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 منبع درخواست‌شده در هیچ‌یک از محصولات «میانای برنامه‌سازی کاربردی» مرتبط با کد دسترسی وجود ندارد. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken ۵۰۰ خط‌مشی انتظار داشت کد دسترسی را در متغیری که در عنصر <AccessToken> مشخص شده است پیدا کند، اما متغیر قابل‌حل نبود. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode ۵۰۰ خط‌مشی انتظار داشت کد تأییدیه‌ای را در متغیری که در عنصر <Code> مشخص شده است پیدا کند، اما متغیر قابل‌حل نبود. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId ۵۰۰ خط‌مشی انتظار داشت «شناسه مشتری» را در متغیری که در عنصر <ClientId> مشخص شده است پیدا کند، اما متغیر قابل‌حل نبود. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken ۵۰۰ خط‌مشی انتظار داشت نشان بازآوری را در متغیری که در عنصر <RefreshToken> مشخص شده است پیدا کند، اما متغیر قابل‌حل نبود. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken ۵۰۰ خط‌مشی انتظار داشت نشانه‌ای را در متغیری که در عنصر <Tokens> مشخص شده است پیدا کند، اما متغیر قابل‌حل نبود.

اعتبارسنجی کد
کد را نامعتبر کنید

steps.oauth.v2.InsufficientScope 403 دامنه کد دسترسی ارائه‌شده در درخواست با دامنه مشخص‌شده در خط‌مشی درستی‌سنجی کد دسترسی مطابقت ندارد. برای آشنایی با محدوده، کار با محدوده‌های OAuth2 را ببینید. VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 کد دسترسی ارسال‌شده از کارخواه نامعتبر است. VerifyAccessToken
steps.oauth.v2.invalid_client 401

این نام خطا زمانی برگردانده می‌شود که دارایی <GenerateResponse> خط‌مشی روی درست تنظیم شده باشد و شناسه مشتری ارسال‌شده در درخواست نامعتبر باشد. بررسی کنید که از مقادیر کلید و رمز مشتری صحیح برای «برنامه توسعه‌دهنده» مرتبط با پراکسی خود استفاده می‌کنید. معمولاً این مقادیر به‌عنوان سرصفحه «مجوز پایه» کدبندی‌شده با Base64 ارسال می‌شوند.

توجه: توصیه می‌شود شرایط قانون خطای موجود را تغییر دهید تا نام‌های invalid_client و InvalidClientIdentifier را هر دو دریافت کند. برای اطلاعات بیشتر و دیدن نمونه، یادداشت‌های انتشار ۱۶ سپتامبر ۲۰۲۱ را ببینید.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidRequest ۴۰۰ این نام خطا برای انواع مختلفی از خطاها استفاده می‌شود، معمولاً برای پارامترهای ازدست‌رفته یا نادرست که در درخواست ارسال شده‌اند. اگر <GenerateResponse> روی false تنظیم شده است، از متغیرهای خطا (توضیح داده‌شده در زیر) برای بازیابی جزئیات خطا، مانند نام و علت خطا، استفاده کنید. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 سرایند مجوز کلمه «حامل» را ندارد که الزامی است. برای مثال: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401

پراکسی API در «محصول» مرتبط با کد دسترسی نیست.

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

برای راهنمایی بیشتر درباره دلایل این خطا، این پست انجمن Apigee را نیز ببینید.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier ۵۰۰

این نام خطا زمانی برگردانده می‌شود که دارایی <GenerateResponse> خط‌مشی روی false تنظیم شده باشد و شناسه کارخواه ارسال‌شده در درخواست نامعتبر باشد. بررسی کنید که از کلید مشتری و مقادیر رمز صحیح برای «برنامه توسعه‌دهنده» مرتبط با پراکسی خود استفاده می‌کنید. معمولاً این مقادیر به‌عنوان سرصفحه «مجوز پایه» کدبندی‌شده با «۶۴پایه» ارسال می‌شوند.

توجه: در این وضعیت، این خطا قبلاً invalid_client نامیده می‌شد. توصیه می‌شود شرایط قانون خطای موجود را تغییر دهید تا نام‌های invalid_client و InvalidClientIdentifier را هر دو دریافت کند. برای اطلاعات بیشتر و دیدن نمونه، یادداشت‌های انتشار ۱۶ سپتامبر ۲۰۲۱ را ببینید.

GenerateAccessToken
RefreshAccessToken

steps.oauth.v2.InvalidParameter ۵۰۰ خط‌مشی باید یا کد دسترسی یا کد مجوز را مشخص کند، اما نه هر دو را. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType ۵۰۰ عنصر <Tokens>/<Token> از شما می‌خواهد نوع نشان را مشخص کنید (برای مثال، refreshtoken). اگر کارخواه نوع اشتباه را ارسال کند، این خطا ایجاد می‌شود. ‫ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter ۵۰۰ نوع پاسخ token است، اما نوع اعطایی مشخص نشده است. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType ۵۰۰

کارخواه نوع پروانه‌ای را مشخص کرده است که خط‌مشی پشتیبانی نمی‌کند (در عنصر <SupportedGrantTypes> فهرست نشده است).

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

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

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

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

نام خطا علت
InvalidValueForExpiresIn

برای عنصر <ExpiresIn>، مقادیر معتبر اعداد صحیح مثبت و -1 است.

InvalidValueForRefreshTokenExpiresIn برای عنصر <RefreshTokenExpiresIn>، مقادیر معتبر عبارت‌اند از اعداد صحیح مثبت و -1.
InvalidGrantType نوع پروانه نامعتبری در عنصر <SupportedGrantTypes> مشخص شده است. برای فهرست انواع معتبر، به مرجع خط‌مشی مراجعه کنید.
ExpiresInNotApplicableForOperation مطمئن شوید که عملیات مشخص‌شده در عنصر <Operations> از انقضا پشتیبانی می‌کند. برای مثال، عملیات VerifyToken این کار را انجام نمی‌دهد.
RefreshTokenExpiresInNotApplicableForOperation مطمئن شوید که عملیات مشخص‌شده در عنصر <Operations> از انقضای توکن بازآوری پشتیبانی می‌کند. برای مثال، عملیات VerifyToken این کار را انجام نمی‌دهد.
GrantTypesNotApplicableForOperation مطمئن شوید که انواع پروانه‌های مشخص‌شده در <SupportedGrantTypes> برای عملکرد مشخص‌شده پشتیبانی می‌شوند.
OperationRequired

باید عملیاتی را در این خط‌مشی بااستفاده از عنصر <Operation> مشخص کنید.

توجه: اگر عنصر <Operation> وجود نداشته باشد، «میانای کاربری» خطای اعتبارسنجی طرحواره می‌دهد.

InvalidOperation

باید بااستفاده از عنصر <Operation>، عملیات معتبری را در این خط‌مشی مشخص کنید.

توجه: اگر عنصر <Operation> نامعتبر باشد، «میانای کاربری» خطای اعتبارسنجی طرحواره می‌دهد.

TokenValueRequired باید مقدار <Token> نشانه را در عنصر <Tokens> مشخص کنید.

متغیرهای خطا

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

متغیر مکان مثال
fault.name="fault_name" ‫fault_name نام خطا است، همان‌طور که در جدول خطاهای زمان اجرا در بالا فهرست شده است. نام خطا آخرین بخش کد خطا است. fault.name = "InvalidRequest"
oauthV2.policy_name.failed policy_name نام مشخص‌شده کاربر برای خط‌مشی‌ای است که خطا را ایجاد کرده است. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name ‫policy_name نام مشخص‌شده کاربر برای خط‌مشی‌ای است که خطا را ایجاد کرده است. oauthV2.GenerateAccesstoken.fault.name = InvalidRequest

توجه: برای عملیات VerifyAccessToken، نام خطا شامل این پسوند است: keymanagement.service
برای مثال: keymanagement.service.invalid_access_token

oauthV2.policy_name.fault.cause policy_name نام مشخص‌شده کاربر برای خط‌مشی‌ای است که خطا را ایجاد کرده است. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

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

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

اگر از Edge for Private Cloud استفاده می‌کنید، می‌توانید این پیش‌فرض را با تنظیم دارایی‌های سازمان همان‌گونه که در این بخش توضیح داده شده است تغییر دهید. (پاک‌سازی ۳ روزه نشانه‌های منقضی‌شده برای Edge ویژه «ابر خصوصی» نسخه ۴.۱۹.۰۱ و نسخه‌های جدیدتر اعمال می‌شود. برای نسخه‌های قدیمی‌تر، فاصله پاک‌سازی پیش‌فرض ۱۸۰ روز است.)

درحال به‌روزرسانی تنظیمات پاک‌سازی برای Edge Private Cloud نسخه ۴.۱۶.۰۱ و نسخه‌های جدیدتر

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

درحال به‌روزرسانی تنظیمات پاک‌سازی برای 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" : "InvalidRequest", "Error" :"Refresh Token expired"}

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

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

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