訪問授權外掛

本文件描述了 Docker Engine 中可用的 Docker Engine 外掛。要檢視 Docker Engine 管理的外掛資訊，請參閱Docker Engine 外掛系統。

Docker 開箱即用的授權模型是全有或全無的。任何有權訪問 Docker 守護程序的使用者都可以執行任何 Docker 客戶端命令。對於使用 Docker Engine API 聯絡守護程序的呼叫者也是如此。如果需要更精細的訪問控制，可以建立授權外掛並將其新增到 Docker 守護程序配置中。透過使用授權外掛，Docker 管理員可以配置精細的訪問策略，以管理對 Docker 守護程序的訪問。

任何具有適當技能的人都可以開發授權外掛。這些技能最基本的是瞭解 Docker、理解 REST 和紮實的程式設計知識。本文件描述了授權外掛開發人員可用的架構、狀態和方法資訊。

基本原則

Docker 的外掛基礎設施透過使用通用 API 載入、刪除和與第三方元件通訊來擴充套件 Docker。訪問授權子系統就是利用此機制構建的。

使用此子系統，您無需重新構建 Docker 守護程序即可新增授權外掛。您可以將外掛新增到已安裝的 Docker 守護程序中。您確實需要重新啟動 Docker 守護程序才能新增新外掛。

授權外掛根據當前身份驗證上下文和命令上下文批准或拒絕向 Docker 守護程序發出的請求。身份驗證上下文包含所有使用者詳細資訊和身份驗證方法。命令上下文包含所有相關的請求資料。

授權外掛必須遵循Docker 外掛 API 中描述的規則。每個外掛都必須位於外掛發現部分描述的目錄中。

注意

縮寫 AuthZ 和 AuthN 分別表示授權和身份驗證。

預設使用者授權機制

如果Docker 守護程序中啟用了 TLS，預設使用者授權流會從證書主題名稱中提取使用者詳細資訊。也就是說，User 欄位設定為客戶端證書主題通用名稱，AuthenticationMethod 欄位設定為 TLS。

基本架構

您負責在 Docker 守護程序啟動時註冊您的外掛。您可以安裝多個外掛並將它們連結在一起。此鏈可以是有序的。對守護程序的每個請求都按順序透過鏈。只有當所有外掛都授予對資源的訪問許可權時，才授予訪問許可權。

當透過 CLI 或 Engine API 向 Docker 守護程序發出 HTTP 請求時，身份驗證子系統會將請求傳遞給已安裝的身份驗證外掛。請求包含使用者（呼叫者）和命令上下文。外掛負責決定是否允許或拒絕請求。

下面的序列圖描述了允許和拒絕授權流

傳送到外掛的每個請求都包含已認證使用者、HTTP 標頭以及請求/響應正文。僅使用者名稱稱和使用的身份驗證方法會傳遞給外掛。最重要的是，不會傳遞任何使用者憑據或令牌。最後，並非所有請求/響應正文都會發送到授權外掛。僅當 Content-Type 為 text/* 或 application/json 時，才會傳送這些請求/響應正文。

對於可能劫持 HTTP 連線（HTTP Upgrade）的命令，例如 exec，授權外掛僅在初始 HTTP 請求時呼叫。一旦外掛批准了該命令，授權就不再應用於流的其餘部分。具體來說，流資料不會傳遞給授權外掛。對於返回分塊 HTTP 響應的命令，例如 logs 和 events，只有 HTTP 請求會發送到授權外掛。

在請求/響應處理期間，某些授權流可能需要對 Docker 守護程序進行額外的查詢。為了完成這些流，外掛可以像普通使用者一樣呼叫守護程序 API。為了啟用這些額外的查詢，外掛必須為管理員提供配置適當身份驗證和安全策略的方法。

Docker 客戶端流程

要啟用和配置授權外掛，外掛開發人員必須支援本節中詳細介紹的 Docker 客戶端互動。

設定 Docker 守護程序

使用 --authorization-plugin=PLUGIN_ID 格式的專用命令列標誌啟用授權外掛。該標誌提供了一個 PLUGIN_ID 值。此值可以是外掛的套接字或規範檔案的路徑。授權外掛可以在不重啟守護程序的情況下載入。有關更多資訊，請參閱 dockerd 文件。

$ dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,...

Docker 的授權子系統支援多個 --authorization-plugin 引數。

呼叫授權命令（允許）

$ docker pull centos
<...>
f1b10cd84249: Pull complete
<...>

呼叫未經授權的命令（拒絕）

$ docker pull centos
<...>
docker: Error response from daemon: authorization denied by plugin PLUGIN_NAME: volumes are not allowed.

來自外掛的錯誤

$ docker pull centos
<...>
docker: Error response from daemon: plugin PLUGIN_NAME failed with error: AuthZPlugin.AuthZReq: Cannot connect to the Docker daemon. Is the docker daemon running on this host?.

API 模式和實現

除了 Docker 的標準外掛註冊方法外，每個外掛都應實現以下兩種方法

• /AuthZPlugin.AuthZReq 此授權請求方法在 Docker 守護程序處理客戶端請求之前呼叫。

• /AuthZPlugin.AuthZRes 此授權響應方法在 Docker 守護程序將響應返回給客戶端之前呼叫。

/AuthZPlugin.AuthZReq

請求

{
    "User":              "The user identification",
    "UserAuthNMethod":   "The authentication method used",
    "RequestMethod":     "The HTTP method",
    "RequestURI":        "The HTTP request URI",
    "RequestBody":       "Byte array containing the raw HTTP request body",
    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string "
}

響應

{
    "Allow": "Determined whether the user is allowed or not",
    "Msg":   "The authorization message",
    "Err":   "The error message if things go wrong"
}

/AuthZPlugin.AuthZRes

請求

{
    "User":              "The user identification",
    "UserAuthNMethod":   "The authentication method used",
    "RequestMethod":     "The HTTP method",
    "RequestURI":        "The HTTP request URI",
    "RequestBody":       "Byte array containing the raw HTTP request body",
    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string",
    "ResponseBody":      "Byte array containing the raw HTTP response body",
    "ResponseHeader":    "Byte array containing the raw HTTP response header as a map[string][]string",
    "ResponseStatusCode":"Response status code"
}

響應

{
   "Allow":              "Determined whether the user is allowed or not",
   "Msg":                "The authorization message",
   "Err":                "The error message if things go wrong"
}

請求授權

每個外掛必須支援兩種請求授權訊息格式，一種是從守護程序到外掛，然後是從外掛到守護程序。下表詳細說明了每條訊息中預期包含的內容。

守護程序 -> 外掛

外掛 -> 守護程序

響應授權

外掛必須支援兩種授權訊息格式，一種是從守護程序到外掛，然後是從外掛到守護程序。下表詳細說明了每條訊息中預期包含的內容。

守護程序 -> 外掛

外掛 -> 守護程序