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 các đ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ủ về 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 cách minh hoạ rõ ràng 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".

Tham chiếu phần tử

Tài liệu tham khảo 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 dưới đây là một trong nhiều cấu hình có thể áp dụng. 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 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>

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 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ã thông báo truy cập phải xuất hiện dưới dạng 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 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 cho phép bạn chỉ định vị trí Edge sẽ tìm mã nhận dạng người dùng cuối. Ví dụ: bạn có thể gửi thông số này 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 xuất hiện dưới dạng tham số truy vấn, chẳng hạn như ?app_enduser=ntesla@theramin.com. Ví dụ: để 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 rất 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 bài viết Cho phép 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.

<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 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 mã nhận dạng phiên vào mã thông báo 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 flow 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 flow 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 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, thì dữ liệu JSON đầy đủ của mã thông báo sẽ được trả về trong phản hồi, bao gồm cả mọi thuộc tính tuỳ chỉnh đã đặt. Trong một số trường hợp, bạn có thể muốn ẩn một số hoặc tất cả thuộc tính tuỳ chỉnh của mì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 phản hồi. Nếu muốn ẩn chúng, 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 được lưu giữ. 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 thiết lập 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 từ mã truy cập sẽ xuất hiện trong phản hồi mã làm mới. Nguyên nhân 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 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 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 các thuộc tính 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 mã thông báo 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ý sau để 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 khách phải gửi mã ứng dụng khách đến máy chủ uỷ quyền. Phần tử này chỉ định rằng Apigee nên tìm mã ứng dụng khách trong 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 phần Yêu cầu mã thông báo truy cập và mã uỷ quyền.

Phần tử <Code>

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

Trong quy trình cấp quyền, ứng dụng khách 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í Edge sẽ tìm kiếm mã uỷ quyền. Ví dụ: bạn có thể gửi thông số này 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 xuất hiện 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ã thông báo truy cập và mã uỷ quyền.

Phần tử<ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

Thực thi 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à một 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ã 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 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 bằng cách tham chiếu đến một biến flow. 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 đồ khoá-giá trị, truy xuất, gán 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 đám mây công cộng, Edge 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 hết hạn.
• Các 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.

Các dòng sau đây chỉ định một biến flow và một giá trị mặc định. Xin lưu ý rằng giá trị biến dò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ộ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), 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, mã truy cập đã hết hạn sẽ tự động bị xoá khỏi hệ thống Apigee Edge 3 ngày sau khi hết hạn. Xem thêm phần Xoá mã thông báo truy cập

Đám mây riêng tư: Đối với quá trình cài đặt Edge for Private Cloud, giá trị mặc định được đặt bằng 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. Đặ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 quyền 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 Trình xử lý thông báo.

   /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 hiện diện 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. 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 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ã 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 xuất hiện dưới dạng một 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 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ã thông báo làm mới bên ngoài phải xuất hiện 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ã thông báo 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. 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 sẽ tạo và trả về một phản hồi. Ví dụ: đối với GenerateAccessToken, phản hồi có thể 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, hệ thống sẽ không gửi phản hồi. Thay vào đó, một tập hợp các biến flow (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. Ví dụ: một biến flow có tên oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code sẽ được điền bằng mã uỷ quyền mới 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ề phản hồi nếu thuộc tính ContinueOnError được đặt thành true. Nếu là false (mặc định), hệ thống sẽ không gửi phản hồi. Thay vào đó, một tập hợp các biến flow (luồng) được điền sẵn 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 tham số loại cấp được truyền trong một yêu cầu. Theo quy cách kỹ thuật của OAuth 2.0, loại cấp phép phải được cung cấ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 tham số truy vấn, chẳng hạn như ?grant_type=password. Ví dụ: để yêu cầu loại cấp 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ã thông báo 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 dùng với chỉ loại cấp mật khẩu. Với hình thức 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ẽ 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 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 flow nào chứa thông tin xác thực.

Ví dụ: bạn có thể truyền mật khẩu trong 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 thực hiện thao tác nào khác đối với các giá trị thông tin xác thực này. Edge chỉ đơn giản là xác minh rằng các giá trị đó có hiện diện. Nhà phát triển API có thể truy xuất yêu cầu giá trị và gửi các yêu cầu đó đến 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í Edge sẽ tìm thông 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 quyền ngầm ẩn. URI chuyển hướng cho máy chủ uỷ quyền (Edge) biết vị trí 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õ thời điểm bắt buộc phải sử dụng tham số này, thời điểm 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 các khoá ứng dụng của yêu cầu và nếu redirect_uri có trong yêu cầu, thì cả hai 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 một URL gọi lại được đăng ký và thiếu redirect_uri 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 không đăng ký URL gọi lại, thì bạn bắt buộc phải có redirect_uri. 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ì vậy, bạn chỉ nên sử dụng với các ứng dụng khách đá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ý một 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 xuất hiện 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, hãy đặt giá trị này thành request.header.redirect_uri. 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ử <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 sẽ tìm mã làm mới. Ví dụ: bạn có thể gửi thông số này 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ã thông báo làm mới phải xuất hiện dưới dạng tham số truy vấn, chẳng hạn như ?refresh_token=login.myapp.com. Ví dụ: để yêu cầu RefreshToken trong tiêu đề HTTP, hãy đặt giá trị này thành request.header.refresh_token. 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ử <RefreshTokenExpiresIn>

<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à 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 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 định cấu hình ở 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 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 bằng cách tham chiếu đến một biến flow. 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 ánh xạ giá trị khoá, truy xuất giá trị đó, gán giá trị đó cho một biến và tham chiếu giá trị đó trong chính sách. 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. Xin lưu ý rằng giá trị biến dòng chảy 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 for Private Cloud, giá trị mặc định được đặt bằng 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. Đặ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 quyền 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 Trình xử lý thông báo.

   /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 cho Edge biết loại quyền cấp 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à quy trình cấp loại ngầm ẩ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 sử dụng phần tử <ResponseType> để định cấu hình một biến flow 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ần được chuyển trong tiêu đề của yêu cầu. 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ử <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Khi được đặ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, Apigee Edge sẽ phát hành một mã thông báo làm mới mới khi bạn cung cấp một mã thông báo làm mới hợp lệ.

Phần tử <Scope>

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

Nếu có trong một trong các chính sách GenerateAccessToken hoặc GenerateAuthorizationCode, phần tử này sẽ được dùng để chỉ định phạm vi cấp mã hoặc mã thông báo. Các giá trị này thường được truyề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 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 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. Ví dụ: để 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 này sẽ thực thi. Trong loại chính sách này, giá trị phải là tên phạm vi "đã mã hoá cứng" – bạn không thể sử dụng biến. Ví dụ:

<Scope>A B</Scope>

Xem thêm phần Làm việc với phạm vi OAuth2 và Yêu cầu mã thông báo 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í Edge sẽ tìm kiếm các giá trị trạng thái. Ví dụ: bạn có thể gửi thông tin này 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 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 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. 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, giá trị 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 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 cấp phép (tức là một điểm cuối có thể được định cấu hình để phân phối mã thông báo truy cập cho nhiều loại cấp phép). Để biết thêm về điểm cuối, hãy xem phần Tìm hiểu về điểm cuối OAuth. Loại cấp phép được truyền trong các yêu cầu mã thông báo trong tham số grant_type.

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

Dùng với các thao tác ValidateToken và InvalidateToken. Xem thêm phần Chấp thuận 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 thu hồi. Ví dụ: nếu nhà phát triển dự kiến sẽ gửi mã thông báo truy cập dưới dạng tham số truy vấn có tên là access_token, hãy 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 quyền bằng mật khẩu. Với hình thức 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ẽ 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ị này, chính sách sẽ gửi một 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 nào có chứa thông tin xác thực.

Ví dụ: bạn có thể truyền tên người dùng trong 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 xác thực này; Edge chỉ xác minh rằng các giá trị này có mặt. Nhà phát triển API có thể truy xuất yêu cầu giá trị và gửi các yêu cầu đó đến 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ã thông báo 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 mã thông báo cho proxy API, chính sách OAuthV2 tương ứng chỉ định thao tác VerifyAccessToken sẽ được đính kèm vào 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 đối với một API đều được uỷ quyền, chính sách sau đây sẽ 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 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 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ử 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í của biến yêu cầu

Đối với mỗi loại quyền cấp, chính sách 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 OAuth 2.0. Nếu ứng dụng của bạn cần khác với quy cách OAuth 2.0, thì bạn có thể chỉ định các vị trí dự kiến cho từng 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, 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, bạn có thể kết hợp và so khớp các tiêu đề với 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 tham số.

Biến flow

Các biến luồng được xác định trong bảng này được điền sẵn dữ liệu 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 sẽ có thể thực thi các chính sách proxy API.

Thao tác VerifyAccessToken

Thao tác VerifyAccessToken thực thi, một số lượng lớn 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 các biến đó khi cần trong luồng sau này. 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 dành cho 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" (Công ty), thì các thuộc tính công ty sẽ được điền sẵn và nếu app.appType là "Developer" (Nhà phát triển), thì 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" (Công ty), thì các thuộc tính công ty sẽ được điền sẵn và nếu app.appType là "Developer" (Nhà phát triển), thì các thuộc tính 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

Thao tác GenerateAccessToken và RefreshAccessToken

Các biến này được đặt khi các hoạt động 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 luồng loại cấp thông tin xác thực ứ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 GenerateAccessTokenImplicit thực thi thành công cho luồng loại cấp phép ngầm ẩn.

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

Ví dụ: oauthv2accesstoken.RefreshTokenPolicy.access_token

Thông tin 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. 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 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 (ngay cả tổ chức dùng thử miễn phí) trên Apigee Edge đều được cấp một điểm cuối mã thông báo OAuth. Điểm cuối được định cấu hình trước 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 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 các điểm cuối của OAuth.

Lấy mã truy cập xoá

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ó) 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 đang tạo một 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 giá trị mặc định này bằng cách đặt các thuộc tính của tổ chức như 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ũ, khoảng thời gian xoá mặc định là 180 ngày.)

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

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

Cập nhật các 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 á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 chứa một số thuộc tính nhấ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ủ mà 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