پیاده سازی نوع اعطای اعتبار مشتری

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

با نوع اعطای اعتبارنامه‌های کلاینت، یک برنامه اعتبارنامه‌های خود (شناسه کلاینت و راز کلاینت) را به یک نقطه پایانی در Apigee Edge که برای تولید یک توکن دسترسی تنظیم شده است، ارسال می‌کند. اگر اعتبارنامه‌ها معتبر باشند، Edge یک توکن دسترسی را به برنامه کلاینت برمی‌گرداند.

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

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

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

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

نقش‌ها

نقش‌ها، «بازیگرانی» را که در جریان OAuth شرکت می‌کنند، مشخص می‌کنند. بیایید یک مرور سریع بر نقش‌های اعتبارنامه‌های کلاینت انجام دهیم تا به شما نشان دهیم که Apigee Edge در کجا قرار می‌گیرد. برای بحث کامل در مورد نقش‌های OAuth 2.0، به مشخصات IETF OAuth 2.0 مراجعه کنید.

• برنامه کلاینت -- برنامه‌ای که نیاز به دسترسی به منابع محافظت‌شده کاربر دارد. معمولاً با این جریان، برنامه به جای اینکه به صورت محلی روی لپ‌تاپ یا دستگاه کاربر اجرا شود، روی سرور اجرا می‌شود.
• Apigee Edge -- در این جریان، Apigee Edge سرور احراز هویت OAuth است. نقش آن تولید توکن‌های دسترسی، اعتبارسنجی توکن‌های دسترسی و ارسال درخواست‌های مجاز برای منابع محافظت‌شده به سرور منبع است.
• سرور منابع -- سرویس بک‌اند که داده‌های محافظت‌شده‌ای را که برنامه‌ی کلاینت برای دسترسی به آنها نیاز به مجوز دارد، ذخیره می‌کند. اگر از پروکسی‌های API میزبانی‌شده در Apigee Edge محافظت می‌کنید، Apigee Edge سرور منابع نیز خواهد بود.

نمونه کد

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

نمودار جریان

نمودار جریان زیر جریان اعتبارنامه‌های کلاینت را با Apigee Edge به عنوان سرور احراز هویت نشان می‌دهد. به طور کلی، Edge در این جریان، سرور منبع نیز هست -- یعنی، پروکسی‌های API منابع محافظت‌شده هستند.

مراحل جریان اعتبارنامه‌های کلاینت

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

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

۱. کلاینت درخواست توکن دسترسی می‌دهد

برای دریافت یک توکن دسترسی، کلاینت یک فراخوانی API به Edge ارسال می‌کند که شامل مقادیر شناسه کلاینت و رمز کلاینت است که از یک برنامه توسعه‌دهنده ثبت‌شده دریافت شده است. علاوه بر این، پارامتر grant_type=client_credentials باید به عنوان یک پارامتر پرس‌وجو ارسال شود. (با این حال، می‌توانید سیاست OAuthV2 را طوری پیکربندی کنید که این پارامتر را در هدر یا بدنه درخواست بپذیرد - برای جزئیات بیشتر به سیاست OAuthV2 مراجعه کنید).

برای مثال:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

نکته: اگرچه می‌توانید مقادیر client_id و client_secret را همانطور که در بالا نشان داده شده است به عنوان پارامترهای پرس و جو ارسال کنید، اما بهتر است آنها را به عنوان یک رشته کدگذاری شده URL با base64 در هدر Authorization ارسال کنید. برای انجام این کار، باید از یک ابزار یا ابزار کدگذاری base64 برای کدگذاری دو مقدار به همراه هم و با جدا کردن آنها با دونقطه استفاده کنید. مانند این: aBase64EncodeFunction(clientidvalue:clientsecret). بنابراین، مثال بالا به این صورت کدگذاری می‌شود:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // به علامت دونقطه که دو مقدار را از هم جدا می‌کند توجه کنید.

نتیجه کدگذاری رشته فوق با استفاده از base64 به صورت زیر است: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

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

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

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

توجه داشته باشید که فراخوانی API به نقطه پایانی /accesstoken ارسال می‌شود. این نقطه پایانی دارای یک سیاست مرتبط با خود است که اعتبارنامه‌های برنامه را تأیید می‌کند. به عبارت دیگر، این سیاست کلیدهای ارسالی را با کلیدهایی که Apigee Edge هنگام ثبت برنامه ایجاد کرده است، مقایسه می‌کند. اگر می‌خواهید درباره نقاط پایانی OAuth در Edge اطلاعات بیشتری کسب کنید، به پیکربندی نقاط پایانی و سیاست‌های OAuth مراجعه کنید.

۳. Edge یک پاسخ برمی‌گرداند

اگر اعتبارنامه‌ها درست باشند، Edge یک توکن دسترسی به کلاینت برمی‌گرداند. در غیر این صورت، یک خطا برمی‌گرداند.

۴. کلاینت، API محافظت‌شده را فراخوانی می‌کند.

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

پیکربندی جریان‌ها و سیاست‌ها

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

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

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

<Flows>
  <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>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

پیکربندی جریان با یک سیاست

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

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

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

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

فراخوانی API برای دریافت توکن دسترسی از نوع POST است و شامل یک هدر Authorization با کدگذاری base64 از client_id + client+secret و پارامتر query به نام grant_type=client_credentials می‌باشد. همچنین می‌تواند شامل پارامترهای اختیاری برای scope و state باشد. برای مثال:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

پیوست کردن سیاست تأیید دسترسی توکن

برای محافظت از API خود با امنیت OAuth 2.0، باید یک سیاست OAuthV2 را با عملیات VerifyAccessToken اضافه کنید. این سیاست بررسی می‌کند که درخواست‌های ورودی دارای توکن دسترسی معتبری باشند. اگر توکن معتبر باشد، Edge درخواست را پردازش می‌کند. اگر معتبر نباشد، 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 

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

منابع اضافی

• Apigee آموزش آنلاین برای توسعه‌دهندگان API ارائه می‌دهد، از جمله دوره‌ای در مورد امنیت API که شامل OAuth نیز می‌شود.
• سیاست OAuthV2 -- مثال‌های زیادی دارد که نحوه ارسال درخواست به سرور احراز هویت و نحوه پیکربندی سیاست OAuthV2 را نشان می‌دهد.