github.com/olljanat/moby@v1.13.1/docs/extend/plugins_authorization.md

github.com/olljanat/moby@v1.13.1/docs/extend/plugins_authorization.md (about)

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