Chính sách OAuthV2

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

Nội dung

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

Lưu ý: Nếu bạn muốn tìm hiểu thêm về OAuth trên Apigee Edge, hãy xem trang chủ OAuth. Trang này cung cấp các đường liên kết đến tài nguyên, mẫu, video và nhiều nội dung khác. Hãy xem mẫu OAuth nâng cao trên GitHub để biết ví dụ minh hoạ rõ ràng về cách sử dụng chính sách này trong một ứng dụng đang hoạt động.

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 phần "Mã hoá thông tin xác thực cơ bản".

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

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

Chính sách mẫu dưới đây là một trong nhiều cấu hình có thể có. Mẫu này cho thấy một chính sách OAuthV2 được định cấu hình cho thao tác GenerateAccessToken. Tệp này bao gồm các phần tử bắt buộc và không bắt buộc. Hãy tham khảo phần mô tả về các phần tử trong mục 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>

Thuộc tính <OAuthV2>

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

Phần tử <AccessToken>

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

Theo mặc định, VerifyAccessToken dự kiến mã truy cập sẽ được gửi trong tiêu đề Authorization. Bạn có thể thay đổi chế độ mặc định đó bằng phần tử này. Ví dụ: request.queryparam.access_token cho biết mã truy cập phải xuất hiện dưới dạng một tham số truy vấn có tên là 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"

Phần tử <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Theo mặc định, VerifyAccessToken dự kiến mã truy cập sẽ được gửi trong tiêu đề Uỷ quyền dưới dạng 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ợ.

Phần tử <AppEndUser>

<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 cho phép bạn chỉ định vị trí mà Edge sẽ tìm mã nhận dạng người dùng cuối. Ví dụ: bạn có thể gửi dưới dạng một tham số truy vấn hoặc trong tiêu đề HTTP.

Ví dụ: request.queryparam.app_enduser cho biết AppEndUser phải có dưới dạng một tham số truy vấn, chẳng hạn như ?app_enduser=ntesla@theramin.com. Để yêu cầu AppEndUser trong tiêu đề HTTP, chẳng hạn như đặ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. Tính năng 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 theo mã nhận dạng người dùng cuối. Để biết thêm thông tin, hãy xem phần 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ã nhận dạng ứng dụng hoặc cả hai.

<Attributes/Attribute>

<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. Ví dụ: bạn có thể muố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 biến luồng hoặc từ một chuỗi ký tự. 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, thì chuỗi sẽ là giá trị 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

Xin lưu ý rằng nếu bạn đặt phần tử GenerateResponse của chính sách này thành true, thì biểu thị JSON đầy đủ của mã thông báo sẽ được trả về trong phản hồi, bao gồm mọi thuộc tính 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ả các thuộc tính tuỳ chỉnh trong phản hồi để các ứng dụng khách không nhìn thấy chúng.

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 các nút này, bạn có thể đặt tham 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 được duy trì. Giả sử bạn tạo mã truy cập bằng các thuộc tính tuỳ chỉnh mà bạn muốn ẩn trong phản hồi được tạo. Việc đặt display=false sẽ giúp bạn đạt được mục tiêu đó. Tuy nhiên, nếu mã truy cập mới được tạo sau đó bằng mã làm mới, thì các thuộc tính tuỳ chỉnh ban đầu trong 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ớ rằng thuộc tính display ban đầu được đặt thành false trong chính sách tạo mã truy cập – thuộc tính tuỳ chỉnh chỉ là một phần của siêu dữ liệu mã truy cập.

Bạn sẽ thấy hành vi tương tự nếu thêm các thuộc tính tuỳ chỉnh vào mã uỷ quyền – khi 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 phản hồi mã truy cập. Một lần nữa, đây có thể không phải là hành vi bạn muốn.

Để ẩn các thuộc tính tuỳ chỉnh trong những trường hợp này, bạn có thể chọn một trong các cách sau:

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

Xem thêm phần Tuỳ chỉnh mã thông báo và mã uỷ quyền.

Phần tử <ClientId>

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

Trong một số trường hợp, ứng dụng phải gửi mã ứng dụng đến máy chủ uỷ quyền. Phần tử này chỉ định rằng Apigee sẽ tìm mã ứng dụng khách trong biến luồng request.formparam.client_id. Không hỗ trợ việc đặt ClientId thành bất kỳ biến nào khác. Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <Code>

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

Trong quy trình loại cấp phép uỷ quyền, ứng dụng phải gửi mã uỷ quyền đến máy chủ uỷ quyền (Apigee Edge). Phần tử này cho phép bạn chỉ định vị trí mà Edge sẽ tìm mã uỷ quyền. Ví dụ: bạn có thể 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.auth_code cho biết mã uỷ quyền phải có dưới dạng một tham số truy vấn, chẳng hạn như ?auth_code=AfGlvs9. Để yêu cầu mã uỷ quyền trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.auth_code. Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử<ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Thiết lập 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 gian hết 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 giá trị mặc định được thiết lập ở cấp hệ thống.

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

Với Apigee Edge cho Đám mây công cộng, Edge sẽ giữ 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. Điều này có nghĩa là mã thông báo đã thu hồi vẫn có thể thành công trong tối đa 3 phút, cho đến khi hết giới hạn bộ nhớ đệm.
• Các thực thể Key Management Service (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à các thực thể KMS.

Khổ thơ sau đây cũng chỉ định một biến luồng và giá trị mặc định. Xin lưu ý rằng giá trị biến luồng sẽ đượ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ã thông báo hết hạn sau khi mã thông báo được tạo. Nếu 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), bạn có thể tham khảo giải pháp được mô tả trong bài đăng này trên Cộng đồng Apigee.

Theo mặc định, các mã truy cập đã hết hạn sẽ tự động bị xoá khỏi hệ thống Apigee Edge sau 3 ngày kể từ khi hết hạn. Xem thêm phần Xoá mã truy cập

Đám mây riêng tư: Đối với quá trình cài đặt Edge cho Đám mây riêng tư, giá trị mặc định được đặt theo thuộc tính conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Cách đặt thuộc tính này:

1. Mở tệp message-processor.properties trong một 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 theo ý muốn:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Đảm bảo tệp thuộc tính thuộc về người dùng "apigee":

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

4. Khởi động lại Trình xử lý tin nhắn.

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

Phần tử <ExternalAccessToken>

<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 do Apigee Edge tạo).

Biến request.queryparam.external_access_token cho biết mã truy cập bên ngoài phải có dưới dạng một tham số truy vấn, chẳng hạn như ?external_access_token=12345678. Để yêu cầu mã truy cập bên ngoài trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.external_access_token. Xem thêm phần Sử dụng mã thông báo OAuth của bên thứ ba.

Phần tử <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Nếu phần tử này là false hoặc không có, thì Edge sẽ xác thực client_id và client_secret theo cách thông thường dựa trên kho 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 thông tin chi tiết về cách sử dụng phần tử này, hãy xem phần Sử dụng mã thông báo OAuth của bên thứ ba.

Phần tử <ExternalAuthorizationCode>

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

Cho Apigee Edge biết nơi tìm mã uỷ quyền bên ngoài (mã uỷ quyền không do Apigee Edge tạo).

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

Phần tử <ExternalRefreshToken>

<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 do Apigee Edge tạo).

Biến request.queryparam.external_refresh_token cho biết mã làm mới bên ngoài phải có dưới dạng một tham số truy vấn, chẳng hạn như ?external_refresh_token=12345678. Để yêu cầu mã làm mới bên ngoài trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.external_refresh_token. Xem thêm phần Sử dụng mã thông báo OAuth của bên thứ ba.

Phần tử <GenerateResponse>

<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 GenerateAccessToken, 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 là false, thì không có phản hồi nào được gửi. Thay vào đó, một tập hợp các 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. Ví dụ: một biến luồng có tên là oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code sẽ được điền sẵn mã uỷ quyền mới được tạo. Xin lưu ý rằng expires_in được biểu thị bằng giây trong phản hồi.

Phần tử <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Nếu được đặt thành true, chính sách sẽ tạo và trả về một phản hồi nếu thuộc tính ContinueOnError được đặt thành true. Nếu false (mặc định), không có phản hồi nào được gửi. Thay vào đó, một tập hợp các 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.

<GrantType>

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

Cho chính sách biết nơi tìm tham số loại cấp quyền được truyền trong một yêu cầu. Theo quy cách kỹ thuật OAuth 2.0, bạn phải cung cấp loại cấp phép cùng với các yêu cầu về mã truy cập và mã uỷ quyền. Biến này 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 phải xuất hiện dưới dạng một tham số truy vấn, chẳng hạn như ?grant_type=password. Để yêu cầu loại cấp trong tiêu đề HTTP, chẳng hạn như đặ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à mã uỷ quyền.

Phần tử <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Thao tác OAuth 2.0 do chính sách thực thi.

Phần tử <PassWord>

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

Phần tử này chỉ được dùng với loại cấp mật khẩu. Với loại cấp mật khẩu, thông tin đăng nhập 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> được dùng để chỉ định các biến mà Edge có thể tìm thấy các giá trị này. Nếu bạn không chỉ định các phần tử này, chính sách sẽ mong đợi tìm thấy 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 các giá trị, chính sách sẽ đưa ra lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu đến mọi biến luồng chứa thông tin đăng nhập.

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

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

Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <RedirectUri>

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

Chỉ định vị trí mà Edge sẽ tìm tham số redirect_uri trong yêu cầu.

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

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

• (bắt buộc) Nếu một URL gọi lại được đăng ký với ứng dụng 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 URL này 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 dành cho 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ý khoá API.

• (không bắt buộc) Nếu bạn đã đăng ký một URL gọi lại và redirect_uri bị thiếu trong 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 bạn chưa đăng ký URL gọi lại, thì redirect_uri là bắt buộc. Xin lưu ý rằng trong trường hợp này, Edge sẽ chấp nhận MỌI URL. Trường hợp này có thể gây ra vấn đề bảo mật và do đó,bạn chỉ nên sử dụng với các ứng dụng khách đáng tin cậy. Nếu không tin tưởng các ứng dụng khách, thì bạn nên luôn yêu cầu đăng ký 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 đề. Biến request.queryparam.redirect_uri cho biết RedirectUri phải xuất hiện dưới dạng một tham số truy vấn, chẳng hạn như ?redirect_uri=login.myapp.com. Để yêu cầu RedirectUri trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.redirect_uri. Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <RefreshToken>

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

Khi yêu cầu mã truy cập 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 vị trí mà Edge sẽ tìm kiếm mã làm mới. Ví dụ: bạn có thể 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 mã làm mới phải có dưới dạng một tham số truy vấn, chẳng hạn như ?refresh_token=login.myapp.com. Để yêu cầu RefreshToken trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.refresh_token. Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

Khổ thơ sau đây cũng chỉ định một biến luồng và giá trị mặc định. Xin lưu ý rằng giá trị biến flow sẽ đượ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 quá trình cài đặt Edge cho Đám mây riêng tư, giá trị mặc định được đặt theo thuộc tính conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Cách đặt thuộc tính này:

1. Mở tệp message-processor.properties trong một 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 theo ý muốn:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Đảm bảo tệp thuộc tính thuộc về người dùng "apigee":

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

4. Khởi động lại Trình xử lý tin nhắn.

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

Phần tử <ResponseType>

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

Phần tử này thông báo cho Edge biết loại cấp nào mà ứng dụng khách đang yêu cầu. Tham số này chỉ được dùng với quy trình cấp ngầm và mã uỷ quyền.

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

Phần tử <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Khi được đặt thành true, mã làm mới hiện có sẽ được dùng lại cho đến khi hết hạn. Nếu false, Apigee Edge sẽ phát hành mã làm mới mới khi bạn cung cấp một mã làm mới hợp lệ.

Phần tử <Scope>

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

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

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

<Scope>A B</Scope>

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

Phần tử <State>

<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 vị trí mà Edge sẽ tìm kiếm các giá trị trạng thái. Ví dụ: bạn có thể gửi mã này dưới dạng một tham số truy vấn hoặc trong tiêu đề HTTP. Giá trị trạng thái thường được dùng làm 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 xuất hiện dưới dạng một tham số truy vấn, chẳng hạn như ?state=HjoiuKJH32. Để yêu cầu trạng thái trong tiêu đề HTTP, chẳng hạn như đặt giá trị này thành request.header.state. Xem thêm phần Yêu cầu mã thông báo truy cập và mã uỷ quyền.

Phần tử <StoreToken>

 <StoreToken>true</StoreToken>

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

<SupportedGrantTypes>/<GrantType> 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 cấp quyền mà điểm cuối mã thông báo OAuth hỗ trợ trên Apigee Edge. Một điểm cuối có thể hỗ trợ nhiều loại cấp quyền (tức là bạn có thể định cấu hình một điểm cuối để phân phối mã truy cập 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ề các điểm cuối OAuth. Loại cấp được truyền trong các yêu cầu mã thông báo trong một tham số grant_type.

Nếu bạn không chỉ định loại cấp phép nào được hỗ trợ, thì các loại cấp phép duy nhất được phép là authorization_code và implicit. Xem thêm phần tử <GrantType> (đây là phần tử cấp cao hơn dùng để chỉ định vị trí mà Apigee Edge sẽ tìm tham số grant_type được truyền trong yêu cầu của ứng dụng 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 cấp phép được hỗ trợ).

Phần tử <Tokens>/<Token>

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

Phần tử <UserName>

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

Phần tử này chỉ được dùng với loại cấp mật khẩu. Với loại cấp mật khẩu, thông tin đăng nhập 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> được dùng để chỉ định các biến mà Edge có thể tìm thấy các giá trị này. Nếu bạn không chỉ định các phần tử này, chính sách sẽ mong đợi tìm thấy 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 các giá trị, chính sách sẽ đưa ra lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu đến mọi biến luồng chứa thông tin đăng nhập.

Ví dụ: bạn có thể truyền tên người dùng trong một tham số truy vấn và đặt 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 thành request.header.username.

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

Xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

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

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

Ví dụ: để đảm bảo rằng tất cả các yêu cầu gửi đến một API đều được uỷ quyền, chính sách sau đây sẽ thực thi quy trình 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ào 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 một API đều được xác minh, hãy đính kèm chính sách vào yêu cầu PreFlow của ProxyEndpoint, như sau:

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

Bạn có thể dùng các phần tử không bắt buộc sau đây để ghi đè chế độ cài đặt mặc định cho thao tác VerifyAccessToken.

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

Xem thêm phần Xác minh mã 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 cấp quyền, chính sách sẽ đưa ra các giả định về vị trí hoặc thông tin bắt buộc trong thông báo yêu cầu. Những giả định này dựa trên quy cách OAuth 2.0. Nếu ứng dụng của bạn cần đi lệch khỏi quy cách OAuth 2.0, thì bạn có thể chỉ định vị trí dự kiế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. Bạn có thể chỉ định các tham số này dưới dạng 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 các tham số mã uỷ quyền bắt buộc dưới dạng 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 hỗ trợ cơ sở ứng dụng khách của bạn, bạn có thể kết hợp các tiêu đề và tham số truy vấn:

  ...
  <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ể định cấu hình một vị trí cho mỗi thông số.

Biến của quy trình

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

Thao tác VerifyAccessToken

Thao tác VerifyAccessToken sẽ 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 mã truy cập, ứng dụng của nhà phát triển, nhà phát triển và công ty. Ví dụ: bạn có thể sử dụng chính sách AssignMessage hoặc JavaScript để đọc bất kỳ biến nào trong số này và sử dụng chúng khi cần sau này trong luồng. Những biến này 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 có liên quan đến Ứng dụng 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 sẵn và nếu app.appType là "Developer", thì các thuộc tính của 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 sẵn và nếu app.appType là "Developer", thì các thuộc tính của nhà phát triển sẽ được điền sẵn.

Thao tác GenerateAuthorizationCode

Các biến này được đặt khi thao tác GenerateAuthorizationCode thực thi thành công:

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

Ví dụ: oauthv2authcode.GenerateCodePolicy.code

Các thao tác GenerateAccessToken và RefreshAccessToken

Các biến này được đặt khi các thao tác GenerateAccessToken và RefreshAccessToken thực thi thành công. Xin lưu ý rằng các biến mã làm mới không áp dụng cho quy trình loại cấp thông tin đăng nhập của ứng dụng khách.

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

Ví dụ: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Các biến này được đặt khi thao tác GenerateAccessTokenImplicit thực thi thành công cho 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

Tài liệu tham khảo về 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. Bạn cần biết thông tin này nếu đang phát triển 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 cần biết về lỗi liên quan đến 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 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 một proxy 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 lỗi

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

Nếu <GenerateResponse> là true, 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ã. Để biết danh sách đầy đủ, hãy xem Tài liệu tham khảo về phản hồi lỗi HTTP OAuth.

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

Nếu <GenerateResponse> là true, chính sách sẽ trả về lỗi ở định dạng này để xác minh và xác thực các thao tác. Để biết danh sách đầy đủ, hãy xem Tài liệu tham khảo về phản hồi lỗi HTTP của OAuth.

{  
   {  
      "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 lược đồ XML (.xsd). Để tham khảo, bạn có thể xem lược đồ chính sách trên GitHub.

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

Mỗi tổ chức (kể cả tổ chức dùng thử miễn phí) trên Apigee Edge đều được cung cấp một điểm cuối mã thông báo OAuth. Điểm cuối được định cấu hình sẵn bằng 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 sau khi tạo tài khoản trên Apigee Edge. Để biết thông tin chi tiết, hãy xem phần Tìm hiểu các điểm cuối OAuth.

Xoá mã truy cập

Theo mặc định, mã thông báo OAuth2 sẽ bị xoá khỏi hệ thống Apigee Edge sau 3 ngày (259200 giây) kể từ khi cả mã truy cập và mã làm mới (nếu có) đều 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 xoá để tiết kiệm dung lượng ổ đĩa nếu hệ thống đang tạo ra một số lượng lớn mã thông báo.

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

Cập nhật chế độ cài đặt xoá cho Edge Private Cloud 4.16.01 trở lên

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

Cập nhật chế độ cài đặt xoá hoàn toàn cho Edge Private Cloud 4.15.07

Lưu ý: Chỉ những mã thông báo được tạo sau khi bạn áp dụng các chế độ cài đặt này mới bị ảnh hưởng; các chế độ cài đặt này không áp dụng cho những 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ề một phản hồi mã thông báo có chứa một số thuộc tính nhất định không tuân thủ RFC. Bảng sau đây cho biết các thuộc tính không tuân thủ 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" : "InvalidRequest", "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