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

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. info

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, chỉ cho phép các ứ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 đều 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

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

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

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

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

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

<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>

<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>

verifyapikey.{policy_name}

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á người dùng và khoá bí mật. Bạn có thể xem cặp khoá và bí mật của người dùng ứng dụng trong Giao diện người dùng Edge hoặc truy cập vào cặp khoá và bí mật đó từ API Edge.

Tại thời điểm đăng ký ứng dụng, nhà phát triển sẽ 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 tài nguyên có thể truy cập thông qua các proxy API. Sau đó, nhà phát triển sẽ truyền khoá API (khoá người dùng) trong mỗi yêu cầu đến một API trong sản phẩm API được liên kết với ứng dụng. Hãy xem phần Tổng quan về việc xuất bản để biết thêm thông tin.

Bạn có thể dùng khoá API làm mã thông báo xác thực hoặc dùng để lấy mã truy cập OAuth. Trong OAuth, khoá API được gọi là "mã ứng dụng". Bạn có thể sử dụng hai tên này thay thế cho nhau. Hãy xem Trang chủ OAuth để biết thêm thông tin.

Edge sẽ 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 Các biến của quy trình bên dưới để biết thêm thông tin.

Tham chiếu phần tử

Sau đây là các phần tử và thuộc tính mà bạn có thể định cấu hình trên 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ả 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ử <APIKey>

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

Thuộc tính

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

Ví dụ

Trong các ví dụ này, khoá được truyền trong các tham số và một 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 chính sách Xác minh khoá API được thực thi trên một khoá API hợp lệ, Edge sẽ điền sẵ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 trong luồng và thường được dùng để thực hiện quy trình xử lý tuỳ chỉnh dựa trên các thuộc tính của khoá API, chẳng hạn như tên ứng dụng, sản phẩm API dùng để uỷ quyền khoá hoặc cá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ố riêng. Tất cả các biến đều là vô hướng, ngoại trừ những biến được chỉ định cụ thể là mảng.

Biến quy trình chung

Bảng sau đây liệt kê các biến luồng chung do chính sách Xác minh khoá API điền sẵn. 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 luồng ứng dụng

Chính sách sẽ điền sẵn các biến luồng sau đây 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 luồng của nhà phát triển

Chính sách sẽ điền sẵn các biến luồng sau đây chứa thông tin về nhà phát triển. 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 luồng công ty

Các biến luồng sau đây chứa thông tin về công ty do chính sách điền sẵn. 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:

Các biến Analytics

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

Bạn có thể sử dụng các biến và giá trị này làm phương diện để tạo báo cáo Analytics nhằm nắm được thông tin về các mẫu sử 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 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 xảy ra lỗi thời gian chạy. Để biết thêm thông tin, 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í 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