Chính sách GetOAuthV2Info

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

Lấy các thuộc tính của mã truy cập, mã làm mới, mã uỷ quyền và thuộc tính của ứng dụng khách, đồng thời điền giá trị của các thuộc tính đó cho các biến.

Chính sách này rất hữu ích khi bạn cần định cấu hình hành vi động, có điều kiện dựa trên giá trị trong mã thông báo hoặc mã xác thực. Bất cứ khi nào quy trình xác thực mã thông báo diễn ra, các biến sẽ được tự động điền bằng giá trị của các thuộc tính mã thông báo. Tuy nhiên, trong trường hợp chưa xác thực mã thông báo, bạn có thể dùng tính năng này để điền rõ ràng các biến bằng giá trị thuộc tính của mã thông báo. Hãy xem thêm bài viết Tuỳ chỉnh mã thông báo và Mã uỷ quyền.

Mã truy cập mà bạn chuyển cho chính sách này phải hợp lệ, nếu không chính sách sẽ tạo ra lỗi invalid_access_token.

Mẫu

Các mẫu sau đây sử dụng chính sách Nhận thông tin về OAuth V2 để truy xuất thông tin về các thành phần của quy trình OAuth2, sau đó truy cập thông tin đó trong mã.

Mã truy cập

Để tham chiếu đến một mã truy cập, hãy sử dụng phần tử <AccessToken> trong chính sách của bạn.

Ví dụ sau đây cho rằng bạn sẽ tìm thấy mã truy cập trong tham số truy vấn có tên là "access_token" (chi tiết triển khai thực tế là do bạn quyết định):

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

Khi có mã truy cập, chính sách sẽ tra cứu hồ sơ của mã thông báo và điền dữ liệu hồ sơ cho một nhóm biến.

Sau đó, bạn có thể truy cập vào các biến này bằng JavaScript hoặc phương thức khác. Ví dụ sau đây truy xuất(các) phạm vi liên kết với mã truy cập bằng JavaScript:

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

Xin lưu ý rằng để truy cập vào những biến đó trong mã, bạn phải thêm tiền tố "ISBNv2accesstoken". Để biết danh sách đầy đủ các biến được cung cấp qua mã truy cập, hãy xem phần Biến mã truy cập.

Mã xác thực

Để nhận thuộc tính mã uỷ quyền, hãy sử dụng phần tử <AuthorizationCode> trong chính sách của bạn.

Ví dụ sau đây cho rằng bạn sẽ tìm thấy mã truy cập trong tham số biểu mẫu có tên là "code" (chi tiết triển khai thực tế là do bạn quyết định):

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

Khi có mã xác thực, chính sách này sẽ tra cứu thông tin của mã và điền sẵn dữ liệu mã xác thực cho một tập hợp các biến.

Sau đó, bạn có thể truy cập vào các biến này bằng JavaScript hoặc phương thức khác. Ví dụ sau truy xuất thuộc tính tuỳ chỉnh liên kết với mã uỷ quyền bằng JavaScript:

var attr = context.getVariable(‘oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name’);

Lưu ý rằng để truy cập vào những biến đó trong mã, bạn phải thêm tiền tố " OAuthv2authcode". Để biết danh sách đầy đủ các biến có sẵn qua mã xác thực, hãy xem bài viết Biến mã uỷ quyền.

Làm mới mã thông báo

Để lấy các thuộc tính mã làm mới, hãy sử dụng phần tử <RefreshToken> trong chính sách của bạn.

Ví dụ sau đây dự kiến sẽ tìm thấy mã truy cập trong tham số truy vấn có tên là "refresh_token" (chi tiết triển khai thực tế là do bạn quyết định):

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

Khi có mã làm mới, chính sách này sẽ tra cứu thông tin của mã làm mới và điền một tập hợp các biến bằng dữ liệu mã làm mới.

Sau đó, bạn có thể truy cập vào các biến đó bằng JavaScript hoặc phương thức khác. Ví dụ sau đây truy xuất thuộc tính tuỳ chỉnh liên kết với mã làm mới bằng JavaScript:

var attr = context.getVariable(‘oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name’);

Xin lưu ý rằng để truy cập vào các biến trong mã, bạn phải thêm tiền tố " Oauthv2refreshtoken". Để biết danh sách đầy đủ các biến có sẵn thông qua mã làm mới, hãy xem phần Làm mới các biến mã thông báo.

Tĩnh

Trong một số ít trường hợp, bạn có thể cần lấy hồ sơ của một mã thông báo được định cấu hình tĩnh (một mã thông báo không thể truy cập được thông qua một biến). Bạn có thể thực hiện việc này bằng cách cung cấp giá trị của mã truy cập dưới dạng một phần tử.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

Bạn cũng có thể thực hiện việc này với tất cả các loại mã thông báo khác (mã ứng dụng khách, mã uỷ quyền và mã làm mới).

Client ID

Ví dụ này cho biết cách truy xuất thông tin về ứng dụng khách bằng mã ứng dụng khách. Sau khi thực thi, chính sách này sẽ điền thông tin ứng dụng vào một tập hợp các biến. Trong trường hợp này, chính sách dự kiến sẽ tìm thấy mã ứng dụng khách trong một tham số truy vấn có tên là client_id. Khi có mã ứng dụng khách, chính sách này sẽ tra cứu hồ sơ của ứng dụng và điền sẵn dữ liệu hồ sơ vào một nhóm biến. Các biến sẽ có tiền tố là oauthv2client.

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

Sau đó, bạn có thể truy cập vào các biến này bằng JavaScript hoặc phương thức khác. Ví dụ: để lấy tên ứng dụng và email của nhà phát triển được liên kết với ứng dụng khách bằng JavaScript:

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

Tham chiếu phần tử

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

Thuộc tính <Get OAuthV2Info>

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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:

Thuộc tính Nội dung mô tả Mặc định Sự hiện diện
name

Tên nội bộ của chính sách. Giá trị của thuộc tính name có thể chứa chữ cái, số, dấu cách, dấu gạch nối, dấu gạch dưới và dấu chấm. Giá trị này không được vượt quá 255 ký tự.

Nếu muốn, bạn có thể sử dụng phần tử <DisplayName> để gắn nhãn cho chính sách này trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên ngôn ngữ tự nhiên khác.

Không áp dụng Bắt buộc
continueOnError

Đặt thành false để trả về lỗi khi một chính sách không hoạt động. Đây là hành vi dự kiến đối với hầu hết các chính sách.

Đặt thành true để quá trình thực thi luồng tiếp tục ngay cả khi chính sách không thành công.

false Không bắt buộc
enabled

Đặt thành true để thực thi chính sách.

Đặt thành false để tắt chính sách này. Chính sách này sẽ không được thực thi ngay cả khi chính sách vẫn được đính kèm vào một quy trình.

đúng Không bắt buộc
async

Thuộc tính này không được dùng nữa.

false Không được dùng nữa

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>
Mặc định

Không áp dụng

Nếu bạn bỏ qua phần tử này, thì giá trị thuộc tính name của chính sách sẽ được sử dụng.

Sự hiện diện Không bắt buộc
Loại Chuỗi

Phần tử <AccessToken>

Truy xuất hồ sơ cho mã truy cập. Bạn chuyển vào một biến chứa chuỗi mã truy cập hoặc một chuỗi mã thông báo bằng giá trị cố định (hiếm gặp). Trong ví dụ này, mã truy cập được truy xuất từ tham số truy vấn được chuyển trong một yêu cầu. Sử dụng phần tử <IgnoreAccessTokenStatus> nếu bạn muốn trả về thông tin cho một mã thông báo đã bị thu hồi hoặc đã hết hạn.

<AccessToken ref="request.queryparam.access_token"></AccessToken>

Mặc định:

request.formparam.access_token (một x-www-form-url encrypted và được chỉ định trong nội dung yêu cầu)

Sự hiện diện:

Không bắt buộc

Loại: Chuỗi
Giá trị hợp lệ:

Biến luồng chứa một chuỗi mã truy cập hoặc một chuỗi ký tự.


Phần tử <Uỷ quyềnCode>

Truy xuất hồ sơ cho mã uỷ quyền. Bạn chuyển vào một biến chứa chuỗi mã xác thực hoặc một chuỗi mã thông báo bằng giá trị cố định (trường hợp hiếm gặp). Trong ví dụ này, mã xác thực được truy xuất từ tham số truy vấn được chuyển trong một yêu cầu. Để biết danh sách các biến được điền sẵn bằng thao tác này, hãy xem phần "Biến luồng".

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

Mặc định:

request.formparam.access_token (một x-www-form-url encrypted và được chỉ định trong nội dung yêu cầu)

Sự hiện diện:

Không bắt buộc

Loại: Chuỗi
Giá trị hợp lệ:

Biến luồng chứa chuỗi mã xác thực hoặc chuỗi ký tự.

Phần tử <ClientId>

Truy xuất thông tin liên quan đến mã ứng dụng khách. Trong ví dụ này, mã ứng dụng khách được truy xuất từ một tham số truy vấn được chuyển trong một yêu cầu. Để biết danh sách các biến được điền sẵn bằng thao tác này, hãy xem phần "Biến luồng".

<ClientId ref="request.queryparam.client_id"></ClientId>

Mặc định:

request.formparam.access_token (một x-www-form-url encrypted và được chỉ định trong nội dung yêu cầu)

Sự hiện diện:

Không bắt buộc

Loại: Chuỗi
Giá trị hợp lệ: Biến luồng chứa chuỗi mã xác thực hoặc chuỗi ký tự.

Phần tử <IgnoreAccessTokenStatus>

Trả về thông tin mã thông báo ngay cả khi mã thông báo đã hết hạn hoặc bị thu hồi. Chỉ có thể sử dụng phần tử này với mã truy cập. Theo mặc định, thông tin cho các thực thể khác như mã làm mới và mã uỷ quyền sẽ được trả về bất kể trạng thái của chúng là gì.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Mặc định:

false

Sự hiện diện:

Không bắt buộc

Loại: Boolean
Giá trị hợp lệ: true hoặc false

Phần tử <RefreshToken>

Truy xuất hồ sơ cho mã làm mới. Bạn chuyển vào một biến chứa chuỗi mã làm mới hoặc một chuỗi mã thông báo bằng giá trị cố định (trường hợp hiếm gặp). Trong ví dụ này, mã làm mới được truy xuất từ tham số truy vấn được chuyển trong một yêu cầu. Để biết danh sách các biến được điền sẵn bằng thao tác này, hãy xem phần "Biến luồng".

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

Mặc định:

request.formparam.access_token (một x-www-form-url encrypted và được chỉ định trong nội dung yêu cầu)

Sự hiện diện:

Không bắt buộc

Loại: Chuỗi
Giá trị hợp lệ:

Biến luồng chứa chuỗi mã thông báo làm mới hoặc chuỗi ký tự.

Biến luồng

Chính sách Get OAuthV2Info điền các biến này và thường được sử dụng trong trường hợp bạn cần dữ liệu hồ sơ nhưng chưa xảy ra lượt cấp phép hoặc xác thực. .

Biến mã ứng dụng khách

Các biến này được điền khi phần tử ClientId được đặt:

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

Truy cập vào các biến mã thông báo

Các biến này được điền khi phần tử AccessToken được đặt:

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Biến mã uỷ quyền

Các biến này được điền sẵn khi bạn đặt phần tử Uỷ quyền:

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Làm mới các biến mã thông báo

Các biến này được điền khi phần tử RefreshToken được đặt:

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Lược đồ

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

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áchXử 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. Tên lỗi hiển thị bên dưới là các chuỗi được gán cho biến fault.name khi xảy ra lỗi. Hãy xem phần Biến lỗi dưới đây để biết thêm thông tin.

Mã lỗi Trạng thái HTTP Nguyên nhân
steps.oauth.v2.access_token_expired 500 Mã truy cập được gửi đến chính sách đã hết hạn.
steps.oauth.v2.authorization_code_expired 500 Mã uỷ quyền gửi đến chính sách này đã hết hạn.
steps.oauth.v2.invalid_access_token 500 Mã truy cập mà bạn gửi cho chính sách này là không hợp lệ.
steps.oauth.v2.invalid_client-invalid_client_id 500 Mã ứng dụng khách được gửi đến chính sách không hợp lệ.
steps.oauth.v2.invalid_refresh_token 500 Mã làm mới được gửi tới chính sách là không hợp lệ.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 Mã uỷ quyền mà bạn gửi đến chính sách này là không hợp lệ.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Vui lòng xem bài đăng này trên Cộng đồng Apigee để biết thông tin về cách khắc phục lỗi này.
steps.oauth.v2.refresh_token_expired 500 Mã làm mới được gửi đến chính sách đã hết hạn.

Lỗi triển khai

Hãy tham khảo thông báo được báo cáo trong giao diện người dùng để biết thông tin về lỗi triển khai.

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.

Biến Trong đó Ví dụ:
fault.name="fault_name" fault_name là tên của lỗi, như liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name là tên của chính sách báo lỗi do người dùng chỉ định. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name là tên của chính sách báo lỗi do người dùng chỉ định. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name là tên của chính sách báo lỗi do người dùng chỉ định. oauthV2.GetTokenInfo.cause = ClientID is Invalid

Ví dụ về phản hồi lỗi

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

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

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Chủ đề có liên quan