Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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.
Truy cập vào tài liệu Apigee X. thông tin

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

Mã mẫu

Để thuận tiện cho bạn, các chính sách và điểm cuối được thảo luận trong chủ đề này có trên GitHub trong dự án oauth-doc-examples trong kho lưu trữ api-platform-samples của Apigee. Bạn có thể triển khai mã mẫu và dùng thử các yêu cầu mẫu xuất hiện trong chủ đề này. Hãy xem tệp 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 cấp mã uỷ quyền. Để biết thông tin giới thiệu về các loại quyền sử dụng OAuth 2.0, hãy xem bài viết 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 phần nội dung yêu cầu (như minh hoạ 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, hãy xem Chính sách OAuthV2.

grant_type – Phải được đặt thành giá trị authorization_code.
code – Mã uỷ quyền nhận được từ điểm cuối /authorize (hoặc bất cứ tên nào bạn chọn). Để 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. Xem phần Yêu cầu mã uỷ quyền bên dưới. Xem thêm phần 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 – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng phạm vi OAuth2.

Xác thực

Bạn phải truyền Mã ứng dụng khách và Khoá bí mật của ứ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 các tham số biểu mẫu client_id và client_secret. Bạn sẽ nhận được các giá trị này từ một ứng dụng 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

Sau đâ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 GenerateAccessToken. Bạn phải định cấu hình chính sách này để hỗ trợ loại cấp authorization_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à chính sách GenerateAccessToken cơ bản được định cấu hình để chấp nhận loại cấp 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 <GenerateResponse> được bật, chính sách sẽ trả về một phản hồi JSON bao gồm mã truy cập, như minh hoạ bên dưới. Loại cấp phép authorization_code sẽ tạo mã truy cập và mã làm mới, vì vậy, phản hồi có thể trô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, chính sách này sẽ không trả về phản hồi. Thay vào đó, nó sẽ điền sẵn tập hợp các biến luồng sau bằng dữ liệu liên quan đến việc cấp mã truy cập.

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 thông tin đăng nhập của ứ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 cấp loại thông tin đăng nhập của ứng dụng khách. Để biết thông tin giới thiệu về các loại quyền sử dụng OAuth 2.0, hãy xem bài viết 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ố trong một tham số truy vấn. Để biết thông tin chi tiết, hãy 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 – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng phạm vi OAuth2.

Xác thực

Bạn phải truyền Mã ứng dụng khách và Khoá bí mật của ứ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 các tham số biểu mẫu client_id và client_secret. Bạn lấy các giá trị này từ ứng dụng nhà phát triển đã đăng ký liên kết với yêu cầu. Xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Điểm cuối mẫu

Sau đâ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 GenerateAccessToken. Bạn phải định cấu hình chính sách này để hỗ trợ loại cấp 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à chính sách GenerateAccessToken cơ bản được định cấu hình để chấp nhận loại cấp 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ạn bật <GenerateResponse>, chính sách này sẽ trả về một phản hồi JSON. Xin lưu ý rằng với loại cấp client_credentials, mã làm mới sẽ không được hỗ trợ. Chỉ mã truy cập được tạo. 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"
}

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 cấp loại thông tin đăng nhập (mật khẩu) mật khẩu của chủ sở hữu tài nguyên. Để biết thông tin giới thiệu về các loại quyền sử dụng 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ề loại cấp mật khẩu, bao gồm cả video dài 4 phút cho biết cách triển khai loại cấp mật khẩu, hãy xem phần Triển khai loại 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 phần nội dung yêu cầu (như minh hoạ 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, hãy 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 dựa trên một kho thông tin đăng nhập bằng chính sách LDAP hoặc JavaScript.

grant_type – Phải được đặt thành giá trị password.
username – 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 – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng phạm vi OAuth2.

Xác thực

Bạn phải truyền Mã ứng dụng khách và Khoá bí mật của ứ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 các tham số biểu mẫu client_id và client_secret. Bạn lấy các giá trị này từ ứng dụng nhà phát triển đã đăng ký liên kết với yêu cầu. Xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Điểm cuối mẫu

Sau đâ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 GenerateAccessToken. Bạn phải định cấu hình chính sách này để 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ạn bật <GenerateResponse>, chính sách này sẽ trả về một 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 tạo. 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"
}

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 ngầm

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 ngầm. Để biết thông tin giới thiệu về các loại quyền sử dụng OAuth 2.0, hãy xem bài viết 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, hãy 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 dựa trên một kho thông tin đăng nhập bằng lệnh gọi 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 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 ký ứng dụng nhà phát triển ứng dụng. Nếu bạn cung cấp một URL gọi lại tại quá trình đăng ký máy khách, 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 – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng phạm vi OAuth2.

Xác thực

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ã nhận dạng ứng dụng dưới dạng một tham số yêu cầu, như được giải thích tại đây.

Điểm cuối mẫu

Sau đâ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à chính sách GenerateAccessTokenImplicitGrant cơ bản, xử lý các yêu cầu về mã thông báo cho quy trình loại cấp ngầm định. Để 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 <GenerateResponse> được bật, chính sách 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 trỏ đến URL được chỉ định trong tham số redirect_uri và được thêm 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 ngầm ẩn không hỗ trợ mã làm mới. Ví dụ:

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

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'

trong đó chính sách OAuthV2 GenerateAuthorizationCode được đính kèm 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, hãy 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 nhà phát triển đã đăng ký.

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

redirect_uri – Nếu bạn chỉ định một URI gọi lại đầy đủ (không phải một phần) trong ứng dụng khách đã đăng ký, thì thông số này là không bắt buộc; nếu không, bạn phải chỉ định thông số này. Lệnh gọi lại là URL mà Edge gửi mã uỷ quyền mới tạo. Xem thêm phần Đăng ký ứng dụng và quản lý khoá API.
state – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng 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 khách đã đăng ký trong yêu cầu.

Điểm cuối mẫu

Dưới đây là một 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à chính sách GenerateAuthorizationCode cơ bả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.

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

Trả về

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

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

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ưu ý: Bạn cũng có thể đặt các thuộc tính tuỳ chỉnh trong chính sách OAuthV2. Các thuộc tính tuỳ chỉnh sẽ được trả về theo cùng một mẫu định dạng như các biến khác: oauthv2.{policy_name}.{attribute_name}. Khi bạn tạo mã truy cập từ mã uỷ quyền, mã truy cập sẽ kế thừa mọi biến tuỳ chỉnh được đặt trong mã uỷ quyền. Ngoài ra, hãy xem chính sách OAuthV2.

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

Mã làm mới là một thông tin đăng nhập mà 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 được trả về trong phản hồi khi bạn nhận được mã truy cập.

Lưu ý: Bạn không thể thêm/xoá/sửa đổi các thuộc tính hiện có trong mã truy cập trong quá trình thực hiện thao tác RefreshAccessToken. Các giá trị bên trong phần tử không được xử lý trong thao tác RefreshAccessToken. Sử dụng chính sách SetOAuthV2Info để cập nhật các thuộc tính.

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 các 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ư minh hoạ trong ví dụ trên. Để định cấu hình một vị trí thay thế cho các đầu vào này, bạn có thể sử dụng các phần tử <GrantType> và <RefreshToken> trong chính sách OAuthV2. Để biết thông tin chi tiết, hãy xem Chính sách OAuthV2.

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

state – Một chuỗi sẽ được gửi lại cùng với phản hồi. Thường được 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.
scope – Cho phép bạn lọc danh sách các sản phẩm API mà bạn có thể dùng mã thông báo đã phát hành. Để biết thông tin chi tiết về phạm vi, hãy xem phần Sử dụng phạm vi OAuth2.

Xác thực

client_id
client_secret

Bạn phải truyền Mã ứng dụng khách và Khoá bí mật của ứ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 các tham số biểu mẫu client_id và client_secret. 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, người dùng sẽ không cần xác thực lại.

Dưới đây là một 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à chính sách RefreshAccessToken cơ bản được định cấu hình để chấp nhận loại cấp 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 <GenerateResponse> được bật, chính sách sẽ trả về một phản hồi JSON chứa mã truy cập mới. Loại cấp phép refresh_token hỗ trợ tạo cả mã truy cập và mã 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"
}

Bạn nên biết rằng sau khi mã làm mới mới được tạo, mã làm mới ban đầu sẽ không còn hợp lệ nữa.

Bạn sẽ nhận được câu trả lời trên nếu <GenerateResponse> được đặt thành true. 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 đó, nó sẽ điền sẵn tập hợp các biến ngữ cảnh (luồng) sau bằng dữ liệu liên quan đến việc cấp mã truy cập.

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ã uỷ quyền, bạn nên truyền các giá trị client_id và client_secret dưới dạng tiêu đề Xác thực cơ bản qua HTTP, như mô tả trong IETF RFC 2617. Đây là một phương pháp hay và được quy cách OAuth 2.0 đề xuất. Để làm việc này, bạn phải mã hoá kết quả của việc kết hợp hai giá trị với nhau bằng dấu hai chấm phân tách chúng theo chuẩn base64.

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 giá trị được mã hoá base64, đối với những thông tin đăng nhập của khách hàng đã cho, kết quả được mã hoá base64 là: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Sau đó, bạn có thể đưa ra yêu cầu về 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ẽ thực sự tạo tiêu đề HTTP Basic cho bạn nếu bạn sử dụng tuỳ chọn -u. Sau đây tương đương với nội dung 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 phím 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 OAuth và mã làm mới trong trường hợp vi phạm bảo mật cơ sở dữ liệu, bạn có thể bật tính năng băm mã thông báo tự động trong tổ chức 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à mã làm mới OAuth mới được tạo bằng thuật toán mà bạn chỉ định. (Sau đây là thông tin về việc 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 lệnh gọi API và Edge xác thực các mã thông báo đó dựa trên các phiên bản đã băm trong cơ sở dữ liệu.

Các thuộc tính sau ở cấp tổ chức kiểm soát việc băm mã thông báo OAuth.

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

Nếu bạn có mã thông báo đã băm hiện có và muốn giữ lại cho đến khi mã thông báo hết hạn, hãy đặt 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, mặc định trước đây 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 Edge Cloud, hãy liên hệ với Nhóm hỗ trợ Apigee Edge để thiết lập các thuộc tính này cho tổ chức của bạn và tuỳ ý băm hàng loạt các mã thông báo hiện có.

Đám mây riêng: Đối với khách hàng sử dụng Edge for Private Cloud, hãy dùng lệnh gọi API sau đây bằng thông tin đăng nhập của quản trị viên hệ thống.

curl -u email:password -X PUT -H "Content-Type: application/xml" https://host:port/v1/o/{myorg} \
  -d '<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isOAuthTokenHashingEnabled">true</Property>
        <Property name="features.OAuthTokenHashingAlgorithm">SHA256</Property>
        <Property name="features.isOAuthTokenFallbackHashingEnabled">true</Property>
        <Property name="features.OAuthTokenFallbackHashingAlgorithm">SHA1</Property>
        <Property...(an existing property)
        <Property...(an existing property)
        <Property...(an existing property)
    </Properties>
  </Organization>'

Băm hàng loạt mã thông báo hiện có

Edge cũng cung cấp một tập lệnh mà bạn có thể chạy để băm các mã thông báo hiện có. Để biết thêm thông tin, hãy xem Hướng dẫn vận hành Edge cho Đám mây riêng phiên bản 4.15.07.00 trở lên.

Chủ đề có liên quan

Triển khai loại cấp thông tin đăng nhập của ứng dụng
Triển khai loại cấp mã uỷ quyền
Khoá học trực tuyến về bảo mật API (bao gồm cả OAuth)
Chính sách OAuthV2 – Có nhiều ví dụ cho thấy cách đưa ra yêu cầu cho máy chủ uỷ quyền và cách định cấu hình chính sách OAuthV2.