访问授权插件

本文档描述了 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 Plugin API 中描述的规则。每个插件必须位于插件发现部分描述的目录中。

注意

缩写 AuthZ 和 AuthN 分别代表授权 (authorization) 和身份验证 (authentication)。

默认用户授权机制

如果在 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"
}

请求授权

每个插件必须支持两种请求授权消息格式，一种从守护进程到插件，另一种从插件到守护进程。下表详细说明了每种消息中期望的内容。

守护进程 -> 插件

插件 -> 守护进程

响应授权

插件必须支持两种授权消息格式，一种从守护进程到插件，另一种从插件到守护进程。下表详细说明了每种消息中期望的内容。

守护进程 -> 插件

插件 -> 守护进程