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