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