Triển khai kiểu cấp mã uỷ quyền

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. info

Mã uỷ quyền là một trong những loại cấp quyền OAuth 2.0 được sử dụng phổ biến nhất. Quy trình sử dụng mã uỷ quyền là một cấu hình "OAUTH ba bên". Trong cấu hình này, người dùng tự xác thực với máy chủ tài nguyên và cho phép ứng dụng truy cập vào các tài nguyên được bảo vệ của họ mà không tiết lộ tên người dùng/mật khẩu cho ứng dụng.

Giới thiệu về chủ đề này

Chủ đề này cung cấp thông tin mô tả chung và tổng quan về quy trình cấp quyền ủy quyền OAuth 2.0, đồng thời thảo luận về cách triển khai quy trình này trên Apigee Edge.

Video

Xem video ngắn để tìm hiểu cách sử dụng loại cấp quyền OAuth 2.0 nhằm bảo mật API.

Trường hợp sử dụng

Loại cấp quyền này dành cho các ứng dụng do nhà phát triển bên thứ ba viết, những người không có mối quan hệ kinh doanh đáng tin cậy với nhà cung cấp API. Ví dụ: nhà phát triển đăng ký các chương trình API công khai thường không được tin cậy. Với loại cấp quyền này, thông tin đăng nhập của người dùng trên máy chủ tài nguyên sẽ không bao giờ được chia sẻ với ứng dụng.

Mã mẫu

Bạn có thể tìm thấy một mẫu triển khai hoàn chỉnh và hoạt động của loại cấp quyền mã uỷ quyền trên Apigee Edge trong kho lưu trữ api-platform-samples trên GitHub. Hãy xem mẫu oauth-advanced sample trong thư mục api-platform-samples/sample-proxies. Xem tệp README để biết thông tin chi tiết về mẫu.

Sơ đồ quy trình

Sơ đồ quy trình sau đây minh hoạ quy trình OAuth sử dụng mã uỷ quyền với Apigee Edge đóng vai trò là máy chủ uỷ quyền.

Mẹo: Để xem phiên bản lớn hơn của sơ đồ này, hãy nhấp chuột phải vào sơ đồ rồi mở trong một thẻ mới hoặc lưu sơ đồ đó rồi mở trong trình xem hình ảnh.

Các bước trong quy trình sử dụng mã uỷ quyền

Sau đây là bản tóm tắt các bước cần thiết để triển khai loại cấp quyền mã uỷ quyền, trong đó Apigee Edge đóng vai trò là máy chủ uỷ quyền. Hãy nhớ rằng điểm mấu chốt của quy trình này là ứng dụng không bao giờ thấy thông tin đăng nhập của người dùng trên máy chủ tài nguyên.

Điều kiện tiên quyết: Ứng dụng phải được đăng ký với Apigee Edge để lấy mã ứng dụng và khoá bí mật của ứng dụng. Xem bài viết Đăng ký ứng dụng để biết thông tin chi tiết.

1. Người dùng bắt đầu quy trình

Khi ứng dụng cần truy cập vào các tài nguyên được bảo vệ của người dùng từ một máy chủ tài nguyên (ví dụ: danh bạ trên một trang mạng xã hội), ứng dụng sẽ gửi một lệnh gọi API đến Apigee Edge. Apigee Edge sẽ xác thực mã ứng dụng và nếu mã đó hợp lệ, thì sẽ chuyển hướng trình duyệt của người dùng đến một trang đăng nhập, nơi người dùng sẽ nhập thông tin đăng nhập của họ. Lệnh gọi API bao gồm thông tin mà ứng dụng đã nhận được khi đăng ký: mã ứng dụng và URI chuyển hướng.

2. Người dùng nhập thông tin đăng nhập

Giờ đây, người dùng sẽ thấy một trang đăng nhập yêu cầu họ nhập thông tin đăng nhập. Nếu đăng nhập thành công, chúng ta sẽ chuyển sang bước tiếp theo.

3. Người dùng đồng ý

Trong bước này, người dùng đồng ý cho phép ứng dụng truy cập vào tài nguyên của họ. Biểu mẫu đồng ý thường bao gồm các lựa chọn về phạm vi, trong đó người dùng có thể chọn những việc mà ứng dụng được phép thực hiện trên máy chủ tài nguyên. Ví dụ: người dùng có thể cấp quyền chỉ đọc hoặc quyền cho phép ứng dụng cập nhật tài nguyên.

4. Ứng dụng đăng nhập gửi yêu cầu đến Apigee Edge

Nếu đăng nhập và đồng ý thành công, ứng dụng đăng nhập sẽ gửi dữ liệu đến điểm cuối /authorizationcode của Apigee Edge. Dữ liệu này bao gồm URI chuyển hướng, mã ứng dụng, phạm vi, mọi thông tin dành riêng cho người dùng mà ứng dụng muốn đưa vào và dấu hiệu cho biết đăng nhập thành công.

5. Apigee Edge tạo mã uỷ quyền

Khi Edge nhận được yêu cầu POST từ ứng dụng đăng nhập trên điểm cuối /authorizationcode, sẽ có 2 điều xảy ra. Trước tiên, Edge xác định rằng quá trình đăng nhập đã thành công (bằng cách kiểm tra các tham số hoặc tiêu đề yêu cầu để tìm chỉ báo thành công). Tiếp theo, Edge kiểm tra để đảm bảo rằng URI chuyển hướng được gửi từ ứng dụng đăng nhập khớp với URI chuyển hướng được chỉ định khi ứng dụng được đăng ký với Apigee Edge. Nếu mọi thứ đều ổn, Edge sẽ tạo mã uỷ quyền.

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

6. Ứng dụng truy xuất mã uỷ quyền và yêu cầu mã truy cập từ Edge

Giờ đây, với mã uỷ quyền hợp lệ, ứng dụng có thể yêu cầu mã truy cập từ Edge. Ứng dụng thực hiện việc này bằng cách gửi mã ứng dụng khách và khoá bí mật của ứng dụng khách (nhận được khi ứng dụng được đăng ký trên Edge), mã uỷ quyền, loại cấp quyền và phạm vi. Bằng cách đưa mã ứng dụng và khoá bí mật vào, Apigee Edge có thể xác minh rằng ứng dụng là ứng dụng đã đăng ký. Ví dụ:

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

7. Ứng dụng nhận được mã truy cập

Nếu mọi thứ đều thành công, Edge sẽ trả về mã truy cập cho ứng dụng. Mã truy cập sẽ có thời gian hết hạn và chỉ hợp lệ cho phạm vi mà người dùng chỉ định khi họ đồng ý cho phép ứng dụng truy cập vào tài nguyên của họ.

8. Ứng dụng gọi API được bảo vệ

Giờ đây, với mã truy cập hợp lệ, ứng dụng có thể gọi API được bảo vệ. Trong trường hợp này, các yêu cầu được gửi đến Apigee Edge (proxy) và Edge chịu trách nhiệm xác thực mã truy cập trước khi chuyển lệnh gọi API đến máy chủ tài nguyên đích. Mã truy cập được truyền trong tiêu đề Uỷ quyền. Ví dụ:

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

Định cấu hình quy trình và chính sách

Là máy chủ uỷ quyền, Edge cần xử lý một số yêu cầu OAuth: mã truy cập, mã uỷ quyền, mã làm mới, chuyển hướng trang đăng nhập, v.v. Có 2 bước cơ bản để định cấu hình các điểm cuối này:

Tạo quy trình tuỳ chỉnh
Thêm và định cấu hình chính sách OAuthV2

Cấu hình quy trình tuỳ chỉnh

Bạn thường định cấu hình quy trình sử dụng loại cấp quyền này để mỗi bước hoặc "chân" của quy trình được xác định bằng một quy trình trong proxy Apigee Edge. Mỗi quy trình có một điểm cuối và một chính sách thực hiện tác vụ dành riêng cho OAuth cần thiết, chẳng hạn như tạo mã uỷ quyền hoặc mã truy cập. Ví dụ: như minh hoạ trong XML bên dưới, điểm cuối /oauth/authorizationcode có một chính sách được liên kết có tên là GenerateAuthCode (đây là chính sách OAuthV2 có chỉ định thao tác GenerateAuthorizationCode).

Cách dễ nhất để hiển thị cấu hình quy trình là sử dụng ví dụ XML. Xem nhận xét nội tuyến để biết thông tin về từng quy trình. Đây là một ví dụ – bạn có thể định cấu hình tên của quy trình và đường dẫn theo ý muốn. Hãy xem thêm bài viết Định cấu hình điểm cuối và chính sách OAuth để biết thông tin tổng quan nhanh về các bước cần thiết để tạo một quy trình tuỳ chỉnh như thế này.

Hãy xem thêm ví dụ về cách triển khai trên 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>

Định cấu hình quy trình bằng chính sách

Mỗi điểm cuối có một chính sách được liên kết. Hãy xem các ví dụ về chính sách. Hãy xem thêm bài viết Định cấu hình điểm cuối và chính sách OAuth để biết thông tin tổng quan nhanh về các bước cần thiết để thêm chính sách OAuthV2 vào điểm cuối proxy.

Đây là đường dẫn /oauth/authorize. Chính sách được đính kèm chịu trách nhiệm chuyển hướng người dùng đến một ứng dụng đăng nhập, nơi người dùng cuối có thể xác thực và cho phép ứng dụng truy cập vào các tài nguyên được bảo vệ của họ một cách an toàn mà không tiết lộ tên người dùng và mật khẩu cho ứng dụng. Bạn có thể thực hiện việc này bằng chính sách gọi dịch vụ, JavaScript, Node.js hoặc các phương tiện khác.

Lệnh gọi API để thực hiện yêu cầu là GET và yêu cầu các tham số truy vấn client_id, response_type, redirect_uri, scope và 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}

Nhận mã uỷ quyền

Đây là đường dẫn /oauth/authorizationcode. Đường dẫn này sử dụng chính sách OAuthV2 có chỉ định thao tác GenerateAuthorizationCode.

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

Lệnh gọi API để lấy mã uỷ quyền là POST và yêu cầu client_id, response_type, redirect_uri và tuỳ chọn phạm vi và trạng thái được truyền trong nội dung yêu cầu dưới dạng tham số biểu mẫu, như minh hoạ trong ví dụ này:

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

Nhận mã truy cập

Chính sách này được đính kèm vào đường dẫn /oauth/accesstoken. Đường dẫn này sử dụng chính sách OAuthV2 có chỉ định thao tác GenerateAccessToken. Trong trường hợp này, tham số grant_type được dự kiến là tham số truy vấn:

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

Lệnh gọi API để lấy mã truy cập là POST và phải bao gồm mã uỷ quyền, client_id, client_secret, grant_type=authorization_code và tuỳ chọn phạm vi. Ví dụ:

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

Đây chỉ là bản tóm tắt cơ bản. Ví dụ về bản phát hành bao gồm nhiều chính sách khác để tạo URL, thực hiện các phép biến đổi và thực hiện các tác vụ khác. Hãy tham khảo mẫu trên GitHub để biết dự án hoàn chỉnh và hoạt động.

Đính kèm chính sách xác minh mã truy cập

Đính kèm chính sách VerifyAccessToken (chính sách OAuthV2 có chỉ định thao tác VerifyAccessToken ) vào đầu bất kỳ quy trình nào truy cập vào API được bảo vệ, để chính sách này được thực thi bất cứ khi nào có yêu cầu về tài nguyên được bảo vệ. Edge kiểm tra để đảm bảo mỗi yêu cầu đều có a mã truy cập hợp lệ. Nếu không, lỗi sẽ được trả về. Để biết các bước cơ bản, hãy xem bài viết Xác minh mã truy cập.

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

Gọi API được bảo vệ

Để gọi một API được bảo vệ bằng tính năng bảo mật OAuth 2.0, bạn cần cung cấp mã truy cập hợp lệ. Mẫu chính xác là đưa mã thông báo vào tiêu đề Uỷ quyền, như sau: Xin lưu ý rằng mã truy cập còn được gọi là "mã thông báo truy cập".

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

Hãy xem thêm bài viết Gửi mã truy cập.