github.com/pwn-term/docker@v0.0.0-20210616085119-6e977cce2565/cli/docs/extend/plugins_authorization.md

github.com/pwn-term/docker@v0.0.0-20210616085119-6e977cce2565/cli/docs/extend/plugins_authorization.md (about)

1 ---
2 description: "How to create authorization plugins to manage access control to your Docker daemon."
3 keywords: "security, authorization, authentication, docker, documentation, plugin, extend"
4 redirect_from:
5 - "/engine/extend/authorization/"
6 ---
7
8 
16
17 # Access authorization plugin
18
19 This document describes the Docker Engine plugins generally available in Docker
20 Engine. To view information on plugins managed by Docker Engine,
21 refer to [Docker Engine plugin system](index.md).
22
23 Docker's out-of-the-box authorization model is all or nothing. Any user with
24 permission to access the Docker daemon can run any Docker client command. The
25 same is true for callers using Docker's Engine API to contact the daemon. If you
26 require greater access control, you can create authorization plugins and add
27 them to your Docker daemon configuration. Using an authorization plugin, a
28 Docker administrator can configure granular access policies for managing access
29 to the Docker daemon.
30
31 Anyone with the appropriate skills can develop an authorization plugin. These
32 skills, at their most basic, are knowledge of Docker, understanding of REST, and
33 sound programming knowledge. This document describes the architecture, state,
34 and methods information available to an authorization plugin developer.
35
36 ## Basic principles
37
38 Docker's [plugin infrastructure](plugin_api.md) enables
39 extending Docker by loading, removing and communicating with
40 third-party components using a generic API. The access authorization subsystem
41 was built using this mechanism.
42
43 Using this subsystem, you don't need to rebuild the Docker daemon to add an
44 authorization plugin. You can add a plugin to an installed Docker daemon. You do
45 need to restart the Docker daemon to add a new plugin.
46
47 An authorization plugin approves or denies requests to the Docker daemon based
48 on both the current authentication context and the command context. The
49 authentication context contains all user details and the authentication method.
50 The command context contains all the relevant request data.
51
52 Authorization plugins must follow the rules described in [Docker Plugin API](plugin_api.md).
53 Each plugin must reside within directories described under the
54 [Plugin discovery](plugin_api.md#plugin-discovery) section.
55
56 > **Note**
57 >
58 > The abbreviations `AuthZ` and `AuthN` mean authorization and authentication
59 > respectively.
60
61 ## Default user authorization mechanism
62
63 If TLS is enabled in the [Docker daemon](https://docs.docker.com/engine/security/https/), the default user authorization flow extracts the user details from the certificate subject name.
64 That is, the `User` field is set to the client certificate subject common name, and the `AuthenticationMethod` field is set to `TLS`.
65
66 ## Basic architecture
67
68 You are responsible for registering your plugin as part of the Docker daemon
69 startup. You can install multiple plugins and chain them together. This chain
70 can be ordered. Each request to the daemon passes in order through the chain.
71 Only when all the plugins grant access to the resource, is the access granted.
72
73 When an HTTP request is made to the Docker daemon through the CLI or via the
74 Engine API, the authentication subsystem passes the request to the installed
75 authentication plugin(s). The request contains the user (caller) and command
76 context. The plugin is responsible for deciding whether to allow or deny the
77 request.
78
79 The sequence diagrams below depict an allow and deny authorization flow:
80
81 ![Authorization Allow flow](images/authz_allow.png)
82
83 ![Authorization Deny flow](images/authz_deny.png)
84
85 Each request sent to the plugin includes the authenticated user, the HTTP
86 headers, and the request/response body. Only the user name and the
87 authentication method used are passed to the plugin. Most importantly, no user
88 credentials or tokens are passed. Finally, not all request/response bodies
89 are sent to the authorization plugin. Only those request/response bodies where
90 the `Content-Type` is either `text/*` or `application/json` are sent.
91
92 For commands that can potentially hijack the HTTP connection (`HTTP
93 Upgrade`), such as `exec`, the authorization plugin is only called for the
94 initial HTTP requests. Once the plugin approves the command, authorization is
95 not applied to the rest of the flow. Specifically, the streaming data is not
96 passed to the authorization plugins. For commands that return chunked HTTP
97 response, such as `logs` and `events`, only the HTTP request is sent to the
98 authorization plugins.
99
100 During request/response processing, some authorization flows might
101 need to do additional queries to the Docker daemon. To complete such flows,
102 plugins can call the daemon API similar to a regular user. To enable these
103 additional queries, the plugin must provide the means for an administrator to
104 configure proper authentication and security policies.
105
106 ## Docker client flows
107
108 To enable and configure the authorization plugin, the plugin developer must
109 support the Docker client interactions detailed in this section.
110
111 ### Setting up Docker daemon
112
113 Enable the authorization plugin with a dedicated command line flag in the
114 `--authorization-plugin=PLUGIN_ID` format. The flag supplies a `PLUGIN_ID`
115 value. This value can be the plugin’s socket or a path to a specification file.
116 Authorization plugins can be loaded without restarting the daemon. Refer
117 to the [`dockerd` documentation](../reference/commandline/dockerd.md#configuration-reloading) for more information.
118
119 ```bash
120 $ dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,...
121 ```
122
123 Docker's authorization subsystem supports multiple `--authorization-plugin` parameters.
124
125 ### Calling authorized command (allow)
126
127 ```bash
128 $ docker pull centos
129 ...
130 f1b10cd84249: Pull complete
131 ...
132 ```
133
134 ### Calling unauthorized command (deny)
135
136 ```bash
137 $ docker pull centos
138 ...
139 docker: Error response from daemon: authorization denied by plugin PLUGIN_NAME: volumes are not allowed.
140 ```
141
142 ### Error from plugins
143
144 ```bash
145 $ docker pull centos
146 ...
147 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?.
148 ```
149
150 ## API schema and implementation
151
152 In addition to Docker's standard plugin registration method, each plugin
153 should implement the following two methods:
154
155 * `/AuthZPlugin.AuthZReq` This authorize request method is called before the Docker daemon processes the client request.
156
157 * `/AuthZPlugin.AuthZRes` This authorize response method is called before the response is returned from Docker daemon to the client.
158
159 #### /AuthZPlugin.AuthZReq
160
161 **Request**:
162
163 ```json
164 {
165 "User": "The user identification",
166 "UserAuthNMethod": "The authentication method used",
167 "RequestMethod": "The HTTP method",
168 "RequestURI": "The HTTP request URI",
169 "RequestBody": "Byte array containing the raw HTTP request body",
170 "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string "
171 }
172 ```
173
174 **Response**:
175
176 ```json
177 {
178 "Allow": "Determined whether the user is allowed or not",
179 "Msg": "The authorization message",
180 "Err": "The error message if things go wrong"
181 }
182 ```
183 #### /AuthZPlugin.AuthZRes
184
185 **Request**:
186
187 ```json
188 {
189 "User": "The user identification",
190 "UserAuthNMethod": "The authentication method used",
191 "RequestMethod": "The HTTP method",
192 "RequestURI": "The HTTP request URI",
193 "RequestBody": "Byte array containing the raw HTTP request body",
194 "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string",
195 "ResponseBody": "Byte array containing the raw HTTP response body",
196 "ResponseHeader": "Byte array containing the raw HTTP response header as a map[string][]string",
197 "ResponseStatusCode":"Response status code"
198 }
199 ```
200
201 **Response**:
202
203 ```json
204 {
205 "Allow": "Determined whether the user is allowed or not",
206 "Msg": "The authorization message",
207 "Err": "The error message if things go wrong"
208 }
209 ```
210
211 ### Request authorization
212
213 Each plugin must support two request authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.
214
215 #### Daemon -> Plugin
216
217 Name | Type | Description
218 -----------------------|-------------------|-------------------------------------------------------
219 User | string | The user identification
220 Authentication method | string | The authentication method used
221 Request method | enum | The HTTP method (GET/DELETE/POST)
222 Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json)
223 Request headers | map[string]string | Request headers as key value pairs (without the authorization header)
224 Request body | []byte | Raw request body
225
226
227 #### Plugin -> Daemon
228
229 Name | Type | Description
230 --------|--------|----------------------------------------------------------------------------------
231 Allow | bool | Boolean value indicating whether the request is allowed or denied
232 Msg | string | Authorization message (will be returned to the client in case the access is denied)
233 Err | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information)
234
235 ### Response authorization
236
237 The plugin must support two authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.
238
239 #### Daemon -> Plugin
240
241
242 Name | Type | Description
243 ----------------------- |------------------ |----------------------------------------------------
244 User | string | The user identification
245 Authentication method | string | The authentication method used
246 Request method | string | The HTTP method (GET/DELETE/POST)
247 Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json)
248 Request headers | map[string]string | Request headers as key value pairs (without the authorization header)
249 Request body | []byte | Raw request body
250 Response status code | int | Status code from the docker daemon
251 Response headers | map[string]string | Response headers as key value pairs
252 Response body | []byte | Raw docker daemon response body
253
254
255 #### Plugin -> Daemon
256
257 Name | Type | Description
258 --------|--------|----------------------------------------------------------------------------------
259 Allow | bool | Boolean value indicating whether the response is allowed or denied
260 Msg | string | Authorization message (will be returned to the client in case the access is denied)
261 Err | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information)