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

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

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

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

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

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

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

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

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

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

۵. 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 یک توکن دسترسی به کلاینت برمی‌گرداند. این توکن دسترسی دارای تاریخ انقضا خواهد بود و فقط برای محدوده‌ای که کاربر هنگام رضایت به برنامه برای دسترسی به منابعش مشخص کرده است، معتبر خواهد بود.

۸. کلاینت، 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 مراجعه کنید.

همچنین به مثال پیاده‌سازی در گیت‌هاب مراجعه کنید.

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

فراخوانی API برای انجام درخواست، از نوع 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'

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

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

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