پیاده‌سازی نوع اعطای کد مجوز

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

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

درباره این موضوع

این موضوع شرح کلی و نمای کلی از جریان نوع اعطای مجوز OAuth 2.0 ارائه می‌دهد و درباره نحوه پیاده‌سازی این جریان در Apigee Edge بحث می‌کند.

ویدیو

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

موارد استفاده

این نوع پروانه برای برنامه‌هایی درنظر گرفته شده است که توسط توسعه‌دهندگان طرف سوم نوشته شده‌اند و با ارائه‌دهنده API رابطه کسب‌وکار قابل‌اعتمادی ندارند. برای مثال، توسعه‌دهندگانی که برای برنامه‌های میانای برنامه‌سازی کاربردی عمومی ثبت‌نام می‌کنند نباید به‌طورکلی مورد اعتماد قرار گیرند. با این نوع اعطا، اطلاعات کاربری کاربر در سرور منبع هرگز با برنامه هم‌رسانی نمی‌شود.

نمونه کد

می‌توانید پیاده‌سازی نمونه کامل و کارآمدی از نوع اعطای کد مجوز را در Apigee Edge در مخزن api-platform-samples در GitHub پیدا کنید. oauth-advanced نمونه را در فهرست راهنمای api-platform-samples/sample-proxies ببینید. برای جزئیات مربوط به نمونه، فایل README را ببینید.

روندنما

جریان نمودار زیر جریان کد مجوز OAuth را با Apigee Edge که به‌عنوان سرور مجوز عمل می‌کند نشان می‌دهد.

نکته: برای دیدن نسخه بزرگ‌تری از این نمودار، روی آن کلیک راست کنید و آن را در برگه جدیدی باز کنید، یا آن را ذخیره کنید و در نمایشگر تصویر باز کنید.

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

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

پیش‌نیاز: برنامه کارخواه باید در Apigee Edge ثبت شده باشد تا کلیدهای رمز کارخواه و شناسه کارخواه را دریافت کند. برای جزئیات بیشتر، ثبت برنامه‌های کارخواه را ببینید.

۱. کاربر جریان را آغاز می‌کند

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

۲. کاربر اعتبارنامه را وارد می‌کند

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

۳. کاربر رضایت می‌دهد

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

۴. برنامه ورود به سیستم درخواستی به Apigee Edge ارسال می‌کند

اگر ورود به سیستم و رضایت موفقیت‌آمیز باشد، برنامه ورود به سیستم داده‌ها را به نقطه پایانی /authorizationcode در Apigee Edge ارسال می‌کند. داده‌ها شامل نشانی وب بازفرستادن، شناسه کارخواه، محدوده، هرگونه اطلاعات خاص کاربر که می‌خواهد اضافه کند، و نشانه‌ای از موفقیت‌آمیز بودن ورود به سیستم است.

۵. ‫Apigee Edge کد مجوزی تولید می‌کند

وقتی Edge درخواست POST را از برنامه ورود به سیستم در نقطه پایانی /authorizationcode خود دریافت می‌کند، دو اتفاق می‌افتد. ابتدا، Edge تعیین می‌کند که ورود به سیستم موفقیت‌آمیز بوده است (با بررسی پارامترهای درخواست یا سرایندها برای نشانگر موفقیت). سپس، Edge بررسی می‌کند تا مطمئن شود که شناسه URI هدایت ارسال‌شده از برنامه ورود به سیستم با شناسه URI هدایتی که هنگام ثبت برنامه در Apigee Edge مشخص شده است مطابقت داشته باشد. اگر همه‌چیز درست باشد، Edge کد مجوزی تولید می‌کند.

{redirect_uri}?code={authorization_code}&state={some_string}

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

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

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

‫۷. کارخواه کد دسترسی دریافت می‌کند

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

‫۸. کارخواه میانای برنامه‌سازی کاربردی محافظت‌شده را فراخوانی می‌کند

اکنون، با یک کد دسترسی معتبر، کارخواه می‌تواند با «میانای برنامه‌سازی کاربردی» محافظت‌شده تماس بگیرد. در این سناریو، درخواست‌ها به Apigee Edge (پراکسی) ارسال می‌شود و Edge مسئولیت دارد کد دسترسی را قبل‌از ارسال تماس API به سرور منبع هدف درستی‌سنجی کند. کدهای دسترسی در سرایند «مجوز» ارسال می‌شوند. برای مثال:

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

پیکربندی جریان‌ها و خط‌مشی‌ها

‫Edge به‌عنوان سرور مجوز باید تعدادی درخواست OAuth را پردازش کند: برای کدهای مجوز، ژتون‌های دسترسی، ژتون‌های بازآوری، هدایت‌های صفحه ورود به سیستم، و غیره. برای پیکربندی این نقاط پایان دو مرحله اساسی وجود دارد:

  • درحال ایجاد جریان‌های سفارشی
  • افزودن و پیکربندی خط‌مشی‌های OAuthV2

پیکربندی جریان سفارشی

معمولاً این جریان نوع اعطا را به‌گونه‌ای پیکربندی می‌کنید که هر مرحله یا «بخش» جریان توسط یک جریان در پراکسی Apigee Edge تعریف شود. هر جریان دارای یک نقطه پایانی و یک خط‌مشی است که وظیفه خاص OAuth موردنیاز را انجام می‌دهد، مانند تولید کد مجوز یا کد دسترسی. برای مثال، همان‌طور که در XML زیر نشان داده شده است، نقطه پایانی /oauth/authorizationcode خط‌مشی مرتبطی به نام GenerateAuthCode دارد (که خط‌مشی OAuthV2 با عملکرد GenerateAuthorizationCode مشخص‌شده است).

آسان‌ترین راه برای نشان دادن پیکربندی جریان با یک نمونه XML است. برای اطلاعات درباره هر جریان، نظرات به‌خط را ببینید. این یک نمونه است -- نام جریان‌ها و مسیرها را می‌توانید هرطور که می‌خواهید پیکربندی کنید. برای نمای کلی سریع از مراحل لازم برای ایجاد یک جریان سفارشی مانند این، به پیکربندی نقاط پایانی و خط‌مشی‌های OAuth نیز مراجعه کنید.

همچنین پیاده‌سازی مثال را در GitHub ببینید.

<Flows>
<Flow name="RedirectToLoginApp">
<!--
Publish this URI to developers to use for their 'login' link
-->
<Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
<Request>
<Step><Name>RedirectToLoginPage</Name></Step>
</Request>
</Flow>
<Flow name="GetAuthCode">
<!--
Call this URL from your Login app after you authenticate the user.
The policy will automatically return the auth code in the response to the
redirect_uri registered by the calling app
-->
<Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
<Request>
<Step><Name>GenerateAuthCode</Name></Step>
</Request>
</Flow>
<Flow name="GetAccessToken">
<!-- This policy flow is triggered when the URI path suffix
matches /oauth/accesstoken. Publish this URL to app developers
to use when obtaining an access token using an auth code
-->
<Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
<Request>
<Step><Name>GenerateAccessToken</Name></Step>
</Request>
</Flow>
</Flows>

جریان‌های کار را با خط‌مشی‌ها پیکربندی کنید

هر نقطه پایانی خط‌مشی منسوب به خود دارد. بیایید نمونه‌هایی از خط‌مشی‌ها را ببینیم. برای نمای کلی سریع از مراحل لازم برای افزودن خط‌مشی‌های OAuthV2 به نقاط پایانی پراکسی، به پیکربندی نقاط پایانی و خط‌مشی‌های OAuth نیز مراجعه کنید.

هدایت ورود به سیستم

این مسیر /oauth/authorize است. خط‌مشی پیوست‌شده مسئول هدایت کاربر به برنامه ورود به سیستم است. در این برنامه، کاربر نهایی می‌تواند بدون فاش کردن نام کاربری و گذرواژه خود به برنامه کارخواه، برنامه کارخواه را برای دسترسی به منابع محافظت‌شده‌اش به‌طور ایمن اصالت‌سنجی و مجاز کند. می‌توانید این کار را با خط‌مشی فراخوانی سرویس، JavaScript،‏ Node.js، یا روش‌های دیگر انجام دهید.

تماس با «میانای برنامه‌سازی کاربردی» برای انجام درخواست GET است و به پارامترهای پُرسمان client_id، response_type،‏ redirect_uri،‏ scope، و state نیاز دارد.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

دریافت کد مجوز

این مسیر /oauth/authorizationcode است. از خط‌مشی OAuthV2 با عملیات GenerateAuthorizationCode مشخص‌شده استفاده می‌کند.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

فراخوانی API برای دریافت کد مجوز یک POST است و نیاز دارد که client_id،‏ response_type،‏ redirect_uri، و به‌صورت اختیاری scope و state در بدنه درخواست به‌عنوان پارامترهای فرم ارسال شوند، همان‌طور که در این مثال نشان داده شده است:

$ curl http://myorg-test.apigee.net/oauth/authorizationcode -X POST -d 'client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}'

دریافت کد دسترسی

این خط‌مشی به مسیر /oauth/accesstoken پیوست شده است. از خط‌مشی OAuthV2 با عملیات GenerateAccessToken مشخص‌شده استفاده می‌کند. در این مورد، پارامتر grant_type به‌عنوان پارامتر پُرسمان موردانتظار است:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn>
    <SupportedGrantTypes>
        <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

فراخوانی API برای دریافت کد دسترسی یک فراخوانی POST است و باید شامل کد مجوز، client_id، client_secret،‏ grant_type=authorization_code، و درصورت تمایل، scope باشد. برای مثال:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'code={authorization_code}&client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

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

پیوست کردن خط‌مشی کد دسترسی درستی‌سنجی

خط‌مشی VerifyAccessToken (خط‌مشی OAuthV2 با عملیات VerifyAccessToken مشخص‌شده) را به ابتدای هر جریانی که به یک API محافظت‌شده دسترسی دارد پیوست کنید، تا هرگاه درخواستی برای یک منبع محافظت‌شده ارسال می‌شود، اجرا شود. ‫Edge بررسی می‌کند تا مطمئن شود هر درخواست دارای رمز دسترسی معتبر است. اگر مشخص نشده باشد، خطایی برمی‌گردد. برای مراحل اولیه، درستی‌سنجی کردن کدهای دسترسی را ببینید.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

فراخوانی API محافظت‌شده

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

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

همچنین ارسال کد دسترسی را ببینید.