Chính sách Xác thực Cơ bản

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

Cho phép bạn sử dụng tính năng Xác thực cơ bản gọn nhẹ cho khả năng bảo mật ở bước cuối cùng. Chính sách này sẽ lấy tên người dùng và mật khẩu, Base64 mã hoá các thông tin này rồi ghi giá trị kết quả cho một biến. Giá trị thu được sẽ có dạng Basic Base64EncodedString. Bạn thường ghi giá trị này vào tiêu đề HTTP, chẳng hạn như tiêu đề Uỷ quyền.

Chính sách này cũng cho phép bạn giải mã thông tin xác thực lưu trữ trong chuỗi mã hoá Base64 thành tên người dùng và mật khẩu.

Video: Video này minh hoạ cách mã hoá base64 tên người dùng và bằng cách sử dụng chính sách Xác thực cơ bản.

Video: Video này minh hoạ cách giải mã tên người dùng được mã hoá base64 và bằng cách sử dụng chính sách Xác thực cơ bản.

Mẫu

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

Trong cấu hình chính sách mẫu ở trên, tên người dùng và mật khẩu sẽ được mã hoá bắt nguồn từ các biến do các thuộc tính ref chỉ định trên Phần tử <User><Password>. Các biến phải đặt trước khi chính sách này thực thi. Thông thường, các biến được điền bởi các giá trị đọc từ bản đồ khoá/giá trị. Xem Bản đồ giá trị chính Chính sách hoạt động.

Cấu hình này dẫn đến tiêu đề HTTP có tên Uỷ quyền, như được chỉ định bởi phần tử &lt;AssignTo&gt;, đang được thêm vào thông báo yêu cầu gửi đi gửi tới máy chủ phụ trợ:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Các giá trị <User><Password> được nối với nhau có dấu hai chấm trước khi mã hoá Base64.

Giả sử bạn có bản đồ khoá/giá trị với mục nhập sau:

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername"
  }, {
    "name" : "password",
    "value" : "MyPassword"
  } ],
  "name" : "BasicAuthCredentials"
}
      

Đính kèm các chính sách KeyValueMapOperations sau trước chính sách BasicAuthentication để có thể trích xuất các giá trị cho <User> và Phần tử <Password> từ kho khoá/giá trị rồi điền chúng vào biến credentials.usernamecredentials.password.

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
      
<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

Trong mẫu chính sách này, chính sách giải mã tên người dùng và mật khẩu từ Tiêu đề HTTP Authorization, như được chỉ định bởi phần tử &lt;Source&gt;. Base64 chuỗi mã hoá phải có dạng Basic Base64EncodedString.

Chính sách này ghi tên người dùng đã được giải mã vào biến request.header.username và mật khẩu đã giải mã vào biến request.header.password.


Giới thiệu về Chính sách xác thực cơ bản

Chính sách này có 2 chế độ hoạt động:

  • Mã hoá: Base64 mã hoá tên người dùng và mật khẩu được lưu trữ trong biến
  • Giải mã: Giải mã tên người dùng và mật khẩu từ Chuỗi được mã hoá Base64

Tên người dùng và mật khẩu thường được lưu trữ trong kho khoá/giá trị rồi được đọc từ kho khoá/giá trị trong thời gian chạy. Để biết thông tin chi tiết về cách sử dụng kho khoá/giá trị, hãy xem bài viết Hoạt động trên bản đồ giá trị khoá .

Tham chiếu phần tử

Tham chiếu phần tử mô tả các phần tử và thuộc tính của BasicAuthentication .

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source> 
</BasicAuthentication>

&lt;BasicAuthentication&gt; thuộc tính

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-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:

Thuộc tính 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ự.

(Không bắt buộc) Bạn có thể dùng phần tử <DisplayName> để gắn nhãn 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 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 chính sách không thành công. Điều này là dự kiến đối với hầu hết các chính sách.

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

false Không bắt buộc
enabled

Hãy đặt thành true để thực thi chính sách này.

Đặ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 luồng đó vẫn được liên kết với một luồng.

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

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

Không áp dụng

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

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

&lt;Operation&gt; phần tử

Xác định xem chính sách Base64 có mã hoá hay giải mã thông tin xác thực hay không.

<Operation>Encode</Operation>
Mặc định: Không áp dụng
Sự hiện diện: Bắt buộc
Loại:

Chuỗi.

Các giá trị hợp lệ bao gồm:

  • Mã hóa
  • Decode

&lt;IgnoreUnresolvedVariables&gt; phần tử

Khi bạn đặt thành true, chính sách này sẽ không báo lỗi nếu một biến không thể được đã được giải quyết. Khi được sử dụng trong bối cảnh của chính sách BasicAuthentication, chế độ cài đặt này thường được đặt vào false vì việc báo lỗi thường có lợi nếu tên người dùng hoặc không thể tìm thấy mật khẩu trong các biến được chỉ định.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Mặc định: đúng
Sự hiện diện: Không bắt buộc
Loại:

Boolean

&lt;User&gt; phần tử

  • Để mã hoá, hãy sử dụng phần tử <User> để chỉ định biến chứa tên người dùng. Các giá trị tên người dùng và mật khẩu được nối với một dấu hai chấm trước Mã hoá Base64.
  • Để giải mã, hãy chỉ định biến nơi ghi tên người dùng được giải mã.
<User ref="request.queryparam.username" /> 
Mặc định: Không áp dụng
Sự hiện diện: Bắt buộc
Loại:

Không áp dụng

Thuộc tính

Thuộc tính Mô tả Mặc định Sự hiện diện
tham chiếu

Biến mà chính sách có thể tự động đọc tên người dùng (mã hoá) hoặc ghi tên người dùng (giải mã).

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

&lt;Password&gt; phần tử

  • Để mã hoá, hãy sử dụng phần tử <Password> để chỉ định biến chứa mật khẩu đó.
  • Để giải mã, hãy chỉ định biến nơi mật khẩu đã giải mã được ghi.
<Password ref="request.queryparam.password" />
Mặc định: Không áp dụng
Sự hiện diện: Bắt buộc
Loại:

Không áp dụng

Thuộc tính

Thuộc tính Mô tả Mặc định Sự hiện diện
tham chiếu

Biến mà chính sách có thể tự động đọc mật khẩu (mã hoá) hoặc ghi từ đó mật khẩu (giải mã).

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

&lt;AssignTo&gt; phần tử

Chỉ định biến mục tiêu cần đặt bằng giá trị được mã hoá hoặc giải mã do biến này tạo ra .

Ví dụ sau đây cho biết rằng chính sách sẽ đặt Authorization tiêu đề của thư đến giá trị được tạo:

<AssignTo createNew="false">request.header.Authorization</AssignTo>
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

Thuộc tính Mô tả Mặc định Sự hiện diện
createNew Xác định xem chính sách có ghi đè biến hay không nếu biến đã được thiết lập.

Khi giá trị "false", việc gán cho biến chỉ xảy ra nếu biến đó là hiện không được đặt (null).

Khi giá trị là "true", hoạt động gán cho biến sẽ luôn diễn ra.

Bạn thường đặt thuộc tính này thành "false" (mặc định).

false Không bắt buộc

&lt;Source&gt; phần tử

Để giải mã, biến chứa chuỗi được mã hoá Base64, trong giá trị biểu mẫu Basic Base64EncodedString. Ví dụ: chỉ định request.header.Authorization, tương ứng với tiêu đề Uỷ quyền.

<Source>request.header.Authorization</Source>
Mặc định: Không áp dụng
Sự hiện diện: Bắt buộc đối với thao tác Giải mã.
Loại:

Không áp dụng

Biến luồng

Biến luồng sau được đặt khi chính sách không thành công:

  • BasicAuthentication.{policy_name}.failed (có giá trị là true)

Tham chiếu lỗi

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.basicauthentication.InvalidBasicAuthenticationSource 500 On a decode when the incoming Base64 encoded string does not contain a valid value or the header is malformed (e.g., does not start with "Basic").
steps.basicauthentication.UnresolvedVariable 500 The required source variables for the decode or encode are not present. This error can only occur if IgnoreUnresolvedVariables is false.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when Fix
UserNameRequired The <User> element must be present for the named operation.
PasswordRequired The <Password> element must be present for the named operation.
AssignToRequired The <AssignTo> element must be present for the named operation.
SourceRequired The <Source> element must be present for the named operation.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. BasicAuthentication.BA-Authenticate.failed = true

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

Example fault rule

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

Giản đồ

Chủ đề có liên quan

Bản đồ giá trị chính Chính sách hoạt động