1. docker
  2. Commit 630f695fb1c26ffba03df1cb5059bf592df44e81
Browse code

Adding authorization subsystem documentation

Signed-off-by: Dima Stopel <dima@twistlock.com>

Dima Stopel authored on 2015/11/04 22:49:53
Showing 2 changed files
docs/extend/authorization.md
History View file @ 630f695
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,119 @@
0 
+<!--[metadata]>
1 
+title = "Access authorization plugin"
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 
+[menu.main]
5 
+parent = "mn_extend"
6 
+weight = -1
7 
+<![end-metadata]-->
8 
+
9 
+
10 
+# Access authorization
11 
+
12 
+By default Docker’s authorization model is all or nothing. Anyone who has access to the Docker daemon has the ability to run any Docker command. Authorization plugins enable creating granular access policies for managing access to Docker daemon.
13 
+
14 
+## Basic principles
15 
+
16 
+* The authorization sub-system is based on Docker's [Plugin API](http://docs.docker.com/engine/extend/plugin_api), so that anyone could add / develop an authorization plug-in. It is possible to add a plug-in to a deployed Docker daemon without the need to rebuild the daemon. Daemon restart is required.
17 
+
18 
+* The authorization sub-system enables approving or denying requests to the Docker daemon based on the current user and command context, where the authentication context contains all user details and the authentication method, and the command context contains all the relevant request data.
19 
+
20 
+* The authorization sub-system enables approving or denying the response from the Docker daemon based on the current user and the command context.
21 
+
22 
+## Basic architecture
23 
+
24 
+Authorization is integrated into Docker daemon by enabling external authorization plug-ins registration as part of the daemon stratup. Each plug-in will receive user's information (retrieved using the authentication sub-system) and HTTP request information and decide whether to allow or deny the request. Plugins can be chained together and only in case where all plug-ins allow accessing the resource, the is access granted.
25 
+
26 
+Recently Docker introduced a new extendability mechanism called [plug-in infrastructure](http://docs.docker.com/engine/extend/plugin_api), which enables extending Docker by dynamically loading, removing and communicating with third-party components using a generic, easily extendable, API. The authorization sub-system was build using this mechanism.
27 
+
28 
+To enable full extendability, each plugin receives the authenticated user name, the request context including the user, HTTP headers, and the request/response body. No authentication information will be passed to the authorization plug-in except for: 1) user name, and  2) authentication method that was used. Specifically, no user credentials or tokens will be passed. The request / response bodies will be sent to the plugin only in case the Content-Type is either `text/*` or `application/json`.
29 
+
30 
+For commands that involve the hijacking of the HTTP connection (HTTP Upgrade), such as `exec`, the authorization plugins will only be called for the initial HTTP requests, once the commands are approved, authorization will not be applied to the rest of the flow. Specifically, the streaming data will not be passed to the authorization plugins. For commands that return chunked HTTP response, such as `logs` and `events`, only the HTTP request will be sent to the authorization plug-ins as well.
31 
+
32 
+During request / response processing, some authorization plugins flows might require performing additional queries to the docker daemon. To complete such a flows plugins can call the daemon API similar to the regular user, which means the plugin admin will have to configure proper authentication and security policies.
33 
+
34 
+## API schema
35 
+
36 
+In addition to the standard plugin registration method, each plugin should implement the following two methods:
37 
+
38 
+`/AuthzPlugin.AuthZReq` The authorize request method, which is called before Docker daemon processes the client request.
39 
+
40 
+`/AuthzPlugin.AuthZRes` The authorize response method, which is called before the response is returned from Docker daemon to the client.
41 
+
42 
+
43 
+### Request authorization
44 
+#### Daemon -> Plugin
45 
+
46 
+Name                   | Type              | Description
47 
+-----------------------|-------------------|-------------------------------------------------------
48 
+User                   | string            | The user identification
49 
+Authentication method  | string            | The authentication method used
50 
+Request method         | enum              | The HTTP method (GET/DELETE/POST)
51 
+Request URI            | string            | The HTTP request URI including API version (e.g., v.1.17/containers/json)
52 
+Request headers        | map[string]string | Request headers as key value pairs (without the authorization header)
53 
+Request body           | []byte            | Raw request body
54 
+
55 
+
56 
+#### Plugin -> Daemon
57 
+
58 
+Name    | Type   | Description
59 
+--------|--------|----------------------------------------------------------------------------------
60 
+Allow   | bool   | Boolean value indicating whether the request is allowed or denied
61 
+Message | string | Authorization message (will be returned to the client in case the access is denied)
62 
+
63 
+### Response authorization
64 
+#### Daemon -> Plugin
65 
+
66 
+
67 
+Name                    | Type              | Description
68 
+----------------------- |------------------ |----------------------------------------------------
69 
+User                    | string            | The user identification
70 
+Authentication method   | string            | The authentication method used
71 
+Request method          | string            | The HTTP method (GET/DELETE/POST)
72 
+Request URI             | string            | The http request URI including API version (e.g., v.1.17/containers/json)
73 
+Request headers         | map[string]string | Request headers as key value pairs (without the authorization header)
74 
+Request body            | []byte            | Raw request body
75 
+Response status code    | int               | Status code from the docker daemon
76 
+Response headers        | map[string]string | Response headers as key value pairs
77 
+Response body           | []byte            | Raw docker daemon response body
78 
+
79 
+
80 
+#### Plugin -> Daemon
81 
+
82 
+Name    | Type   | Description
83 
+--------|--------|----------------------------------------------------------------------------------
84 
+Allow   | bool   | Boolean value indicating whether the response is allowed or denied
85 
+Message | string | Authorization message (will be returned to the client in case the access is denied)
86 
+
87 
+## UX flows
88 
+
89 
+### Setting up docker daemon
90 
+
91 
+Authorization plugins are enabled with a dedicated command line argument. The argument contains a comma separated list of the plugin names, which should be the same as the plugin’s socket or spec file.
92 
+```
93 
+$ docker -d authz-plugins=plugin1,plugin2,...
94 
+```
95 
+
96 
+### Calling authorized command (allow)
97 
+
98 
+No impact on command output
99 
+```
100 
+$ docker pull centos
101 
+...
102 
+f1b10cd84249: Pull complete
103 
+...
104 
+```
105 
+
106 
+### Calling unauthorized command (deny)
107 
+
108 
+```
109 
+$ docker pull centos
110 
+…
111 
+Authorization failed. Pull command for user 'john_doe' is denied by authorization plugin 'ACME' with message ‘[ACME] User 'john_doe' is not allowed to perform the pull command’
112 
+```
113 
+
114 
+
115 
+
116 
+
docs/reference/commandline/daemon.md
History View file @ 630f695
... ... 
@@ -17,6 +17,7 @@ weight = -1
17 17
18 18 
     Options:
19 19 
       --api-cors-header=""                   Set CORS headers in the remote API
20 
+      --authz-plugins=[]                     Set authorization plugins to load
20 21 
       -b, --bridge=""                        Attach containers to a network bridge
21 22 
       --bip=""                               Specify network bridge IP
22 23 
       -D, --debug=false                      Enable debug mode
... ... 
@@ -601,6 +602,12 @@ The currently supported cluster store options are:
601 601 
     private key is used as the client key for communication with the
602 602 
     Key/Value store.
603 603
604 
+## Access authorization
605 
+
606 
+The `--authz-plugins` option instructs the daemon to load the authorization plugins. Authorization plugins must follow the rules described in [Docker Plugin API](http://docs.docker.com/engine/extend/plugin_api/) and reside within directories described under the [plugin discovery](http://docs.docker.com/engine/extend/plugin_api/#plugin-discovery) section. The option accepts a set of plugin names to load, for example `--authz-plugins=plugin1,plugin2`.
607 
+
608 
+
609 
+More information about how to create an authorization plugin can be found under the [authorization](https://docs.docker.com/engine/extend/authorization/) section in the user guide.
604 610
605 611 
 ## Miscellaneous options
606 612