Chính sách OAuthV2

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

Nội dung

OAuthV2 là một chính sách nhiều khía cạnh để thực hiện các thao tác loại cấp quyền OAuth 2.0. Đây là chính sách chính dùng để định cấu hình điểm cuối OAuth 2.0 trên Apigee Edge.

Mẹo: Nếu bạn muốn tìm hiểu thêm về OAuth trên Apigee Edge, hãy xem trang chủ OAuth. Công cụ này cung cấp đường liên kết đến tài nguyên, mẫu, video và hơn thế nữa. Xem hướng dẫn nâng cao Mẫu OAuth trên GitHub để minh hoạ rõ cách chính sách này được sử dụng trong một quá trình .

Mẫu

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

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

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

Xem thêm "Mã hóa cơ bản thông tin xác thực".

Tài liệu tham khảo phần tử

Tài liệu tham khảo chính sách này mô tả các thành phần và thuộc tính của chính sách OAuthV2.

Chính sách mẫu hiển thị bên dưới là một trong nhiều cấu hình có thể có. Mẫu này cho thấy Đã định cấu hình chính sách OAuthV2 cho hoạt động GenerateAccessToken. Trong đó có các trường bắt buộc và các phần tử không bắt buộc. Hãy tham khảo nội dung mô tả về phần tử trong phần này để biết thông tin chi tiết.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> thuộc tính

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

&lt;DisplayName&gt; phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>

&lt;AccessToken&gt; phần tử

<AccessToken>request.header.access_token</AccessToken>

Theo mặc định, VerifyAccessToken dự kiến gửi mã truy cập trong Authorization . Bạn có thể thay đổi giá trị mặc định đó bằng phần tử này. Cho ví dụ request.queryparam.access_token cho biết mã truy cập phải hiển thị dưới dạng tham số truy vấn có tên access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

&lt;AccessTokenPrefix&gt; phần tử

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Theo mặc định, VerifyAccessToken yêu cầu gửi mã thông báo truy cập trong tiêu đề Uỷ quyền làm mã thông báo Bearer. Ví dụ:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Hiện tại, Bearer là tiền tố duy nhất được hỗ trợ.

&lt;AppEndUser&gt; phần tử

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Trong trường hợp mã nhận dạng người dùng cuối của ứng dụng phải được gửi đến máy chủ uỷ quyền, phần tử này sẽ cho phép bạn chỉ định nơi Edge sẽ tìm mã nhận dạng người dùng cuối. Ví dụ: bản ghi có thể được gửi dưới dạng truy vấn hoặc trong tiêu đề HTTP.

Ví dụ: request.queryparam.app_enduser cho biết rằng AppEndUser phải xuất hiện dưới dạng tham số truy vấn, vì ví dụ: ?app_enduser=ntesla@theramin.com. Để yêu cầu AppEndUser trong một HTTP đầu trang, ví dụ: đặt giá trị này thành request.header.app_enduser.

Khi cung cấp chế độ cài đặt này, bạn có thể thêm mã nhận dạng người dùng cuối của ứng dụng vào mã truy cập. Chiến dịch này rất hữu ích nếu bạn muốn có thể truy xuất hoặc thu hồi mã truy cập OAuth 2.0 mã nhận dạng người dùng. Để biết thêm thông tin, hãy xem Bật tính năng truy xuất và thu hồi mã truy cập OAuth 2.0 theo mã nhận dạng người dùng cuối, mã ứng dụng hoặc cả hai.

&lt;Attributes/Attribute&gt;

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Sử dụng phần tử này để thêm các thuộc tính tuỳ chỉnh vào mã truy cập hoặc mã uỷ quyền. Cho ví dụ: bạn nên nhúng mã nhận dạng người dùng hoặc giá trị nhận dạng phiên vào một mã truy cập có thể được trích xuất và kiểm tra trong thời gian chạy.

Phần tử này cho phép bạn chỉ định một giá trị trong một biến luồng hoặc từ một chuỗi cố định. Nếu bạn chỉ định cả biến và chuỗi, thì giá trị được chỉ định trong biến luồng sẽ được sử dụng. Nếu không thể phân giải biến, khi đó chuỗi sẽ là mặc định.

Để biết thêm thông tin về cách sử dụng phần tử này, hãy xem bài viết Tuỳ chỉnh mã thông báo và Mã uỷ quyền.

Hiển thị hoặc ẩn các thuộc tính tuỳ chỉnh trong phản hồi

Hãy nhớ rằng nếu bạn đặt phần tử GenerateResponse của chính sách này thành true, bản trình bày JSON đầy đủ của mã thông báo sẽ được trả về trong phản hồi, bao gồm bất kỳ tuỳ chỉnh mà bạn đã đặt. Trong một số trường hợp, bạn có thể muốn ẩn một số hoặc tất cả trong phản hồi để các thuộc tính đó không hiển thị với các ứng dụng khách.

Theo mặc định, các thuộc tính tuỳ chỉnh sẽ xuất hiện trong phản hồi. Nếu muốn ẩn quảng cáo, bạn có thể đặt thông số display thành false. Ví dụ:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Giá trị của thuộc tính display không duy trì. Giả sử bạn tạo một mã truy cập có các thuộc tính tuỳ chỉnh mà bạn muốn ẩn trong tạo phản hồi. Việc thiết lập display=false sẽ giúp bạn đạt được mục tiêu đó. Tuy nhiên, nếu một người dùng mới mã truy cập được tạo sau đó bằng mã làm mới, các thuộc tính tuỳ chỉnh ban đầu từ mã truy cập sẽ xuất hiện trong phản hồi mã làm mới. Lý do là vì Edge không nhớ điều đó ban đầu, thuộc tính display được đặt thành false trong chính sách tạo mã truy cập--tuỳ chỉnh chỉ là một phần trong siêu dữ liệu của mã truy cập.

Bạn sẽ thấy hành vi tương tự nếu bạn thêm các thuộc tính tùy chỉnh vào mã uỷ quyền--khi một mã truy cập được tạo bằng mã đó, các thuộc tính tuỳ chỉnh đó sẽ xuất hiện trong mã truy cập của bạn. Xin nhắc lại, đây có thể không phải là hành vi bạn mong muốn.

Để ẩn các mục tuỳ chỉnh trong những trường hợp này, bạn có các lựa chọn sau:

• Đặt lại rõ ràng các thuộc tính tuỳ chỉnh trong chính sách về mã làm mới và đặt màn hình của các thuộc tính đó thành false. Trong trường hợp này, bạn có thể cần phải truy xuất các giá trị tuỳ chỉnh ban đầu từ các mã truy cập bằng chính sách GetOAuthV2Info.
• Sử dụng chính sách JavaScript hậu xử lý để trích xuất các thuộc tính tuỳ chỉnh mà bạn không muốn xem trong phản hồi.

Hãy xem thêm bài viết Tuỳ chỉnh mã thông báo và Mã uỷ quyền.

&lt;ClientId&gt; phần tử

<ClientId>request.formparam.client_id</ClientId>

Trong một số trường hợp, ứng dụng khách phải gửi mã ứng dụng khách đến máy chủ uỷ quyền. Chiến dịch này cho phép bạn chỉ định nơi Edge sẽ tìm ID ứng dụng khách. Chỉ số hợp lệ vị trí mà bạn có thể đặt là vị trí mặc định vị trí, biến luồng request.formparam.client_id. Đang cài đặt ClientId với bất kỳ biến nào khác không được hỗ trợ. Xem thêm phần Yêu cầu mã truy cập và uỷ quyền mã.

&lt;Code&gt; phần tử

<Code>request.queryparam.code</Code>

Trong quy trình loại cấp uỷ quyền, khách hàng phải gửi mã uỷ quyền cho máy chủ uỷ quyền (Apigee Edge). Phần tử này cho phép bạn chỉ định nơi Edge sẽ tìm kiếm mã uỷ quyền. Ví dụ: mã có thể được gửi dưới dạng tham số truy vấn, tiêu đề HTTP hoặc biểu mẫu tham số (mặc định).

Biến request.queryparam.auth_code cho biết rằng mã uỷ quyền phải hiển thị dưới dạng tham số truy vấn, giống như đối với ví dụ: ?auth_code=AfGlvs9. Để yêu cầu mã uỷ quyền trong HTTP đầu trang, ví dụ: đặt giá trị này thành request.header.auth_code. Xem thêm Yêu cầu mã truy cập và mã uỷ quyền.

&lt;ExpiresIn&gt; phần tử

<ExpiresIn>10000</ExpiresIn> 

Áp dụng thời gian hết hạn của mã truy cập và mã uỷ quyền tính bằng mili giây. (Đối với mã làm mới, hãy sử dụng <RefreshTokenExpiresIn>.) Giá trị thời gian hết hạn là giá trị do hệ thống tạo cùng với giá trị <ExpiresIn>. Nếu <ExpiresIn> được đặt thành -1, mã thông báo hoặc mã sẽ hết hạn theo thời hạn tối đa của mã truy cập OAuth. Nếu bạn không chỉ định <ExpiresIn>, hệ thống sẽ áp dụng một giá trị mặc định được định cấu hình ở cấp hệ thống.

Thời gian hết hạn cũng có thể được đặt trong thời gian chạy bằng cách sử dụng giá trị mặc định, được cố định giá trị trong mã hoặc bằng khi tham chiếu đến một biến luồng. Ví dụ: bạn có thể lưu trữ giá trị thời hạn của mã thông báo trong một khoá-giá trị ánh xạ, truy xuất dữ liệu, gán biến cho một biến và tham chiếu đến biến đó trong chính sách. Ví dụ: kvm.oauth.expires_in.

Với Apigee Edge dành cho Cloud Public, Edge giúp bạn các thực thể sau trong bộ nhớ đệm trong tối thiểu 180 giây sau khi các thực thể được truy cập.

• Mã truy cập OAuth. Tức là mã thông báo bị thu hồi vẫn có thể thành công trong tối đa 3 mã phút cho đến khi giới hạn bộ nhớ đệm hết hạn.
• Thực thể Dịch vụ quản lý khoá (KMS) (Ứng dụng, Nhà phát triển, Sản phẩm API).
• Thuộc tính tuỳ chỉnh trên mã thông báo OAuth và thực thể KMS.

Đoạn văn sau đây cũng chỉ định một biến luồng và một giá trị mặc định. Lưu ý rằng quy trình giá trị của biến được ưu tiên hơn giá trị mặc định đã chỉ định.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge không hỗ trợ cách buộc một mã thông báo hết hạn sau khi tạo. Nếu bạn cần buộc mã thông báo hết hạn (ví dụ: dựa trên một điều kiện), một giải pháp khả thi là được mô tả trong bài đăng này trên thẻ Cộng đồng Apigee.

Theo mặc định, những mã truy cập đã hết hạn sẽ bị xoá hoàn toàn khỏi Apigee Hệ thống Edge sẽ tự động cập nhật sau 3 ngày kể từ khi hết hạn. Xem thêm bài viết Yêu cầu xoá quyền truy cập mã thông báo

Đám mây riêng tư: Đối với việc cài đặt Edge dành cho Đám mây riêng tư, lựa chọn mặc định do thuộc tính conf_keymanagement_oauth_auth_code_expiry_time_in_millis đặt. Cách đặt tài sản này:

1. Mở tệp message-processor.properties trong trình chỉnh sửa. Nếu tệp không tồn tại, hãy tạo tệp:

   vi /opt/apigee/customer/application/message-processor.properties

2. Đặt thuộc tính như mong muốn:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Đảm bảo rằng tệp thuộc tính thuộc sở hữu của "apigee" người dùng:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Khởi động lại Trình xử lý thư.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

&lt;ExternalAccessToken&gt; phần tử

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Cho Apigee Edge biết nơi tìm mã truy cập bên ngoài (mã truy cập không được tạo bởi Apigee Edge).

Biến request.queryparam.external_access_token cho biết rằng mã truy cập bên ngoài sẽ xuất hiện dưới dạng tham số truy vấn, như đối với ví dụ: ?external_access_token=12345678. Để yêu cầu mã truy cập bên ngoài trong tiêu đề HTTP, ví dụ: đặt giá trị này thành request.header.external_access_token. Xem thêm bài viết Sử dụng OAuth của bên thứ ba Mã thông báo.

&lt;ExternalAuthorization&gt; phần tử

<ExternalAuthorization>true</ExternalAuthorization>

Nếu phần tử này sai hoặc không có, thì Edge sẽ xác thực client_id và client_secret thường nhắm đến cửa hàng uỷ quyền Apigee Edge. Sử dụng phần tử này khi bạn muốn làm việc với mã thông báo OAuth của bên thứ ba. Để biết chi tiết về cách sử dụng phần tử này, hãy xem phần Sử dụng OAuth của bên thứ ba Mã thông báo.

&lt;ExternalAuthorizationCode&gt; phần tử

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Cho Apigee Edge biết nơi tìm mã xác thực bên ngoài (mã xác thực không được tạo bởi Apigee Edge).

Biến request.queryparam.external_auth_code cho biết rằng mã xác thực bên ngoài phải hiển thị dưới dạng tham số truy vấn, như đối với ví dụ: ?external_auth_code=12345678. Để yêu cầu xác thực bên ngoài mã trong tiêu đề HTTP, ví dụ: đặt giá trị này thành request.header.external_auth_code. Xem thêm bài viết Sử dụng OAuth của bên thứ ba Mã thông báo.

&lt;ExternalRefreshToken&gt; phần tử

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Cho Apigee Edge biết nơi tìm mã làm mới bên ngoài (mã làm mới không được tạo bởi Apigee Edge).

Biến request.queryparam.external_refresh_token cho biết rằng mã làm mới bên ngoài sẽ xuất hiện dưới dạng tham số truy vấn, như đối với ví dụ: ?external_refresh_token=12345678. Để yêu cầu mã làm mới bên ngoài trong tiêu đề HTTP, ví dụ: đặt giá trị này thành request.header.external_refresh_token. Xem thêm bài viết Sử dụng OAuth của bên thứ ba Mã thông báo.

&lt;GenerateResponse&gt; phần tử

<GenerateResponse enabled='true'/>

Nếu bạn đặt thành true, chính sách này sẽ tạo và trả về một phản hồi. Ví dụ: đối với CreateAccessToken, phản hồi có thể có dạng như sau:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Nếu giá trị là false, thì sẽ không có phản hồi nào được gửi. Thay vào đó, một nhóm biến luồng được điền sẵn có các giá trị liên quan đến chức năng của chính sách. Ví dụ: biến luồng có tên là oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code được điền sẵn thông tin mã uỷ quyền được tạo. Xin lưu ý rằng expires_in được biểu thị bằng giây trong giá trị của bạn.

&lt;GenerateErrorResponse&gt; phần tử

<GenerateErrorResponse enabled='true'/>

Nếu bạn đặt thành true, chính sách này sẽ tạo và trả về phản hồi nếu Thuộc tính ContinueOnError được đặt thành true. Nếu false (mặc định), không đã gửi phản hồi. Thay vào đó, một nhóm biến luồng được điền sẵn các giá trị liên quan đến chức năng của chính sách.

&lt;GrantType&gt;

<GrantType>request.queryparam.grant_type</GrantType>

Cho chính sách biết nơi tìm thông số loại cấp quyền được chuyển trong một yêu cầu. Theo thông số OAuth 2.0, loại cấp quyền phải được cung cấp cùng với yêu cầu về mã truy cập và mã uỷ quyền. Biến có thể là tiêu đề, tham số truy vấn hoặc tham số biểu mẫu (mặc định).

Ví dụ: request.queryparam.grant_type cho biết rằng Mật khẩu sẽ xuất hiện dưới dạng tham số truy vấn, chẳng hạn như ?grant_type=password. Ví dụ: để yêu cầu loại cấp quyền trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.grant_type. Xem thêm phần Yêu cầu mã truy cập và uỷ quyền mã.

&lt;Operation&gt; phần tử

<Operation>GenerateAuthorizationCode</Operation>

Chính sách này đã thực thi thao tác OAuth 2.0.

&lt;PassWord&gt; phần tử

<PassWord>request.queryparam.password</PassWord>

Phần tử này được dùng với chỉ loại cấp mật khẩu. Bằng loại cấp mật khẩu, thông tin xác thực của người dùng (mật khẩu và tên người dùng) phải được cung cấp cho Chính sách OAuthV2. Các phần tử <PassWord> và <UserName> là dùng để chỉ định những biến mà Edge có thể tìm thấy các giá trị này. Nếu các yếu tố này không được chỉ định, chính sách yêu cầu tìm các giá trị (theo mặc định) trong các tham số biểu mẫu có tên là username và password. Nếu không tìm thấy giá trị, chính sách sẽ gửi thông báo lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu đến bất kỳ biến luồng chứa thông tin xác thực.

Ví dụ: bạn có thể chuyển mật khẩu vào yêu cầu mã thông báo bằng cách sử dụng tham số truy vấn và đặt như sau: <PassWord>request.queryparam.password</PassWord>. Đến yêu cầu mật khẩu trong tiêu đề HTTP, hãy đặt giá trị này đến request.header.password.

Chính sách OAuthV2 không thực hiện bất kỳ hành động nào khác đối với các giá trị thông tin xác thực này; Edge đơn giản là xác minh rằng chúng có mặt. Nhà phát triển API có quyền truy xuất yêu cầu giá trị và gửi mã đó đến một nhà cung cấp danh tính trước khi thực thi chính sách tạo mã thông báo.

Xem thêm bài viết Yêu cầu mã truy cập và mã uỷ quyền.

&lt;RedirectUri&gt; phần tử

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Chỉ định vị trí Edge sẽ tìm kiếm tham số redirect_uri trong của bạn.

Giới thiệu về URI chuyển hướng

URI chuyển hướng được dùng cùng với mã uỷ quyền và các loại cấp quyền ngầm ẩn. Lệnh chuyển hướng URI cho máy chủ uỷ quyền (Edge) biết nơi gửi mã uỷ quyền (đối với mã xác thực) cấp quyền) hoặc mã truy cập (đối với loại cấp quyền ngầm ẩn). Bạn cần phải hiểu rõ khi nào tham số là bắt buộc, khi nào là không bắt buộc và cách sử dụng tham số:

• (bắt buộc) Nếu URL gọi lại được đăng ký với ứng dụng của nhà phát triển được liên kết với khoá ứng dụng của yêu cầu và nếu redirect_uri có trong yêu cầu, thì hai số đó phải khớp chính xác. Nếu không khớp, hệ thống sẽ trả về lỗi. Để biết thông tin về cách đăng ký ứng dụng của nhà phát triển trên Edge và chỉ định URL gọi lại, hãy xem bài viết Đăng ký ứng dụng và quản lý API khoá.

• (không bắt buộc) Nếu một URL gọi lại đã được đăng ký và thiếu redirect_uri từ yêu cầu, thì Edge sẽ chuyển hướng đến URL gọi lại đã đăng ký.
• (bắt buộc) Nếu URL gọi lại chưa được đăng ký, thì redirect_uri sẽ là bắt buộc. Xin lưu ý rằng trong trường hợp này, Edge sẽ chấp nhận BẤT KỲ URL nào. Trường hợp này có thể đưa ra vấn đề bảo mật, và do đó chỉ nên được sử dụng với khách hàng đáng tin cậy của chúng tôi. Nếu ứng dụng khách không đáng tin cậy thì phương pháp hay nhất là luôn yêu cầu đăng ký một URL gọi lại.

Bạn có thể gửi tham số này trong một tham số truy vấn hoặc trong một tiêu đề. Chiến lược phát hành đĩa đơn biến request.queryparam.redirect_uri cho biết RedirectUri sẽ xuất hiện dưới dạng tham số truy vấn, vì ví dụ: ?redirect_uri=login.myapp.com. Để yêu cầu RedirectUri trong HTTP đầu trang, ví dụ: đặt giá trị này thành request.header.redirect_uri. Xem Yêu cầu mã truy cập và mã uỷ quyền.

&lt;RefreshToken&gt; phần tử

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Khi yêu cầu mã làm mới bằng mã làm mới, bạn phải cung cấp mã làm mới trong yêu cầu. Phần tử này cho phép bạn chỉ định nơi Edge sẽ tìm mã làm mới. Cho ví dụ: mã có thể được gửi dưới dạng tham số truy vấn, tiêu đề HTTP hoặc tham số biểu mẫu (mặc định).

Biến request.queryparam.refreshtoken cho biết quá trình làm mới mã thông báo sẽ được hiển thị dưới dạng tham số truy vấn, vì ví dụ: ?refresh_token=login.myapp.com. Để yêu cầu RefreshToken trong HTTP đầu trang, ví dụ: đặt giá trị này thành request.header.refresh_token. Xem Yêu cầu mã truy cập và mã uỷ quyền.

&lt;RefreshTokenExpiresIn&gt; phần tử

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Thực thi thời gian hết hạn của mã thông báo làm mới tính bằng mili giây. Giá trị thời gian hết hạn là một hệ thống giá trị đã tạo cộng với giá trị <RefreshTokenExpiresIn>. Nếu <RefreshTokenExpiresIn> được đặt thành -1, mã làm mới hết hạn theo thời hạn tối đa của mã làm mới OAuth. Nếu không chỉ định <RefreshTokenExpiresIn>, hệ thống sẽ áp dụng một giá trị mặc định được định cấu hình ở cấp hệ thống. Liên hệ với Bộ phận hỗ trợ Apigee Edge để biết thêm thông tin thông tin về các chế độ cài đặt mặc định của hệ thống.

Thời gian hết hạn cũng có thể được đặt trong thời gian chạy bằng cách sử dụng giá trị mặc định, được cố định giá trị trong mã hoặc bằng khi tham chiếu đến một biến luồng. Ví dụ: bạn có thể lưu trữ giá trị thời hạn của mã thông báo trong một khoá-giá trị ánh xạ, truy xuất dữ liệu, gán biến cho một biến và tham chiếu đến biến đó trong chính sách. Cho ví dụ: kvm.oauth.expires_in.

Đoạn văn sau đây cũng chỉ định một biến luồng và một giá trị mặc định. Lưu ý rằng quy trình giá trị của biến được ưu tiên hơn giá trị mặc định đã chỉ định.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Đám mây riêng tư: Đối với việc cài đặt Edge dành cho Đám mây riêng tư, lựa chọn mặc định do thuộc tính conf_keymanagement_oauth_refresh_token_expiry_time_in_millis đặt. Cách đặt tài sản này:

1. Mở tệp message-processor.properties trong trình chỉnh sửa. Nếu tệp không tồn tại, hãy tạo tệp:

   vi /opt/apigee/customer/application/message-processor.properties

2. Đặt thuộc tính như mong muốn:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Đảm bảo rằng tệp thuộc tính thuộc sở hữu của "apigee" người dùng:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Khởi động lại Trình xử lý thư.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

&lt;ResponseType&gt; phần tử

<ResponseType>request.queryparam.response_type</ResponseType>

Phần tử này thông báo cho Edge biết loại cấp quyền mà ứng dụng khách đang yêu cầu. Chỉ dùng với mã uỷ quyền và các luồng loại cấp quyền ngầm ẩn.

Theo mặc định, Edge sẽ tìm giá trị loại phản hồi trong một truy vấn response_type . Nếu bạn muốn ghi đè chế độ mặc định này, hãy sử dụng <ResponseType> thành phần tử định cấu hình biến luồng chứa giá trị loại phản hồi. Ví dụ: nếu bạn đặt thuộc tính này với request.header.response_type, Edge sẽ tìm loại phản hồi được chuyển vào tiêu đề yêu cầu. Xem thêm phần Yêu cầu mã truy cập và uỷ quyền mã.

&lt;ReuseRefreshToken&gt; phần tử

<ReuseRefreshToken>true</ReuseRefreshToken>

Khi bạn đặt thành true, mã làm mới hiện có sẽ được sử dụng lại cho đến khi hết hạn. Nếu false thân mến, mã làm mới mới do Apigee Edge cấp khi mã làm mới hợp lệ là trình bày.

&lt;Scope&gt; phần tử

<Scope>request.queryparam.scope</Scope>

Nếu phần tử này hiện diện ở một trong các GenerateAccessToken hoặc Generateuỷ quyền chính sách này, trường này được dùng để chỉ định phạm vi cấp mã thông báo hoặc mã. Các giá trị này là thường được chuyển đến chính sách trong yêu cầu từ ứng dụng khách. Bạn có thể định cấu hình phần tử này để lấy một biến luồng, cho phép bạn chọn cách truyền phạm vi trong một yêu cầu. Trong trong ví dụ sau, request.queryparam.scope cho biết phạm vi phải xuất hiện dưới dạng tham số truy vấn, ví dụ như ?scope=READ. Để yêu cầu phạm vi trong tiêu đề HTTP. Ví dụ: đặt giá trị này thành request.header.scope.

Nếu phần tử này xuất hiện trong một "VerifyAccessToken" chính sách, sau đó nó được dùng để chỉ định mà chính sách sẽ thực thi. Trong loại chính sách này, giá trị phải được "mã hoá cứng" phạm vi name -- bạn không thể sử dụng biến. Ví dụ:

<Scope>A B</Scope>

Xem thêm bài viết Làm việc với OAuth2 phạm vi và Yêu cầu mã truy cập và mã uỷ quyền.

&lt;State&gt; phần tử

<State>request.queryparam.state</State>

Trong trường hợp ứng dụng khách phải gửi thông tin trạng thái đến máy chủ uỷ quyền, phần tử này cho phép bạn chỉ định nơi Edge sẽ tìm kiếm các giá trị trạng thái. Ví dụ: việc này có thể sẽ được gửi dưới dạng tham số truy vấn hoặc trong tiêu đề HTTP. Giá trị trạng thái thường được dùng như biện pháp bảo mật để ngăn chặn các cuộc tấn công CSRF.

Ví dụ: request.queryparam.state cho biết trạng thái phải là hiển thị dưới dạng tham số truy vấn, ví dụ như ?state=HjoiuKJH32. Để yêu cầu trạng thái trong tiêu đề HTTP, ví dụ: đặt giá trị này thành request.header.state. Xem thêm Xem thêm phần Yêu cầu mã truy cập và uỷ quyền mã.

&lt;StoreToken&gt; phần tử

 <StoreToken>true</StoreToken> 

Đặt phần tử này thành true khi <ExternalAuthorization> là phần tử true. Phần tử <StoreToken> yêu cầu Apigee Edge và lưu trữ mã truy cập bên ngoài. Nếu không, dữ liệu đó sẽ không được duy trì.

&lt;SupportedGrantTypes&gt;/&lt;GrantType&gt; phần tử

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Chỉ định các loại quyền mà điểm cuối của mã thông báo OAuth trên Apigee Edge hỗ trợ. Một điểm cuối có thể hỗ trợ nhiều loại quyền cấp (nghĩa là bạn có thể định cấu hình một điểm cuối duy nhất để phân phối quyền truy cập mã thông báo cho nhiều loại cấp quyền.) Để biết thêm thông tin về các điểm cuối, hãy xem bài viết Tìm hiểu về OAuth điểm cuối. Loại cấp quyền được chuyển vào yêu cầu mã thông báo trong grant_type .

Nếu bạn không chỉ định loại tài trợ được hỗ trợ nào, thì các loại tài trợ được phép duy nhất là authorization_code và implicit. Hãy xem thêm phần tử &lt;GrantType&gt; (một phần tử cấp cao hơn được dùng để chỉ định vị trí mà Apigee Edge sẽ tìm thông số grant_type được truyền vào một yêu cầu của máy khách. Edge sẽ đảm bảo rằng giá trị của tham số grant_type khớp với một trong các loại tài trợ được hỗ trợ).

&lt;Tokens&gt;/&lt;Token&gt; phần tử

Được dùng với các hoạt động ValidateToken và InvalidateToken. Hãy xem thêm phần Phê duyệt và thu hồi mã truy cập. <Token> là phần tử xác định biến luồng giúp xác định nguồn của mã thông báo cần thu hồi. Nếu nhà phát triển dự kiến sẽ gửi mã truy cập dưới dạng tham số truy vấn có tên access_token, ví dụ: sử dụng request.queryparam.access_token.

&lt;UserName&gt; phần tử

<UserName>request.queryparam.user_name</UserName>

Phần tử này được dùng với chỉ loại cấp mật khẩu. Bằng loại cấp mật khẩu, thông tin xác thực của người dùng (mật khẩu và tên người dùng) phải được cung cấp cho Chính sách OAuthV2. Các phần tử <PassWord> và <UserName> là dùng để chỉ định những biến mà Edge có thể tìm thấy các giá trị này. Nếu các yếu tố này không được chỉ định, chính sách yêu cầu tìm các giá trị (theo mặc định) trong các tham số biểu mẫu có tên là username và password. Nếu không tìm thấy giá trị, chính sách sẽ gửi thông báo lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu đến bất kỳ biến luồng chứa thông tin xác thực.

Ví dụ: bạn có thể chuyển tên người dùng vào tham số truy vấn và đặt tham số Phần tử <UserName> như sau: <UserName>request.queryparam.username</UserName>.Để yêu cầu tên người dùng trong tiêu đề HTTP, hãy đặt giá trị này đến request.header.username.

Chính sách OAuthV2 không thực hiện bất kỳ hành động nào khác đối với các giá trị thông tin xác thực này; Edge đơn giản là xác minh rằng chúng có mặt. Nhà phát triển API có quyền truy xuất yêu cầu giá trị và gửi mã đó đến một nhà cung cấp danh tính trước khi thực thi chính sách tạo mã thông báo.

Xem thêm bài viết Yêu cầu mã truy cập và mã uỷ quyền.

Xác minh quyền truy cập mã thông báo

Sau khi thiết lập điểm cuối của mã thông báo cho proxy API, chính sách OAuthV2 tương ứng sẽ chỉ định toán tử VerifyAccessToken được đính kèm với Luồng cho thấy tài nguyên được bảo vệ.

Ví dụ: để đảm bảo rằng tất cả yêu cầu đối với một API đều được uỷ quyền, chính sách sau thực thi việc xác minh mã truy cập:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Chính sách này được đính kèm với tài nguyên API cần được bảo vệ. Để đảm bảo rằng tất cả các yêu cầu đến API đã được xác minh, hãy đính kèm chính sách này vào quy trình PreFlow của yêu cầu ProxyEndpoint như sau:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Bạn có thể sử dụng các phần tử tuỳ chọn sau để ghi đè chế độ cài đặt mặc định cho phần tử Hoạt động VerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

Xem thêm bài viết Xác minh quyền truy cập và Yêu cầu mã truy cập và mã uỷ quyền.

Chỉ định vị trí của biến yêu cầu

Đối với mỗi loại quyền tài trợ, chính sách đưa ra các giả định về vị trí hoặc thông tin cần thiết trong thông báo yêu cầu. Những giả định này dựa trên quy cách của OAuth 2.0. Nếu ứng dụng của bạn cần đi chệch khỏi quy cách OAuth 2.0, thì bạn có thể chỉ định các vị trí mong muốn cho từng thông số. Ví dụ: khi xử lý mã uỷ quyền, bạn có thể chỉ định vị trí của mã uỷ quyền, mã ứng dụng khách, URI chuyển hướng và phạm vi. Các toán tử này có thể được chỉ định là Tiêu đề HTTP, tham số truy vấn hoặc tham số biểu mẫu.

Ví dụ bên dưới minh hoạ cách bạn có thể chỉ định vị trí của mã uỷ quyền bắt buộc tham số làm tiêu đề HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Hoặc, nếu cần thiết để hỗ trợ cơ sở ứng dụng khách hàng của mình, bạn có thể kết hợp và so khớp tiêu đề và truy vấn thông số:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Bạn chỉ có thể thiết lập một vị trí cho mỗi thông số.

Biến luồng

Các biến luồng được xác định trong bảng này được điền sẵn khi các chính sách OAuth tương ứng được được thực thi nên có sẵn cho các chính sách hoặc ứng dụng khác thực thi trong proxy API luồng.

Thao tác VerifyAccessToken

Thao tác VerifyAccessToken thực thi, một số lượng lớn các biến luồng được điền sẵn trong ngữ cảnh thực thi của proxy. Các biến này cung cấp cho bạn các thuộc tính liên quan đến quyền truy cập mã, ứng dụng của nhà phát triển, nhà phát triển và công ty. Bạn có thể dùng chính sách AttributionMessage hoặc JavaScript, ví dụ: để đọc bất kỳ biến nào trong số này và sử dụng chúng nếu cần sau này trong quy trình. Các các biến cũng có thể hữu ích cho mục đích gỡ lỗi.

Biến dành riêng cho mã thông báo

Biến dành riêng cho ứng dụng

Các biến này liên quan đến Ứng dụng của nhà phát triển được liên kết với mã thông báo.

Biến dành riêng cho nhà phát triển

Nếu app.appType là "Company" thì các thuộc tính của công ty sẽ được điền và nếu app.appType là "Nhà phát triển", sau đó các thuộc tính nhà phát triển sẽ được điền sẵn.

Biến dành riêng cho công ty

Nếu app.appType là "Company" thì các thuộc tính của công ty sẽ được điền và nếu app.appType là "Nhà phát triển", sau đó các thuộc tính nhà phát triển sẽ được điền sẵn.

GenerateAuthorizationCode hoạt động

Các biến này được đặt khi hoạt động GenerateLicenseCode thực thi thành công:

Tiền tố: oauthv2authcode.{policy_name}.{variable_name}

Ví dụ: oauthv2authcode.GenerateCodePolicy.code

CreateAccessToken và Hoạt động RefreshAccessToken

Các biến này được đặt khi thực thi các hoạt động GenerateAccessToken và RefreshAccessToken thành công. Lưu ý rằng các biến của mã làm mới không áp dụng cho việc cấp thông tin xác thực ứng dụng cho luồng.

Tiền tố: oauthv2accesstoken.{policy_name}.{variable_name}

Ví dụ: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Các biến này được đặt khi thực thi hoạt động GenerateAccessTokenlined thành công đối với quy trình loại cấp quyền ngầm ẩn.

Tiền tố: oauthv2accesstoken.{policy_name}.{variable_name}

Ví dụ: oauthv2accesstoken.RefreshTokenPolicy.access_token

Tham chiếu lỗi

Phần này mô tả các mã lỗi và thông báo lỗi được trả về cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi chính sách này thực thi.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy có chứa chính sách này.

Biến lỗi

Các biến này được đặt khi chính sách này kích hoạt lỗi trong thời gian chạy.

Ví dụ về phản hồi khi gặp lỗi

Những phản hồi này sẽ được gửi lại ứng dụng khách nếu <GenerateResponse> là phần tử true.

Nếu giá trị <GenerateResponse> là true (đúng) thì chính sách sẽ trả về lỗi ở định dạng này cho các thao tác tạo mã thông báo và mã. Để xem danh sách đầy đủ, hãy xem Lỗi HTTP của OAuth tham chiếu phản hồi.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Nếu giá trị <GenerateResponse> là true (đúng) thì chính sách sẽ trả về lỗi ở định dạng này để xác minh và xác thực thao tác. Để xem danh sách đầy đủ, hãy xem bài viết Lỗi HTTP OAuth tham chiếu phản hồi.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Ví dụ về quy tắc lỗi

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Giản đồ chính sách

Mỗi loại chính sách được xác định bằng một giản đồ XML (.xsd). Để tham khảo, chính sách giản đồ có trên GitHub.

Làm việc với OAuth mặc định cấu hình

Mỗi tổ chức (kể cả tổ chức dùng thử miễn phí) trên Apigee Edge đều được cấp phép bằng mã thông báo OAuth điểm cuối. Điểm cuối được định cấu hình sẵn với các chính sách trong proxy API có tên là OAuth. Bạn có thể bắt đầu sử dụng điểm cuối mã thông báo ngay khi tạo một tài khoản trên Apigee Edge. Cho chi tiết, hãy xem bài viết Tìm hiểu về OAuth điểm cuối.

Lấy mã truy cập xoá

Theo mặc định, mã thông báo OAuth2 sẽ bị xoá hoàn toàn khỏi hệ thống Apigee Edge sau 3 ngày (259200 giây) sau khi cả mã truy cập và mã làm mới (nếu có) đã hết hạn. Trong một số trường hợp, bạn có thể muốn thay đổi chế độ mặc định này. Ví dụ: bạn có thể muốn rút ngắn thời gian dọn dẹp xuống tiết kiệm dung lượng ổ đĩa nếu tạo một số lượng lớn mã thông báo.

Nếu đang sử dụng Edge dành cho đám mây riêng tư, bạn có thể thay đổi chế độ mặc định này bằng cách cài đặt tổ chức như được giải thích trong phần này. (Xóa hoàn toàn các mã thông báo đã hết hạn trong 3 ngày áp dụng cho Edge dành cho Private Cloud phiên bản 4.19.01 trở lên. Đối với các phiên bản trước đó, khoảng thời gian hoàn toàn mặc định là 180 ngày).

Cập nhật các tùy chọn cài đặt xóa hoàn toàn cho Edge Private Cloud 4.16.01 và các phiên bản mới hơn

Lưu ý: Chỉ mã thông báo được tạo sau khi các chế độ cài đặt này được tạo đã áp dụng đều bị ảnh hưởng; chế độ cài đặt này không áp dụng cho mã thông báo được tạo trước đó.

Đang cập nhật hoàn toàn bộ nhớ cài đặt cho Edge Private Cloud 4.15.07

Lưu ý: Chỉ những mã thông báo được tạo sau khi áp dụng các chế độ cài đặt này bị ảnh hưởng; chế độ cài đặt này không áp dụng cho mã thông báo được tạo trước đó.

Hành vi không tuân thủ RFC

Chính sách OAuthV2 trả về phản hồi mã thông báo chứa một số thuộc tính không tuân thủ RFC. Bảng sau đây trình bày các trang web không tuân thủ các thuộc tính do chính sách OAuthV2 trả về và các thuộc tính tuân thủ tương ứng.

Ngoài ra, phản hồi lỗi cho mã làm mới đã hết hạn khi grant_type = refresh_token là:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Tuy nhiên, phản hồi tuân thủ RFC là:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Chủ đề có liên quan

• Giới thiệu về OAuth 2.0