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 Nếu muốn, bạn có thể sử dụng phần tử |
Không áp dụng | Bắt buộc |
continueOnError |
Đặt thành Đặt thành |
false | Không bắt buộc |
enabled |
Đặt thành Đặt thà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 |
---|---|
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á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. 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>