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