Làm việc với các phạm vi OAuth2

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về Apigee X. thông tin

Chủ đề này thảo luận cách sử dụng các phạm vi OAuth 2.0 trên Apigee Edge.

Phạm vi OAuth2 là gì?

Phạm vi OAuth 2.0 cung cấp một cách để giới hạn lượng truy cập được cấp cho một quyền truy cập mã thông báo. Ví dụ: mã truy cập được cấp cho một ứng dụng khách có thể được cấp quyền READ và GHI vào tài nguyên được bảo vệ hoặc chỉ truy cập READ. Bạn có thể triển khai API để thực thi mọi phạm vi hoặc tổ hợp phạm vi mà bạn muốn. Vì vậy, nếu ứng dụng nhận được mã thông báo có phạm vi READ và ứng dụng đó cố gắng gọi một điểm cuối API yêu cầu quyền GHI, thì lệnh gọi sẽ không thành công.

Trong chủ đề này, chúng ta sẽ thảo luận về cách chỉ định phạm vi để truy cập vào mã thông báo và cách Apigee Edge thực thi các phạm vi OAuth 2.0. Sau khi đọc chủ đề này, bạn sẽ có thể sử dụng phạm vi với sự tự tin.

Phạm vi được chỉ định cho mã truy cập như thế nào?

Khi tạo mã truy cập, Edge có thể chỉ định một phạm vi cho mã thông báo đó. Để tìm hiểu cách thực hiện tình huống này xảy ra thì trước tiên, bạn phải làm quen với các thực thể Apigee Edge sau: sản phẩm API, nhà phát triển và nhà phát triển ứng dụng của mình. Để tìm hiểu phần giới thiệu, hãy xem phần Giới thiệu về việc xuất bản. Bạn nên bạn xem lại tài liệu này nếu cần trước khi tiếp tục.

Mã truy cập là một chuỗi dài gồm các ký tự trông ngẫu nhiên cho phép Edge xác minh các yêu cầu API đến (hãy coi đây là phiên bản độc lập cho các yêu cầu thông thường thông tin xác thực tên người dùng/mật khẩu). Về mặt kỹ thuật, mã thông báo là khoá tham chiếu đến một tập hợp siêu dữ liệu trông giống như sau:

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Siêu dữ liệu của mã thông báo bao gồm chuỗi mã thông báo truy cập thực tế, thông tin hết hạn, thông tin nhận dạng ứng dụng của nhà phát triển, nhà phát triển và các sản phẩm được liên kết với mã thông báo. Bạn sẽ bạn cũng cần lưu ý rằng siêu dữ liệu cũng bao gồm cả "phạm vi".

Mã thông báo có được phạm vi như thế nào?

Chìa khoá đầu tiên để hiểu phạm vi là cần nhớ rằng mỗi sản phẩm trong ứng dụng dành cho nhà phát triển không có hoặc có nhiều phạm vi được chỉ định cho phạm vi đó. Bạn có thể chỉ định các phạm vi này khi sản phẩm hoặc có thể được thêm vào sau. Chúng tồn tại dưới dạng danh sách các tên và nằm trong "siêu dữ liệu" liên kết với từng sản phẩm.

Khi bạn tạo một ứng dụng của nhà phát triển và thêm sản phẩm vào ứng dụng đó, Edge sẽ xem xét tất cả sản phẩm trong ứng dụng của nhà phát triển và tạo một danh sách tất cả các phạm vi cho những sản phẩm đó (ứng dụng chính hoặc danh sách phạm vi toàn cầu -- tập hợp tất cả các phạm vi được công nhận).

Khi một ứng dụng khách yêu cầu mã truy cập từ Apigee Edge, ứng dụng khách này có thể tuỳ ý chỉ định mã truy cập nào mà mình muốn liên kết với mã thông báo đó. Ví dụ: yêu cầu sau đây yêu cầu cho phạm vi "A". Tức là máy khách yêu cầu máy chủ uỷ quyền (Edge) tạo một mã truy cập có phạm vi "A" (cho phép ứng dụng gọi các API có phạm vi "A"). Ứng dụng sẽ gửi một yêu cầu POST như sau:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

Điều gì sẽ xảy ra?

Khi nhận được yêu cầu này, Edge sẽ biết ứng dụng nào đang đưa ra yêu cầu và biết ứng dụng nào ứng dụng của nhà phát triển mà khách hàng đã đăng ký (mã ứng dụng khách và khoá bí mật của ứng dụng khách được mã hoá trong tiêu đề xác thực cơ bản). Vì tham số truy vấn scope được đưa vào nên Edge cần phải quyết định xem có sản phẩm API nào liên kết với ứng dụng của nhà phát triển có phạm vi "A" không. Nếu có, thì hệ thống sẽ tạo mã truy cập có phạm vi "A". Một cách khác để xem xét vấn đề này là phạm vi tham số truy vấn là một loại bộ lọc. Nếu ứng dụng của nhà phát triển nhận ra phạm vi "A, B, X" và tham số truy vấn chỉ định "scope=X Y Z", sau đó chỉ phạm vi "X" sẽ được chỉ định cho mã thông báo.

Nếu khách hàng không đính kèm thông số phạm vi thì sao? Trong trường hợp này, Edge sẽ tạo một mã thông báo bao gồm tất cả các phạm vi mà ứng dụng của nhà phát triển công nhận. Bây giờ bạn cần hiểu rằng hành vi mặc định là trả về mã truy cập chứa cho tất cả sản phẩm có trong ứng dụng của nhà phát triển.

Nếu không có sản phẩm nào liên kết với ứng dụng của nhà phát triển chỉ định phạm vi và mã thông báo có một phạm vi, thì các lệnh gọi được thực hiện bằng mã thông báo đó sẽ không thực hiện được.

Giả sử một ứng dụng của nhà phát triển nhận ra các phạm vi sau: A B C D. Đây là danh sách chính của ứng dụng phạm vi. Có thể là một sản phẩm trong ứng dụng có phạm vi A và B, đồng thời sản phẩm thứ hai có phạm vi C và D hoặc bất kỳ tổ hợp nào. Nếu ứng dụng không chỉ định tham số scope (hoặc nếu mã này chỉ định tham số phạm vi không có giá trị), mã thông báo sẽ được cấp ở cả 4 phạm vi: A, B, C, và D. Xin nhắc lại, mã thông báo nhận được một tập hợp phạm vi là hợp nhất của tất cả các phạm vi được công nhận thông qua ứng dụng của nhà phát triển.

Có thêm một trường hợp mà hành vi mặc định là trả về mã thông báo truy cập cùng với tất cả các phạm vi đã xác định. Đó cũng là khi chính sách GenerateAccessToken (chính sách của Apigee Edge) tạo mã truy cập) không chỉ định phần tử <Scope>. Ví dụ: đây là một chính sách GenerateAccessToken trong đó <Scope> được chỉ định. Nếu phần tử <Scope> đó bị thiếu (hoặc nếu hiện diện nhưng trống), thì hành vi mặc định được thực thi. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Phạm vi được thực thi như thế nào?

Trước tiên, hãy nhớ rằng trên Apigee Edge, mã truy cập sẽ được xác thực bằng chính sách OAuthV2 (thường được đặt ở đầu luồng proxy). Chính sách phải có Đã chỉ định thao tác VerifyAccessToken. Hãy cùng tìm hiểu chính sách này:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

Hãy lưu ý phần tử <Scope>. Trường này dùng để chỉ định phạm vi mà chính sách sẽ chấp nhận.

Trong ví dụ này, chính sách chỉ thành công nếu mã truy cập có phạm vi "A". Nếu trường hợp này &lt;Scope&gt; phần tử bị bỏ qua hoặc nếu phần tử này không có giá trị, thì chính sách sẽ bỏ qua phạm vi của phần tử mã truy cập.

Giờ đây, với khả năng xác thực mã truy cập dựa trên phạm vi, bạn có thể thiết kế API để thực thi các phạm vi cụ thể. Bạn thực hiện việc này bằng cách thiết kế luồng tuỳ chỉnh bằng VerifyAccessToken nhận biết phạm vi đi kèm với các chính sách đó.

Giả sử API của bạn có một luồng được xác định cho điểm cuối /resourceA:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

Khi quy trình này được kích hoạt (một yêu cầu sẽ có /resourceA trong đường dẫn thì chính sách OAuthV2-VerifyAccessTokenA sẽ được gọi ngay lập tức. Chính sách này xác minh rằng mã truy cập hợp lệ và có vẻ như mã này hỗ trợ(các) phạm vi nào. Nếu chính sách định cấu hình như ví dụ bên dưới, với <Scope>A</Scope>, chính sách sẽ chỉ thành công nếu mã truy cập có phạm vi "A". Nếu không, hàm này sẽ trả về lỗi.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Tóm lại, nhà phát triển API chịu trách nhiệm thiết kế việc thực thi phạm vi trong API của họ. Họ thực hiện việc này bằng cách tạo các quy trình tuỳ chỉnh để xử lý các phạm vi cụ thể và đính kèm VerifyAccessToken để thực thi các phạm vi đó.

Ví dụ về mã

Cuối cùng, hãy xem một số lệnh gọi API mẫu để minh hoạ cách nhận mã thông báo và cách thực thi phạm vi.

Kiểu viết hoa mặc định

Giả sử bạn có một ứng dụng của nhà phát triển với các sản phẩm và sự kết hợp của những sản phẩm đó các phạm vi là: A, B và C. Lệnh gọi API này yêu cầu mã truy cập nhưng không chỉ định truy vấn phạm vi . 

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

Trong trường hợp này, mã thông báo đã tạo sẽ được cấp các phạm vi A, B và C (hành vi mặc định). Chiến lược phát hành đĩa đơn siêu dữ liệu của mã thông báo sẽ có dạng như sau:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Bây giờ, giả sử bạn có một điểm cuối API có phạm vi "A" (đó là VerifyAccessToken yêu cầu phạm vi "A"). Sau đây là chính sách VerifyAccessToken:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Dưới đây là mẫu lệnh gọi đến và điểm cuối thực thi phạm vi A:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA

Lệnh gọi GET này thành công:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

Thực hiện thành công vì chính sách VerifyAccessToken được kích hoạt khi điểm cuối được gọi cần có phạm vi A và mã truy cập đã được cấp phạm vi A, B và C – phạm vi mặc định hành vi.

Trường hợp lọc

Giả sử bạn có một ứng dụng dành cho nhà phát triển với các sản phẩm thuộc phạm vi A, B, C và X. Bạn yêu cầu mã truy cập và bao gồm tham số truy vấn scope như sau:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

Trong trường hợp này, mã thông báo được tạo sẽ được cấp các phạm vi A và X, vì cả A và X đều là một phạm vi phạm vi hợp lệ. Hãy nhớ rằng ứng dụng của nhà phát triển nhận dạng các phạm vi A, B, C và X. Trong trường hợp này, bạn đang lọc danh sách sản phẩm API dựa trên các phạm vi này. Nếu một sản phẩm có phạm vi A hoặc X, bạn có thể định cấu hình các điểm cuối API sẽ thực thi các phạm vi này. Nếu một sản phẩm không có phạm vi A hoặc X (giả sử ứng dụng có B, C và Z), thì không thể gọi những API thực thi phạm vi A hoặc X với mã thông báo.

Khi bạn gọi API bằng mã thông báo mới:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

Mã truy cập đã được proxy API xác thực. Ví dụ:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Lệnh kích hoạt lệnh gọi GET thành công và trả về một phản hồi. Ví dụ:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

Xác minh thành công vì chính sách VerifyAccessToken yêu cầu phạm vi A hoặc X và mã truy cập bao gồm phạm vi A và X. Tất nhiên, nếu phần tử <Scope> được đặt thành "B", lệnh gọi này sẽ không thực hiện được.

Tóm tắt

Bạn cần hiểu cách Apigee Edge xử lý các phạm vi OAuth 2.0. Sau đây là những điểm chính cần ghi nhớ điểm:

  • Ứng dụng của nhà phát triển "nhận dạng" sự kết hợp của tất cả các phạm vi được xác định cho tất cả các sản phẩm của công ty.
  • Khi yêu cầu mã truy cập, ứng dụng sẽ có cơ hội chỉ định phạm vi mà ứng dụng sẽ thực hiện mong muốn. Việc xác định phạm vi là tuỳ thuộc vào Apigee Edge (máy chủ uỷ quyền) sẽ thực sự chỉ định cho mã truy cập dựa trên (a) (các) phạm vi được yêu cầu và (b) những chức năng mà ứng dụng của nhà phát triển công nhận.
  • Nếu bạn không định cấu hình Apigee Edge để kiểm tra phạm vi (phần tử <Scope> bị thiếu trong chính sách VerifyAccessToken hoặc chính sách này trống), thì lệnh gọi API sẽ thành công miễn là phạm vi được nhúng trong mã truy cập khớp với một trong các phạm vi được ứng dụng dành cho nhà phát triển đã đăng ký (một trong các phạm vi trong danh sách phạm vi "chính" của ứng dụng).
  • Nếu mã truy cập không được liên kết với bất kỳ phạm vi nào, thì mã truy cập đó sẽ chỉ thành công trong trường hợp Edge không xem xét phạm vi (thiếu phần tử <Scope> từ chính sách VerifyAccessToken hoặc chính sách này trống).