Chính sách Xác minh khóa API

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

Chính sách Xác minh khoá API cho phép bạn thực thi quy trình xác minh khoá API trong thời gian chạy, trong đó chỉ cho phép những ứng dụng có khoá API được phê duyệt truy cập vào API của bạn. Chính sách này đảm bảo rằng các khoá API là hợp lệ, chưa bị thu hồi và được phê duyệt để sử dụng các tài nguyên cụ thể liên kết với các sản phẩm API của bạn.

Mẫu

Khoá trong tham số truy vấn

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

Trong ví dụ này, chính sách dự kiến sẽ tìm thấy khoá API trong một biến luồng có tên là request.queryparam.apikey. Biến request.queryparam.{name} là biến luồng Edge tiêu chuẩn được điền sẵn giá trị của tham số truy vấn được truyền trong yêu cầu ứng dụng.

Lệnh curl sau đây truyền khoá API trong một tham số truy vấn:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Khoá trong tiêu đề

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

Trong ví dụ này, chính sách dự kiến sẽ tìm thấy khoá API trong một biến luồng có tên là request.header.x-apikey. Biến request.header.{name} là biến luồng Edge tiêu chuẩn được điền sẵn bằng giá trị của tiêu đề được chuyển trong yêu cầu ứng dụng.

CURL sau đây cho biết cách chuyển khoá API trong tiêu đề:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

Khoá trong biến

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

Chính sách này có thể tham chiếu bất kỳ biến nào chứa khoá đó. Chính sách trong ví dụ này trích xuất khoá API từ một biến có tên là requestAPIKey.key.

Việc biến đó được điền như thế nào là tuỳ thuộc vào bạn. Ví dụ: bạn có thể sử dụng chính sách Trích xuất biến để điền requestAPIKey.key từ tham số truy vấn có tên myKey, như hiển thị dưới đây:

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Truy cập các biến của luồng chính sách

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Edge tự động điền một tập hợp các biến luồng khi thực thi chính sách Xác minh khoá API cho khoá API hợp lệ. Bạn có thể sử dụng các biến này để truy cập vào thông tin như tên ứng dụng, mã ứng dụng và thông tin về nhà phát triển hoặc công ty đã đăng ký ứng dụng. Trong ví dụ trên, bạn sử dụng chính sách Chỉ định thông báo để truy cập vào tên, họ và địa chỉ email của nhà phát triển sau khi Xác minh khoá API thực thi.

Tất cả các biến này đều có tiền tố:

verifyapikey.{policy_name}

Trong ví dụ này, tên chính sách Xác minh khoá API là "verify-api-key". Do đó, bạn tham chiếu đến tên của nhà phát triển đưa ra yêu cầu bằng cách truy cập vào biến verifyapikey.verify-api-key.developer.firstName.

Tìm hiểu nội dung


Giới thiệu về chính sách Xác minh khoá API

Khi nhà phát triển đăng ký một ứng dụng trên Edge, Edge sẽ tự động tạo một cặp khoá bí mật và khoá người dùng. Bạn có thể xem cặp khoá bí mật và khoá người dùng của ứng dụng trong giao diện người dùng Edge hoặc truy cập vào cặp khoá bí mật và khoá đó từ API Edge.

Tại thời điểm đăng ký ứng dụng, nhà phát triển chọn một hoặc nhiều sản phẩm API để liên kết với ứng dụng, trong đó sản phẩm API là một tập hợp các tài nguyên có thể truy cập được thông qua proxy API. Sau đó, nhà phát triển sẽ chuyển khoá API (khoá người tiêu dùng) trong mọi yêu cầu đến API trong một sản phẩm API liên kết với ứng dụng. Xem phần Tổng quan về việc xuất bản để biết thêm thông tin.

Khoá API có thể được dùng làm mã xác thực hoặc để lấy mã truy cập OAuth. Trong OAuth, khoá API được gọi là "client id". Các tên này có thể sử dụng thay thế cho nhau. Xem trang chủ OAuth để biết thêm thông tin.

Edge tự động điền một tập hợp các biến luồng khi thực thi chính sách Xác minh khoá API. Hãy xem phần các biến Quy trình dưới đây để biết thêm thông tin.

Tham chiếu phần tử

Dưới đây là các phần tử và thuộc tính mà bạn có thể thiết lập trong chính sách này:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
</VerifyAPIKey>

Thuộc tính <VerifyAPIKey>

Ví dụ sau đây cho thấy các thuộc tính trên thẻ <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-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ử <APIKey>

Phần tử này chỉ định biến luồng chứa khoá API. Thông thường, máy khách gửi khoá API trong một tham số truy vấn, tiêu đề HTTP hoặc một tham số biểu mẫu. Ví dụ: nếu khoá được gửi trong một tiêu đề có tên x-apikey, thì khoá sẽ được tìm thấy trong biến: request.header.x-apikey

Mặc định Không áp dụng
Sự hiện diện Bắt buộc
Loại Chuỗi

Thuộc tính

Bảng sau đây mô tả các thuộc tính của phần tử <APIKey>

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

Tham chiếu đến biến chứa khoá API. Mỗi chính sách chỉ được phép có một vị trí.

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

Ví dụ

Trong những ví dụ này, khoá được truyền vào các tham số và tiêu đề có tên là x-apikey.

Dưới dạng tham số truy vấn:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

Dưới dạng tiêu đề HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

Dưới dạng tham số biểu mẫu HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

Giản đồ

Biến luồng

Khi thực thi chính sách Xác minh khoá API trên một khoá API hợp lệ, Edge sẽ điền một tập hợp các biến luồng. Các biến này có sẵn cho các chính sách hoặc mã được thực thi sau này trong luồng và thường được dùng để thực hiện quá trình xử lý tuỳ chỉnh dựa trên các thuộc tính của khoá API như tên ứng dụng, sản phẩm API dùng để cấp quyền cho khoá hoặc thuộc tính tuỳ chỉnh của khoá API.

Chính sách này điền sẵn một số loại biến luồng, bao gồm:

  • Giải pháp chung
  • Ứng dụng
  • Nhà phát triển
  • Công ty
  • Số liệu phân tích

Mỗi loại biến luồng có một tiền tố khác nhau. Tất cả các biến đều là đại lượng vô hướng, ngoại trừ những biến được chỉ định cụ thể dưới dạng mảng.

Biến luồng chung

Bảng sau đây liệt kê các biến luồng chung được điền theo chính sách Xác minh khoá API. Tất cả các biến này đều có tiền tố:

verifyapikey.{policy_name}

Ví dụ: verifyapikey.{policy_name}.client_id

Các biến có sẵn bao gồm:

Biến Nội dung mô tả
client_id Khoá người dùng (còn gọi là khoá API hoặc khoá ứng dụng) do ứng dụng yêu cầu cung cấp.
client_secret Thông tin mật của người dùng liên kết với khoá của người dùng.
redirection_uris Mọi URI chuyển hướng trong yêu cầu.
developer.app.id

Mã ứng dụng của nhà phát triển đưa ra yêu cầu.

developer.app.name Tên ứng dụng của ứng dụng của nhà phát triển đưa ra yêu cầu.
developer.id

Mã của nhà phát triển đã đăng ký làm chủ sở hữu của ứng dụng yêu cầu.

developer.{custom_attrib_name} Mọi thuộc tính tuỳ chỉnh bắt nguồn từ hồ sơ khoá ứng dụng.
DisplayName Giá trị thuộc tính <DisplayName> của chính sách.
failed Đặt thành "true" khi không xác thực được Khoá API.
{custom_app_attrib} Mọi thuộc tính tuỳ chỉnh bắt nguồn từ hồ sơ ứng dụng. Chỉ định tên của thuộc tính tuỳ chỉnh.
apiproduct.name* Tên của sản phẩm API được dùng để xác thực yêu cầu.
apiproduct.{custom_attrib_name}* Mọi thuộc tính tuỳ chỉnh bắt nguồn từ hồ sơ sản phẩm API.
apiproduct.developer.quota.limit* Giới hạn hạn mức được đặt trên sản phẩm API, nếu có.
apiproduct.developer.quota.interval* Khoảng hạn mức được đặt trên sản phẩm API, nếu có.
apiproduct.developer.quota.timeunit* Đơn vị thời gian hạn mức được đặt trên sản phẩm API, nếu có.
* Các biến sản phẩm API được điền tự động nếu các sản phẩm API được định cấu hình bằng môi trường, proxy và tài nguyên hợp lệ (lấy từ proxy.pathsuffix). Để biết hướng dẫn về cách thiết lập các sản phẩm API, hãy xem phần Sử dụng API quản lý Edge để phát hành API.

Biến luồng ứng dụng

Chính sách này đã điền sẵn các biến luồng sau chứa thông tin về ứng dụng. Tất cả các biến này đều có tiền tố:

verifyapikey.{policy_name}.app.

Ví dụ:

verifyapikey.{policy_name}.app.name

Các biến có sẵn bao gồm:

Biến Nội dung mô tả
name Tên ứng dụng.
id Mã của ứng dụng.
accessType Không được Apigee sử dụng.
callbackUrl URL gọi lại của ứng dụng. Thường chỉ dùng cho OAuth.
DisplayName Tên hiển thị của ứng dụng.
status Trạng thái của ứng dụng, chẳng hạn như "đã phê duyệt" hoặc "đã thu hồi".
apiproducts Một mảng chứa danh sách các sản phẩm API liên kết với ứng dụng.
appFamily Bất kỳ nhóm ứng dụng nào có chứa ứng dụng hoặc "mặc định".
appParentStatus Trạng thái của nguồn gốc của ứng dụng, chẳng hạn như "đang hoạt động" hoặc "không hoạt động"
appType Loại ứng dụng, có thể là "Công ty" hoặc "Nhà phát triển".
appParentId Mã của ứng dụng mẹ.
created_at Dấu ngày/giờ khi ứng dụng được tạo.
created_by Địa chỉ email của nhà phát triển đã tạo ứng dụng.
last_modified_at Dấu ngày/giờ khi ứng dụng được cập nhật lần gần đây nhất.
last_modified_by Địa chỉ email của nhà phát triển đã cập nhật ứng dụng lần gần đây nhất.
{app_custom_attributes} Thuộc tính tuỳ chỉnh bất kỳ của ứng dụng. Chỉ định tên của thuộc tính tuỳ chỉnh.

Biến quy trình dành cho nhà phát triển

Các biến luồng sau đây chứa thông tin về nhà phát triển được điền theo chính sách. Tất cả các biến này đều có tiền tố:

verifyapikey.{policy_name}.developer

Ví dụ:

verifyapikey.{policy_name}.developer.id

Các biến có sẵn bao gồm:

Biến Nội dung mô tả
id Trả về {org_name}@@@{developer_id}
userName Tên người dùng của nhà phát triển.
firstName Tên của nhà phát triển.
lastName Họ của nhà phát triển.
email Địa chỉ email của nhà phát triển.
status Trạng thái của nhà phát triển là đang hoạt động, không hoạt động hoặc sign_lock.
apps Một loạt ứng dụng liên kết với nhà phát triển.
created_at Dấu ngày/giờ khi nhà phát triển được tạo.
created_by Địa chỉ email của người dùng đã tạo nhà phát triển.
last_modified_at Dấu ngày/giờ khi nhà phát triển được sửa đổi lần gần đây nhất.
last_modified_by Địa chỉ email của người dùng đã sửa đổi nhà phát triển.
{developer_custom_attributes} Thuộc tính tuỳ chỉnh bất kỳ của nhà phát triển. Chỉ định tên của thuộc tính tuỳ chỉnh.
Company Tên của công ty (nếu có) liên kết với nhà phát triển.

Biến luồng công ty

Các biến luồng sau đây chứa thông tin về công ty được điền theo chính sách. Tất cả các biến này đều có tiền tố:

verifyapikey.{policy_name}.company

Ví dụ:

verifyapikey.{policy_name}.company.name

Các biến có sẵn bao gồm:

Biến Nội dung mô tả
name Tên công ty.
displayName Tên hiển thị của công ty.
id

Mã công ty.

apps Một mảng chứa danh sách các ứng dụng của công ty.
appOwnerStatus
Trạng thái của chủ sở hữu ứng dụng là đang hoạt động, không hoạt động hoặc sign_lock.
created_at Dấu ngày/giờ khi công ty được tạo.
created_by Địa chỉ email của người dùng đã tạo công ty.
last_modified_at Dấu ngày/giờ khi công ty được sửa đổi lần gần đây nhất.
last_modified_by Địa chỉ email của người dùng đã sửa đổi công ty lần gần đây nhất.
{company_custom_attributes} Bất kỳ thuộc tính tuỳ chỉnh nào của công ty. Chỉ định tên của thuộc tính tuỳ chỉnh.

Biến Analytics

Các biến sau đây được tự động điền sẵn trong Analytics khi chính sách Xác minh khoá API được thực thi cho khoá API hợp lệ. Các biến này chỉ được điền sẵn theo chính sách Xác minh khoá API và các chính sách OAuth.

Bạn có thể dùng các biến và giá trị này làm phương diện để xây dựng báo cáo Analytics nhằm nắm rõ các quy luật tiêu dùng của nhà phát triển và ứng dụng.

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

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.

Mã lỗi Trạng thái HTTP Nguyên nhân
keymanagement.service.CompanyStatusNotActive 401 Công ty liên kết với Ứng dụng của nhà phát triển có khoá API mà bạn đang sử dụng có trạng thái không hoạt động. Khi trạng thái của một Công ty được đặt thành không hoạt động, bạn không thể truy cập vào các nhà phát triển hoặc ứng dụng được liên kết với Công ty đó. Quản trị viên tổ chức có thể thay đổi trạng thái của một công ty bằng cách sử dụng API quản lý. Xem Đặt trạng thái của một công ty.
keymanagement.service.DeveloperStatusNotActive 401

Nhà phát triển tạo Ứng dụng dành cho nhà phát triển có khoá API mà bạn đang sử dụng sẽ có trạng thái không hoạt động. Khi trạng thái của một Nhà phát triển ứng dụng được đặt thành không hoạt động, thì mọi Ứng dụng của nhà phát triển do nhà phát triển đó tạo đều bị huỷ kích hoạt. Người dùng quản trị có quyền thích hợp (chẳng hạn như Quản trị viên tổ chức) có thể thay đổi trạng thái của nhà phát triển theo những cách sau:

keymanagement.service.invalid_client-app_not_approved 401 Ứng dụng của nhà phát triển liên kết với khoá API đã bị thu hồi. Ứng dụng đã bị thu hồi sẽ không thể truy cập vào bất kỳ sản phẩm API nào và không thể gọi bất kỳ API nào do Apigee Edge quản lý. Quản trị viên tổ chức có thể thay đổi trạng thái của Ứng dụng của nhà phát triển bằng API quản lý. Xem phần Phê duyệt hoặc thu hồi ứng dụng của nhà phát triển.
oauth.v2.FailedToResolveAPIKey 401 Chính sách này dự kiến sẽ tìm thấy khoá API trong một biến được chỉ định trong phần tử <APIKey> của chính sách. Lỗi này phát sinh khi biến dự kiến không tồn tại (không thể giải quyết).
oauth.v2.InvalidApiKey 401 Edge đã nhận được một khoá API nhưng khoá này không hợp lệ. Khi Edge tra cứu khoá trong cơ sở dữ liệu của mình, khoá này phải khớp chính xác với khoá đã gửi trong yêu cầu. Nếu API này từng hoạt động, hãy đảm bảo chưa tạo lại khoá. Nếu khoá đã được tạo lại, bạn sẽ thấy lỗi này nếu cố sử dụng khoá cũ. Để biết thông tin chi tiết, hãy xem phần Đăng ký ứng dụng và quản lý khoá API.
oauth.v2.InvalidApiKeyForGivenResource 401 Một khoá API mà Edge nhận được và khoá đó là hợp lệ; tuy nhiên, khoá này không khớp với khoá được phê duyệt trong Ứng dụng dành cho nhà phát triển liên kết với proxy API của bạn thông qua một Sản phẩm.

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.

Tên lỗi Nguyên nhân
SpecifyValueOrRefApiKey Chưa chỉ định giá trị hoặc khoá cho phần tử <APIKey>.

Biến lỗi

Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem Những điều bạn cần biết về lỗi chính sách.

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 "FailedToResolveAPIKey"
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.VK-VerifyAPIKey.failed = true

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

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

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

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

Chủ đề có liên quan