Yêu cầu mã thông báo truy cập và 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. thông tin

Trong chủ đề này, chúng tôi sẽ chỉ cho bạn cách yêu cầu mã truy cập và mã uỷ quyền, định cấu hình điểm cuối OAuth 2.0 và định cấu hình chính sách cho từng loại cấp quyền được hỗ trợ.

Mã mẫu

Để thuận tiện cho bạn, bạn có thể xem các chính sách và điểm cuối được thảo luận trong chủ đề này trên GitHub trong dự án oauth-doc-examples trong kho lưu trữ Apigee api-platform-samples. Bạn có thể triển khai mã mẫu và thử các yêu cầu mẫu xuất hiện trong chủ đề này. Hãy xem phần README của dự án để biết thông tin chi tiết.

Yêu cầu mã truy cập: loại cấp mã uỷ quyền

Phần này giải thích cách yêu cầu mã truy cập bằng quy trình loại cấp mã uỷ quyền. Để biết giới thiệu về các loại cấp quyền cho OAuth 2.0, hãy xem phần Giới thiệu về OAuth 2.0.

Yêu cầu mẫu

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Tham số bắt buộc

Theo mặc định, các tham số này phải là x-www-form-urlencoded và được chỉ định trong nội dung yêu cầu (như trong mẫu ở trên). Tuy nhiên, bạn có thể thay đổi giá trị mặc định này bằng cách định cấu hình các phần tử <GrantType>, <Code> và <RedirectUri> trong chính sách OAuthV2 được đính kèm vào điểm cuối /accesstoken này. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

  • grant_type – Phải được đặt thành giá trị authorization_code.
  • mã – Mã uỷ quyền nhận được từ điểm cuối /authorize (hoặc bất kỳ mã nào mà bạn chọn đặt tên cho mã đó). Để yêu cầu mã truy cập trong quy trình loại cấp mã uỷ quyền, trước tiên, bạn phải lấy mã uỷ quyền. Hãy xem phần Yêu cầu mã uỷ quyền ở bên dưới. Hãy xem thêm bài viết Triển khai loại cấp mã uỷ quyền.
  • redirect_uri – Bạn phải cung cấp tham số này nếu tham số redirect_uri có trong yêu cầu mã uỷ quyền trước. Nếu tham số redirect_uri không có trong yêu cầu mã uỷ quyền và nếu bạn không cung cấp tham số này, thì chính sách này sẽ sử dụng giá trị của URL gọi lại được cung cấp khi ứng dụng của nhà phát triển được đăng ký.

Tham số không bắt buộc

  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

Bạn phải chuyển Mã ứng dụng khách và Mật khẩu ứng dụng khách dưới dạng tiêu đề Xác thực cơ bản (được mã hoá Base64) hoặc dưới dạng thông số biểu mẫu client_id và client_secret. Bạn lấy các giá trị này từ một ứng dụng của nhà phát triển đã đăng ký. Xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Điểm cuối mẫu

Dưới đây là cấu hình điểm cuối mẫu để tạo mã truy cập. Ứng dụng này sẽ thực thi chính sách GenerateAccessToken. Bạn phải định cấu hình chính sách này để hỗ trợ loại cấp quyền ủy quyền_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Chính sách mẫu

Đây là một chính sách GenerateAccessToken cơ bản được định cấu hình để chấp nhận loại cấp quyền authorization_code. Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về phản hồi JSON chứa mã truy cập, như minh hoạ dưới đây. Loại cấp quyền authorization_code sẽ tạo một mã truy cập và một mã làm mới, vì vậy, phản hồi sẽ có dạng như sau:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Nếu bạn đặt <GenerateResponse> thành false (sai), chính sách sẽ không trả về phản hồi. Thay vào đó, mã này sẽ điền dữ liệu liên quan đến việc cấp mã truy cập cho tập hợp biến luồng sau đây.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ví dụ:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Yêu cầu mã truy cập: loại cấp thông tin đăng nhập ứng dụng

Phần này giải thích cách yêu cầu mã truy cập bằng quy trình loại cấp thông tin đăng nhập ứng dụng. Để biết giới thiệu về các loại cấp quyền cho OAuth 2.0, hãy xem phần Giới thiệu về OAuth 2.0.

Yêu cầu mẫu

Để biết thông tin về cách mã hoá tiêu đề xác thực cơ bản trong lệnh gọi sau, hãy xem phần "Mã hoá thông tin xác thực cơ bản". 

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

Tham số bắt buộc

Theo mặc định, tham số Grant_type bắt buộc phải là x-www-form-urlencoded và được chỉ định trong nội dung yêu cầu (như trong mẫu ở trên); tuy nhiên, bạn có thể thay đổi giá trị mặc định này bằng cách định cấu hình phần tử <GrantType> trong chính sách OAuthV2 được đính kèm vào điểm cuối /accesstoken này. Ví dụ: bạn có thể chọn truyền tham số đó vào một tham số truy vấn. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

  • grant_type – Phải được đặt thành giá trị client_credentials.

Tham số không bắt buộc

  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

Bạn phải chuyển Mã ứng dụng khách và Mật khẩu ứng dụng khách dưới dạng tiêu đề Xác thực cơ bản (được mã hoá Base64) hoặc dưới dạng thông số biểu mẫu client_id và client_secret. Bạn lấy các giá trị này từ ứng dụng của nhà phát triển đã đăng ký được liên kết với yêu cầu. Hãy xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Điểm cuối mẫu

Dưới đây là cấu hình điểm cuối mẫu để tạo mã truy cập. Chrome sẽ thực thi chính sách GenerateAccessToken. Chính sách này phải được định cấu hình để hỗ trợ loại cấp quyền client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Chính sách mẫu

Đây là một chính sách GenerateAccessToken cơ bản được định cấu hình để chấp nhận loại cấp quyền client_credentials. Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về phản hồi JSON. Xin lưu ý rằng với loại cấp quyền client_credentials, mã thông báo làm mới không được hỗ trợ. Chỉ có mã truy cập được đúc. Ví dụ:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Nếu bạn đặt <GenerateResponse> thành false (sai), chính sách sẽ không trả về phản hồi. Thay vào đó, mã này sẽ điền dữ liệu liên quan đến việc cấp mã truy cập cho tập hợp biến luồng sau đây.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Ví dụ:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Yêu cầu mã truy cập: loại cấp mật khẩu

Phần này giải thích cách yêu cầu mã truy cập bằng quy trình loại cấp thông tin xác thực mật khẩu của chủ sở hữu tài nguyên (mật khẩu). Để biết giới thiệu về các loại cấp quyền cho OAuth 2.0, hãy xem phần Giới thiệu về OAuth 2.0.

Để biết thêm thông tin chi tiết về kiểu cấp mật khẩu, bao gồm cả video dài 4 phút hướng dẫn cách triển khai, hãy xem Triển khai kiểu cấp mật khẩu.

Yêu cầu mẫu

Để biết thông tin về cách mã hoá tiêu đề xác thực cơ bản trong lệnh gọi sau, hãy xem phần "Mã hoá thông tin xác thực cơ bản". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Tham số bắt buộc

Theo mặc định, các tham số này phải là x-www-form-urlencoded và được chỉ định trong nội dung yêu cầu (như trong mẫu ở trên). Tuy nhiên, bạn có thể thay đổi giá trị mặc định này bằng cách định cấu hình các phần tử <GrantType>, <Username> và <Password> trong chính sách OAuthV2 được đính kèm vào điểm cuối /token này. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

Thông tin đăng nhập của người dùng thường được xác thực theo kho lưu trữ thông tin xác thực bằng chính sách LDAP hoặc JavaScript.

  • grant_type – Phải được đặt thành giá trị password.
  • tên người dùng – Tên người dùng của chủ sở hữu tài nguyên.
  • password – Mật khẩu của chủ sở hữu tài nguyên.

Tham số không bắt buộc

  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

Bạn phải chuyển Mã ứng dụng khách và Mật khẩu ứng dụng khách dưới dạng tiêu đề Xác thực cơ bản (được mã hoá Base64) hoặc dưới dạng thông số biểu mẫu client_id và client_secret. Bạn lấy các giá trị này từ ứng dụng của nhà phát triển đã đăng ký được liên kết với yêu cầu. Hãy xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Điểm cuối mẫu

Dưới đây là cấu hình điểm cuối mẫu để tạo mã truy cập. Ứng dụng này sẽ thực thi chính sách GenerateAccessToken. Chính sách này phải được định cấu hình để hỗ trợ loại cấp mật khẩu.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Chính sách mẫu

Đây là một chính sách GenerateAccessToken cơ bản được định cấu hình để chấp nhận loại cấp mật khẩu. Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về phản hồi JSON. Xin lưu ý rằng với loại cấp mật khẩu, cả mã truy cập và mã làm mới đều được đúc. Ví dụ:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Nếu bạn đặt <GenerateResponse> thành false (sai), chính sách sẽ không trả về phản hồi. Thay vào đó, mã này sẽ điền dữ liệu liên quan đến việc cấp mã truy cập cho tập hợp biến luồng sau đây.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ví dụ:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Yêu cầu mã truy cập: loại cấp quyền ngầm ẩn

Phần này giải thích cách yêu cầu mã truy cập bằng quy trình loại cấp quyền ngầm ẩn. Để giới thiệu về các loại cấp quyền cho OAuth 2.0, hãy xem phần Giới thiệu về OAuth 2.0.

Yêu cầu mẫu

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Tham số bắt buộc

Theo mặc định, các tham số này phải là tham số truy vấn (như trong mẫu ở trên); tuy nhiên, bạn có thể thay đổi giá trị mặc định này bằng cách định cấu hình các phần tử <ResponseType>, <ClientId> và <RedirectUri> trong chính sách OAuthV2 được đính kèm vào điểm cuối /token này. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

Thông tin xác thực của người dùng thường được xác thực theo kho lưu trữ thông tin xác thực bằng cách sử dụng chú thích dịch vụ LDAP hoặc chính sách JavaScript.

  • response_type – Phải được đặt thành giá trị token.
  • client_id – Mã ứng dụng khách của một ứng dụng của nhà phát triển đã đăng ký.
  • redirect_uri – Tham số này là bắt buộc nếu bạn không cung cấp URI gọi lại khi ứng dụng nhà phát triển ứng dụng được đăng ký. Nếu bạn cung cấp URL gọi lại khi đăng ký ứng dụng, thì URL đó sẽ được so sánh với giá trị này và phải khớp chính xác.

Tham số không bắt buộc

  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

Cấp quyền ngầm ẩn không yêu cầu xác thực cơ bản. Bạn cần phải truyền mã ứng dụng khách dưới dạng tham số yêu cầu, như được giải thích ở đây.

Điểm cuối mẫu

Dưới đây là cấu hình điểm cuối mẫu để tạo mã truy cập. Thao tác này sẽ thực thi chính sách GenerateAccessTokenimplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Chính sách mẫu

Đây là một chính sách cơ bản về GenerateAccessTokenImplicitGrant, giúp xử lý các yêu cầu mã thông báo cho quy trình loại cấp quyền ngầm ẩn. Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về một lệnh chuyển hướng vị trí 302 trong tiêu đề phản hồi. Lệnh chuyển hướng này trỏ đến URL được chỉ định trong thông số redirect_uri và được nối thêm với mã truy cập và thời gian hết hạn của mã thông báo. Xin lưu ý rằng loại cấp quyền ngầm ẩn không hỗ trợ mã thông báo làm mới. Ví dụ:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Nếu bạn đặt <GenerateResponse> thành false (sai), chính sách sẽ không trả về phản hồi. Thay vào đó, mã này sẽ điền dữ liệu liên quan đến việc cấp mã truy cập cho tập hợp biến luồng sau đây.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Ví dụ:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Yêu cầu mã uỷ quyền

Nếu đang sử dụng quy trình loại cấp mã uỷ quyền, bạn cần lấy mã uỷ quyền trước khi có thể yêu cầu mã truy cập.

Yêu cầu mẫu

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

nơi đính kèm chính sách OAuthV2 GenerateAuthorizeCode tại điểm cuối proxy /oauth/authorize (xem điểm cuối mẫu bên dưới).

Tham số bắt buộc

Theo mặc định, các tham số này phải là tham số truy vấn (như trong mẫu ở trên); tuy nhiên, bạn có thể thay đổi giá trị mặc định này bằng cách định cấu hình các phần tử <ResponseType>, <ClientId> và <RedirectUri> trong chính sách OAuthV2 được đính kèm vào điểm cuối /authorize này. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

  • response_type – Phải được đặt thành giá trị code.
  • client_id – Mã ứng dụng khách của một ứng dụng của nhà phát triển đã đăng ký.

Tham số không bắt buộc

  • redirect_uri – Nếu URI gọi lại đầy đủ (không phải một phần) được chỉ định trong ứng dụng khách đã đăng ký, thì tham số này là không bắt buộc; nếu không thì bắt buộc. Lệnh gọi lại là URL mà Edge gửi mã xác thực mới đúc. Hãy xem thêm phần Đăng ký ứng dụng và quản lý khoá API.
  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

Không yêu cầu xác thực cơ bản. Tuy nhiên, bạn phải cung cấp mã ứng dụng khách của ứng dụng đã đăng ký trong yêu cầu.

Điểm cuối mẫu

Dưới đây là cấu hình điểm cuối mẫu để tạo mã uỷ quyền:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Chính sách mẫu

Đây là một chính sách địa lý cơ bản của Generate Uỷ quyềnCode Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về tham số truy vấn ?code đến vị trí redirect_uri (URI gọi lại) có đính kèm mã uỷ quyền. Mã này được gửi qua lệnh chuyển hướng trình duyệt 302, trong đó có URL trong tiêu đề Location (Vị trí) của phản hồi. Ví dụ: ?code=123456.

Nếu bạn đặt <GenerateResponse> thành false, chính sách này sẽ không trả về phản hồi. Thay vào đó, phương thức này sẽ điền dữ liệu liên quan đến mã uỷ quyền cho tập hợp các biến luồng sau đây.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Ví dụ:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Làm mới mã truy cập

Mã làm mới là thông tin xác thực bạn dùng để lấy mã truy cập, thường là sau khi mã truy cập đã hết hạn hoặc không hợp lệ. Mã làm mới sẽ được trả về trong phản hồi khi bạn nhận được mã truy cập.

Cách yêu cầu mã truy cập mới bằng mã làm mới:

Yêu cầu mẫu

Để biết thông tin về cách mã hoá tiêu đề xác thực cơ bản trong lệnh gọi sau, hãy xem phần "Mã hoá thông tin xác thực cơ bản". 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Tham số bắt buộc

  • grant_type – Phải được đặt thành giá trị refresh_token.
  • refresh_token – Mã làm mới được liên kết với mã truy cập mà bạn muốn gia hạn.

Theo mặc định, chính sách này sẽ tìm những tham số này dưới dạng tham số x-www-form-urlencoded được chỉ định trong nội dung yêu cầu, như trong ví dụ trên. Để định cấu hình vị trí thay thế cho các dữ liệu đầu vào này, bạn có thể sử dụng phần tử <GrantType> và <RefreshToken> trong chính sách OAuthV2. Để biết thông tin chi tiết, vui lòng xem chính sách OAuthV2.

Tham số không bắt buộc

  • state (trạng thái) – Một chuỗi sẽ được gửi lại cùng phản hồi. Thường dùng để ngăn chặn các cuộc tấn công giả mạo yêu cầu trên nhiều trang web.
  • phạm vi – Cho phép bạn lọc danh sách các sản phẩm API có thể sử dụng mã thông báo đúc. Để biết thông tin chi tiết về phạm vi, hãy xem bài viết Làm việc với phạm vi OAuth2.

Xác thực

  • client_id
  • client_secret

Bạn phải chuyển Mã ứng dụng khách và Mật khẩu ứng dụng khách dưới dạng tiêu đề Xác thực cơ bản (được mã hoá Base64) hoặc dưới dạng thông số biểu mẫu client_id và client_secret. Hãy xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Khi làm mới mã truy cập, sẽ không có hoạt động xác thực lại người dùng.

Dưới đây là cấu hình điểm cuối mẫu để tạo mã truy cập bằng mã làm mới. Thao tác này sẽ thực thi chính sách RefreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Chính sách mẫu

Đây là một chính sách RefreshAccessToken cơ bản được định cấu hình để chấp nhận loại quyền refresh_token. Để biết thông tin về các phần tử cấu hình không bắt buộc mà bạn có thể định cấu hình bằng chính sách này, hãy xem chính sách OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Trả về

Khi bật <GenerateResponse>, chính sách này sẽ trả về phản hồi JSON chứa mã truy cập mới. Loại cấp refresh_token hỗ trợ đúc cả quyền truy cập và mã thông báo làm mới mới. Ví dụ:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Xin lưu ý rằng sau khi đúc một mã làm mới, mã ban đầu sẽ không còn hợp lệ.

Phản hồi ở trên là những gì bạn nhận được nếu đặt <GenerateResponse> thành true (đúng). Nếu bạn đặt <GenerateResponse> thành false (sai), chính sách sẽ không trả về thông tin phản hồi. Thay vào đó, mã này sẽ điền dữ liệu liên quan đến việc cấp mã truy cập cho tập hợp biến ngữ cảnh (luồng) sau đây.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ví dụ:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Mã hoá thông tin xác thực cơ bản

Khi thực hiện lệnh gọi API để yêu cầu mã thông báo hoặc mã xác thực, bạn nên theo thông số kỹ thuật của OAuth 2.0 để chuyển các giá trị client_id và client_secret làm tiêu đề Xác thực cơ bản HTTP, như mô tả trong IETF RFC 2617. Để thực hiện việc này, bạn phải mã hoá base64 kết quả khi kết hợp hai giá trị với nhau bằng dấu hai chấm để phân tách chúng.

Trong mã giả:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Trong ví dụ này, ns4fQc14Zg4hKFCNaSzArVuwszX95X là client_id và ZIjFyTsNgQNyxI là mật khẩu ứng dụng khách.

Bất kể bạn sử dụng ngôn ngữ lập trình nào để tính toán giá trị được mã hoá base64, đối với thông tin xác thực ứng dụng đã cho đó, kết quả được mã hoá base64 sẽ là: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Sau đó, bạn có thể thực hiện yêu cầu mã thông báo như sau:

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

Tiện ích curl sẽ tạo tiêu đề HTTP cơ bản cho bạn nếu bạn dùng tuỳ chọn -u. Đoạn mã sau tương đương với đoạn mã trên:

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

Các môi trường lập trình khác có thể có các lối tắt tương tự để tự động tạo tiêu đề được mã hoá base64.

Băm mã thông báo trong cơ sở dữ liệu

Để bảo vệ quyền truy cập vào OAuth và làm mới mã thông báo trong trường hợp xảy ra rò rỉ bảo mật cơ sở dữ liệu, bạn có thể bật tính năng tự động băm mã thông báo trong tổ chức của mình trên Edge. Khi tính năng này được bật, Edge sẽ tự động tạo một phiên bản băm của mã truy cập và làm mới OAuth mới tạo bằng thuật toán mà bạn chỉ định. (Thông tin về tính năng băm hàng loạt mã thông báo hiện có.) Các mã thông báo chưa băm được dùng trong các lệnh gọi API và Edge xác thực các mã này dựa trên các phiên bản đã băm trong cơ sở dữ liệu.

Các tài sản cấp tổ chức sau đây kiểm soát hoạt động băm mã thông báo OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Nếu bạn hiện có mã thông báo đã băm và muốn giữ lại các mã đó cho đến khi hết hạn, hãy thiết lập các thuộc tính sau trong tổ chức của bạn, trong đó thuật toán băm khớp với thuật toán hiện có (ví dụ: SHA1, giá trị mặc định cũ của Edge). Nếu mã thông báo chưa được băm, hãy sử dụng PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Nếu bạn là khách hàng sử dụng nền tảng đám mây ở Edge, hãy liên hệ với Nhóm hỗ trợ Apigee để thiết lập các tài sản này cho tổ chức của mình và băm hàng loạt mã thông báo hiện có (không bắt buộc).

Chủ đề có liên quan