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 đa chiều để thực hiện các thao tác cấp quyền sử dụng 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. Trang này cung cấp đường liên kết đến các tài nguyên, đoạn nhạc, video và nhiều nội dung khác. Hãy xem mẫu OAuth nâng cao trên GitHub để thấy 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)));

Hãy xem thêm phần "Mã hoá thông tin xác thực cơ bản".

Tham chiếu phần tử

Tài liệu tham khảo về chính sách 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 được 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 một chính sách OAuthV2 được định cấu hình cho tác vụ GenerateAccessToken. Trong đó có cả các phần tử bắt buộc và không bắt buộc. Hãy tham khảo nội dung mô tả 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>

Thuộc tính < OAuthV2>

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

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

Phần tử <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Phần tử <AccessToken>

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

Theo mặc định, VerifyAccessToken dự kiến sẽ gửi mã truy cập trong tiêu đề Authorization. Bạn có thể thay đổi giá trị 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 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"

Phần tử <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Theo mặc định, VerifyAccessToken dự kiến rằng mã truy cập sẽ được gửi trong tiêu đề Uỷ quyền dưới dạng mã thông báo mang tên ( 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 phải gửi mã nhận dạng người dùng cuối của ứng dụng đến máy chủ uỷ quyền, phần tử này sẽ cho phép bạn chỉ định nơi Edge nên tìm mã nhận dạng người dùng cuối. Ví dụ: sự kiện này có thể được gửi dưới dạng tham số truy vấn hoặc trong tiêu đề HTTP.

Ví dụ: request.queryparam.app_enduser cho biết rằng AppEndUser phải hiển thị dưới dạng tham số truy vấn, chẳng hạn như ?app_enduser=ntesla@theramin.com. Chẳng hạn, để yêu cầu AppEndUser trong tiêu đề HTTP, hãy đặ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ể đưa 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 hữu ích nếu bạn muốn 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ã người dùng cuối, mã ứng dụng hoặc cả hai.

<Thuộc tính/Thuộc tính>

<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 thuộc tính tuỳ chỉnh vào mã truy cập hoặc mã uỷ quyền. 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 mà bạn có thể 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 giá trị trong biến luồng hoặc từ một chuỗi giá trị 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 biến không thể phân giải được, 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 hoặc ẩn 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, thì giá trị 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 nên ẩn một số hoặc tất 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 những thuộc tính đó.

Theo mặc định, các thuộc tính tuỳ chỉnh sẽ xuất hiện trong câu trả lời. Nếu muốn ẩn các quảng cáo 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ột mã truy cập có các thuộc tính tuỳ chỉnh mà bạn muốn ẩn trong phản hồi đã tạo. Việc đặt display=false sẽ giúp bạn hoàn thành mục tiêu đó. Tuy nhiên, nếu sau đó một mã truy cập mới được tạo bằng mã làm mới, thì các thuộc tính tuỳ chỉnh ban đầu của mã truy cập đó sẽ xuất hiện trong phản hồi của mã làm mới. Điều này là do Edge không nhớ rằng ban đầu, thuộc tính display được đặt thành false trong chính sách tạo mã truy cập. Thuộc tính tuỳ chỉnh này 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 thêm các thuộc tính tuỳ 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 phản hồi của mã truy cập. Xin nhắc lại rằng đây có thể không phải là hành vi bạn mong muốn.

Để ẩn thuộc tính tuỳ chỉnh trong các 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 mã thông báo làm mới và đặt giá trị 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 gốc bằng cách sử dụng chính sách Get OAuthV2Info.
• Sử dụng chính sách xử lý hậu kỳ JavaScript để trích xuất mọi thuộc tính tuỳ chỉnh mà bạn không muốn thấy trong phản hồi theo cách thủ công.

Hãy xem thêm bài viết 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 khách phải gửi mã ứng dụng khách đến máy chủ uỷ quyền. Phần tử này cho phép bạn chỉ định vị trí mà Edge nên tìm mã ứng dụng khách. Vị trí hợp lệ duy nhất mà bạn có thể đặt là vị trí mặc định, biến luồng request.formparam.client_id. Không hỗ trợ đặt ClientId thành bất kỳ biến nào khác. Xem thêm bài viết 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 quyền 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 nơi Edge nên tìm mã uỷ quyền. Ví dụ: sự kiện này 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.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, chẳng hạn như ?auth_code=AfGlvs9. Ví dụ: để yêu cầu mã uỷ quyền trong tiêu đề HTTP, hãy đặ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ử<Hết hạn>

<ExpiresIn>10000</ExpiresIn> 

Thực thi thời gian hết hạn của mã thông báo 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 bạn đặt <ExpiresIn> thành -1, thì mã thông báo hoặc mã sẽ hết hạn theo thời hạn mã truy cập OAuth tối đa. 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.

Bạn cũng có thể đặt thời gian hết hạn trong thời gian chạy bằng cách sử dụng giá trị mặc định được mã hoá cứng hoặc 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 bản đồ ánh xạ giá trị khoá, truy xuất, chỉ định giá trị đó cho một biến và tham chiếu giá trị đó trong chính sách. Ví dụ: kvm.oauth.expires_in

Với Apigee Edge cho Cloud công cộng, Edge sẽ lưu 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 bị thu hồi vẫn có thể thành công trong tối đa 3 phút cho đến khi giới hạn bộ nhớ đệm của 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.

khổ thơ sau đây chỉ rõ một biến luồng và một giá trị mặc định. Lưu ý rằng giá trị biến luồng được ưu tiên hơn giá trị mặc định được chỉ định.

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

Edge không hỗ trợ cách buộc hết hạn mã thông báo sau khi mã đó được 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), thì giải pháp khả thi đượ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á hoàn toàn khỏi hệ thống Apigee Edge sau 3 ngày kể từ khi hết hạn. Xem thêm bài viết Đẩy mạnh mã thông báo truy cập

Đám mây riêng tư: Đối với quá trình cài đặt Edge dành cho đám mây riêng tư, giá trị mặc định được đặt bởi 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 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. Thiết lập tài sản như mong muốn:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

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

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

4. Khởi động lại Bộ xử lý thư.

   /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 cần tìm mã truy cập bên ngoài (mã truy cập không do Apigee Edge tạo ra).

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

Phần tử <ExternalUỷ quyền>

<ExternalAuthorization>true</ExternalAuthorization>

Nếu phần tử này sai hoặc không hiện diện, thì Edge sẽ xác thực client_id và client_secret thông thường dựa trên cửa hàng uỷ quyền Apigee Edge. Hãy 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ử <ExternalCấpCode>

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

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

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, chẳng hạn như ?external_auth_code=12345678. Ví dụ: để yêu cầu mã xác thực bên ngoài trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.external_auth_code. Hãy xem thêm bài viết 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 cần 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 rằng mã làm mới bên ngoài phải hiển thị dưới dạng tham số truy vấn, chẳng hạn như ?external_refresh_token=12345678. Ví dụ: để yêu cầu mã làm mới bên ngoài trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.external_refresh_token. Hãy xem thêm bài viết 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 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 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 sẽ được điền sẵn bằng các giá trị liên quan đến hàm 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 bằng mã xác thực mới đúc. 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 bạn đặt thành true, chính sách này 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) thì sẽ 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 bằng các giá trị liên quan đến hàm của chính sách.

<GrantType>

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

Cho chính sách biết nơi tìm thông số loại tài trợ được chuyển trong một yêu cầu. Theo quy cách của OAuth 2.0, loại cấp quyền phải được cung cấp cùng với các yêu cầu 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 hiển thị dưới dạng tham số truy vấn, chẳng hạn như ?grant_type=password. Để yêu cầu loại quyền cấp trong tiêu đề HTTP, chẳng hạn, hãy đặt giá trị này thành request.header.grant_type. Xem thêm bài viết 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 được sử dụng với kiểu cấp mật khẩu. Với kiểu cấp mật khẩu, bạn phải cung cấp thông tin đăng nhập của người dùng (mật khẩu và tên người dùng) 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 các phần tử này không được chỉ định, thì chính sách sẽ 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 các giá trị này, chính sách sẽ gửi ra lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu bất kỳ biến luồng nào 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à thiết lập 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ì thêm đối với các giá trị thông tin đăng nhập này; Edge chỉ đơn giản là xác minh rằng các giá trị đó còn tồn tại. Nhà phát triển API có quyền tuỳ ý truy xuất yêu cầu giá trị và gửi cho 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 bài viết 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 nơi mà Edge nên tìm kiế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 kiểu cấp quyền ngầm ẩn. URI chuyển hướng thông báo cho máy chủ uỷ quyền (Edge) biết nơi gửi mã uỷ quyền (đối với loại cấp mã xác thực) hoặc mã truy cập (đối với loại cấp quyền ngầm ẩn). Bạn cần hiểu rõ khi nào tham số này là bắt buộc, khi nào là không bắt buộc và cách sử dụng tham số này:

• (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 liên kết với khoá ứng dụng khách của yêu cầu và redirect_uri có trong yêu cầu, thì 2 URL này phải khớp chính xác. Nếu không khớp, hàm 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à cách chỉ định URL gọi lại, hãy xem phần Đăng ký ứng dụng và quản lý khoá API.

• (không bắt buộc) Nếu một URL gọi lại được đăng ký 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 chưa đăng ký URL gọi lại, thì bạn bắt buộc phải cung cấp redirect_uri. 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ể gây ra vấn đề bảo mật nên bạn chỉ nên sử dụng ứng dụng này với các ứng dụng đáng tin cậy. 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ý URL gọi lại.

Bạn có thể gửi tham số này trong tham số truy vấn hoặc trong tiêu đề. Biến request.queryparam.redirect_uri cho biết rằng RedirectUri phải hiển thị dưới dạng tham số truy vấn, chẳng hạn như ?redirect_uri=login.myapp.com. Ví dụ: để yêu cầu RedirectUri trong tiêu đề HTTP, đặt giá trị này thành request.header.redirect_uri. Hãy 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 nơi Edge nên tìm mã làm mới. Ví dụ: URL này 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 rằng mã làm mới phải hiển thị dưới dạng tham số truy vấn, chẳng hạn như ?refresh_token=login.myapp.com. Chẳng hạn, để yêu cầu RefreshToken trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.refresh_token. Hãy xem thêm phần Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <RefreshToken vàiIn>

<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 giá trị do hệ thống tạo cộng với giá trị <RefreshTokenExpiresIn>. Nếu bạn đặt <RefreshTokenExpiresIn> thành -1, thì mã làm mới sẽ hết hạn theo thời hạn mã làm mới OAuth tối đa. Nếu bạn không chỉ định <RefreshTokenExpiresIn>, thì theo mặc định, thời hạn là vô thời hạn.

Bạn cũng có thể đặt thời gian hết hạn trong thời gian chạy bằng cách sử dụng giá trị mặc định được mã hoá cứng hoặc 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 bản đồ ánh xạ giá trị khoá, truy xuất, chỉ định giá trị đó cho một biến và tham chiếu giá trị đó trong chính sách. Ví dụ: kvm.oauth.expires_in.

khổ thơ sau đây chỉ rõ một biến luồng và một giá trị mặc định. Lưu ý rằng giá trị biến flow được ưu tiên hơn giá trị mặc định được 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 dành cho đám mây riêng tư, giá trị mặc định được đặt bởi 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 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. Thiết lập tài sản như mong muốn:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

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

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

4. Khởi động lại Bộ xử lý thư.

   /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 về loại quyền mà ứng dụng khách đang yêu cầu. Phương thức này chỉ được dùng với mã uỷ quyền và luồng kiểu cấp quyền ngầm ẩn.

Theo mặc định, Edge sẽ tìm kiế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 sử 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 sẽ được truyền trong tiêu đề yêu cầu. Xem thêm bài viết Yêu cầu mã truy cập và mã uỷ quyền.

Phần tử <UsageRefreshToken>

<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 là false, thì mã làm mới sẽ do Apigee Edge phát hành khi trình bày 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ó mặt trong một trong các chính sách GenerateAccessToken hoặc GenerateCommitCode, thì phần tử này sẽ được dùng để chỉ định phạm vi nào cấp mã thông báo hoặc mã. Các giá trị này 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ử để lấy biến luồng, cho phép bạn lựa chọn cách truyền 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 tham số truy vấn, chẳng hạn như ?scope=READ. Chẳng hạn, để yêu cầu phạm vi trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.scope.

Nếu phần tử này xuất hiện trong một chính sách "VerifyAccessToken", thì phần tử này sẽ được dùng để chỉ định 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ể sử dụng biến. Ví dụ:

<Scope>A B</Scope>

Xem thêm bài viết Xử lý 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 sẽ cho phép bạn chỉ định nơi Edge tìm giá trị trạng thái. Ví dụ: sự kiện này có thể được gửi dưới dạng tham số truy vấn hoặc 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 rằng trạng thái phải hiện diện dưới dạng tham số truy vấn, chẳng hạn như ?state=HjoiuKJH32. Ví dụ: để yêu cầu trạng thái trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.state. Hãy xem thêm bài viết Yêu cầu mã 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, yêu cầu này sẽ không được duy trì.

Phần tử <SupportedGrantTypes>/<GrantType>

<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 được hỗ trợ bởi một điểm cuối của mã thông báo OAuth trên Apigee Edge. Một điểm cuối có thể hỗ trợ nhiều loại cấp quyền (nghĩa là một điểm cuối có thể được định cấu hình để 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ề điểm cuối, hãy xem bài viết Tìm hiểu về điểm cuối của OAuth. Loại cấp quyền được truyền vào yêu cầu mã thông báo trong tham số grant_type.

Nếu bạn không chỉ định loại cấp quyền được hỗ trợ, thì loại cấp duy nhất được phép là authorization_code và implicit. Hãy xem thêm phần tử <GrantType> (là phần tử cấp cao hơn dùng để chỉ định trong đó Apigee Edge nên tìm kiế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 quyền được hỗ trợ).

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

Được dùng với các hoạt động ValidationToken và InvalidateToken. Hãy xem thêm phần 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 cần bị thu hồi. Nếu dự kiến nhà phát triển sẽ gửi mã truy cập dưới dạng tham số truy vấn có tên access_token, chẳng hạn, hãy sử dụng request.queryparam.access_token.

Phần tử <UserName>

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

Phần tử này được sử dụng với kiểu cấp mật khẩu. Với kiểu cấp mật khẩu, bạn phải cung cấp thông tin đăng nhập của người dùng (mật khẩu và tên người dùng) 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 các phần tử này không được chỉ định, thì chính sách sẽ 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 các giá trị này, chính sách sẽ gửi ra lỗi. Bạn có thể sử dụng các phần tử <PassWord> và <UserName> để tham chiếu bất kỳ biến luồng nào chứa thông tin xác thực.

Ví dụ: bạn có thể truyền tên người dùng vào một tham số truy vấn và thiết lập 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ì thêm đối với các giá trị thông tin đăng nhập này; Edge chỉ đơn giản là xác minh rằng các giá trị đó còn tồn tại. Nhà phát triển API có quyền tuỳ ý truy xuất yêu cầu giá trị và gửi cho 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 bài viết Yêu cầu mã truy cập và mã uỷ quyền.

Xác minh mã truy cập

Sau khi thiết lập điểm cuối của 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 (Flow) hiển thị tài nguyên được bảo vệ.

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

Hãy xem thêm bài viết 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í cho biến yêu cầu

Đối với mỗi loại cấp quyền, chính sách này sẽ đưa ra giả định về vị trí hoặc thông tin bắt buộc trong thông báo yêu cầu. Các giả định này dựa trên thông số kỹ thuật của OAuth 2.0. Nếu ứng dụng của bạn cần không nhất quán với thông số kỹ thuật của OAuth 2.0, thì bạn có thể chỉ định vị trí dự kiến cho mỗi tham 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 đối số này có thể được chỉ định 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 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 để hỗ trợ cơ sở ứng dụng khách, bạn có thể kết hợp và so khớp tiêu đề cũng như 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 luồng

Các biến luồng 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 thực thi. Do đó, các chính sách hoặc ứng dụng khác thực thi trong luồng proxy API có thể được dùng.

Thao tác VerifyAccessToken

Sẽ thực thi thao tác VerifyAccessToken, một số lượng lớn các biến luồng sẽ đượ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 khối composeMessage hoặc JavaScript để đọc bất kỳ biến nào trong số các biến này và sử dụng chúng nếu cần trong tương lai. Các 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 liên quan đến Ứng dụng của nhà phát triển 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ì thuộc tính của công ty sẽ được điền và nếu app.appType là "Nhà phát triển", thì thuộc tính của nhà phát triển sẽ được điền.

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

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

Thao tác generateAuthorizeCode

Các biến này được thiết lập khi thao tác GenerateAuthorizeCode thực thi thành công:

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

Ví dụ: oauthv2authcode.GenerateCodePolicy.code

Các hoạt động GenerateAccessToken và RefreshAccessToken

Các biến này được thiết lập khi các tác vụ GenerateAccessToken và RefreshAccessToken thực thi thành công. Xin lưu ý rằng các biến mã thông báo làm mới không áp dụng cho quy trình loại cấp thông tin đăng nhập ứng dụ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 thao tác GenerateAccessTokenOverride thực thi thành công cho luồng 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 đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem 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 thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai 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 sẽ được gửi lại ứng dụng khách nếu phần tử <GenerateResponse> là true.

Nếu <GenerateResponse> là true, thì chính sách sẽ trả về các lỗi theo đị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 qua OAuth.

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

Nếu <GenerateResponse> là true (đúng), chính sách sẽ trả về các 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 qua 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 giản đồ XML (.xsd). Để tham khảo, lược đồ chính sách có 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í) sử dụng Apigee Edge đều được cấp phép bằng một điểm cuối của 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 của mã thông báo ngay khi tạo tài khoản trên Apigee Edge. Để biết thông tin chi tiết, hãy xem bài viết Tìm hiểu về điểm cuối của OAuth.

Xoá mã truy cập

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ể cần thay đổi giá trị mặc định này. Ví dụ: bạn nên rút ngắn thời gian xoá hoàn toàn để tiết kiệm dung lượng ổ đĩa nếu có một số lượng lớn mã thông báo đang được tạo.

Nếu đang dùng Edge for Private Cloud, bạn có thể thay đổi chế độ mặc định này bằng cách đặt các thuộc tính tổ chức như giải thích trong phần này. (Tính năng xoá hoàn toàn các mã thông báo đã hết hạn trong vòng 3 ngày sẽ á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ũ, khoảng thời gian xoá 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 trở lên

Lưu ý: Chỉ những mã thông báo được tạo sau khi áp dụng những 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 đã tạo trước đó.

Cập nhật các tùy chọn 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 áp dụng những chế độ cài đặt này; chế độ cài đặt này không áp dụng cho những mã thông báo đã tạo trước đó.

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

Chính sách OAuthV2 sẽ trả về phản hồi mã thông báo có chứa một số thuộc tính không tuân thủ RFC. Bảng sau đây cho thấy 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ã thông báo 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