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

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

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

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

این مبحث یک توصیف کلی و نمای کلی از جریان نوع اعطای مجوز OAuth 2.0 ارائه می دهد و نحوه اجرای این جریان را در Apigee Edge مورد بحث قرار می دهد.

ویدئو

برای یادگیری نحوه استفاده از نوع مجوز OAuth 2.0 برای ایمن سازی API های خود، ویدیوی کوتاهی را تماشا کنید.

موارد استفاده کنید

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

نمونه کد

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

نمودار جریان

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

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

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

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

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

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

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

2. کاربر اطلاعات کاربری را وارد می کند

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

3. کاربر رضایت می دهد

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

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

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

5. Apigee Edge یک کد مجوز تولید می کند

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

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

6. Edge کد مجوز را برای مشتری ارسال می کند

Edge یک تغییر مسیر 302 را با کد تأیید به عنوان پارامتر پرس و جو به مشتری ارسال می کند.

7. مشتری کد مجوز را بازیابی می کند و یک کد دسترسی از 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'

8. مشتری یک نشانه دسترسی دریافت می کند

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

9. مشتری با API محافظت شده تماس می گیرد

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

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

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

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

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

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

فراخوانی API برای انجام درخواست یک GET است و به پارامترهای query client_id، answer_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 برای به دست آوردن کد مجوز یک GET است و به پارامترهای query client_id، answer_type، و به صورت اختیاری scope و state نیاز دارد، همانطور که در این مثال نشان داده شده است:

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

رمز دسترسی را دریافت کنید

این خط مشی به مسیر /oauth/accesstoken پیوست شده است. از خط مشی OAuthV2 با عملیات GenerateAccessCode مشخص شده استفاده می کند. در این مورد، پارامتر 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، و در صورت تمایل، محدوده باشد. به عنوان مثال:

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

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

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

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

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