1. docker
  2. Commit 8cc0892269fb532f117aadc0e8acf7a173fe4e1b
Browse code

Fixing documentation according to comments by @moxiegirl and @thaJeztah

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

Dima Stopel authored on 2015/12/08 21:54:33
Showing 9 changed files
daemon/config.go
History View file @ 8cc0892
... ... 
@@ -55,7 +55,7 @@ type CommonConfig struct {
55 55 
 // from the command-line.
56 56 
 func (config *Config) InstallCommonFlags(cmd *flag.FlagSet, usageFn func(string) string) {
57 57 
 	cmd.Var(opts.NewListOptsRef(&config.GraphOptions, nil), []string{"-storage-opt"}, usageFn("Set storage driver options"))
58 
-	cmd.Var(opts.NewListOptsRef(&config.AuthZPlugins, nil), []string{"-authz-plugins"}, usageFn("List of authorization plugins by order of evaluation"))
58 
+	cmd.Var(opts.NewListOptsRef(&config.AuthZPlugins, nil), []string{"-authz-plugins"}, usageFn("List authorization plugins in order from first evaluator to last"))
59 59 
 	cmd.Var(opts.NewListOptsRef(&config.ExecOptions, nil), []string{"-exec-opt"}, usageFn("Set exec driver options"))
60 60 
 	cmd.StringVar(&config.Pidfile, []string{"p", "-pidfile"}, defaultPidFile, usageFn("Path to use for daemon PID file"))
61 61 
 	cmd.StringVar(&config.Root, []string{"g", "-graph"}, defaultGraph, usageFn("Root of the Docker runtime"))
docs/extend/authorization.md
History View file @ 8cc0892
... ... 
@@ -10,40 +10,192 @@ weight = -1
10 10 
 <![end-metadata]-->
11 11
12 12
13 
-# Access authorization
13 
+# Create an authorization plugin
14 14
15 
-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.
15 
+Docker’s out-of-the-box authorization model is all or nothing. Any user with
16 
+permission to access to 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.
16 27
17 28 
 ## Basic principles
18 29
19 
-* 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.
30 
+Docker's [plugin infrastructure](http://docs.docker.com/engine/extend/plugin_api) enables
31 
+extending Docker by dynamically 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 a installed Docker daemon. You do
37 
+need to restart the Docker daemon to add a new plugin.
20 38
21 
-* 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.
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.
22 43
23 
-* The authorization sub-system enables approving or denying the response from the Docker daemon based on the current user and the command context.
44 
+Authorization plugins must follow the rules described in [Docker Plugin API](http://docs.docker.com/engine/extend/plugin_api/).
45 
+Each plugin must reside within directories described under the [plugin discovery](http://docs.docker.com/engine/extend/plugin_api/#plugin-discovery)
46 
+section.
24 47
25 48 
 ## Basic architecture
26 49
27 
-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.
50 
+You are responsible for registering your plugin as part of the Docker daemon
51 
+startup. You can install multiple plugins and chain them together. This chain
52 
+can be ordered. Each request to the daemon passes in order through the chain.
53 
+Only when all the plugins grant access to the resource, is the access granted.
54 
+
55 
+When an HTTP request is made to the Docker daemon through the CLI or via the
56 
+remote API, the authentication subsystem passes the request to the installed
57 
+authentication plugin(s). The request contains the user (caller) and command
58 
+context. The plugin is responsible for deciding whether to allow or deny the
59 
+request.
60 
+
61 
+Below please find tow sequence diagrams describing the *allow* and *deny*
62 
+authorization flows:
63 
+
64 
+![Bad Address](images/authz_allow.png)
65 
+
66 
+![Bad Address](images/authz_deny.png)
28 67
29 
-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.
68 
+Each request sent to the plugin includes the authenticated user, the HTTP
69 
+headers, and the request/response body. Only the user name and the
70 
+authentication method used are passed to the plugin. Most importantly, no user
71 
+credentials or tokens are passed. Finally, not all request/response bodies
72 
+are sent to the authorization plugin. Only those request/response bodies where
73 
+the `Content-Type` is either `text/*` or `application/json` are sent.
30 74
31 
-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`.
75 
+For commands that can potentially the hijack the HTTP connection (`HTTP
76 
+Upgrade`), such as `exec`, the authorization plugin are only called for the
77 
+initial HTTP requests. Once the plugin approves the command, authorization is
78 
+not applied to the rest of the flow. Specifically, the streaming data is not
79 
+passed to the authorization plugins. For commands that return chunked HTTP
80 
+response, such as `logs` and `events`, only the HTTP request are sent to the
81 
+authorization plugins as well.
32 82
33 
-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.
83 
+During request/response processing, some authorization plugins flows might
84 
+need to do additional queries to the Docker daemon. To complete such flows,
85 
+plugins can call the daemon API similar to a regular user. To enable these
86 
+additional queries, the plugin must provide the means for an administrator to
87 
+configure proper authentication and security policies.
34 88
35 
-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.
89 
+## Docker client flows
36 90
37 
-## API schema
91 
+To enable and configure the authorization plugin, the plugin developer must support the Docker client interactions detailed in this section.
38 92
39 
-In addition to the standard plugin registration method, each plugin should implement the following two methods:
93 
+### Setting up Docker daemon
94 
+
95 
+Enable the authorization plugin with a dedicated command line flag in the
96 
+`--authz-plugins=PLUGIN_ID` format. The flag supplies a `PLUGIN_ID` value.
97 
+This value can be the plugin’s socket or a path to a specification file.
98 
+
99 
+```
100 
+$ docker daemon --authz-plugins=plugin1 --auth-plugins=plugin2,...
101 
+```
40 102
41 
-`/AuthzPlugin.AuthZReq` The authorize request method, which is called before Docker daemon processes the client request.
103 
+Docker's authorization subsystem supports multiple `--authz-plugin` parameters.
42 104
43 
-`/AuthzPlugin.AuthZRes` The authorize response method, which is called before the response is returned from Docker daemon to the client.
105 
+### Calling authorized command (allow)
106 
+
107 
+Your plugin must support calling the `allow` command to authorize a command. This call does not impact Docker's command line.
108 
+
109 
+```
110 
+$ docker pull centos
111 
+...
112 
+f1b10cd84249: Pull complete
113 
+...
114 
+```
115 
+
116 
+### Calling unauthorized command (deny)
44 117
118 
+Your plugin must support calling the `deny` command to report on the outcome of a plugin interaction. This call returns messages to Docker's command line informing the user of the outcome of each call.
119 
+
120 
+```
121 
+$ docker pull centos
122 
+…
123 
+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’
124 
+```
125 
+
126 
+Where multiple authorization plugins are installed, multiple messages are expected.
127 
+
128 
+
129 
+## API schema and implementation
130 
+
131 
+Sample code for a typical plugin can be found here [ADD LINK]. In addition to Docker's standard plugin registration method, each plugin should implement the following two methods:
132 
+
133 
+* `/AuthzPlugin.AuthZReq` This authorize request method is called before the Docker daemon processes the client request.
134 
+
135 
+* `/AuthzPlugin.AuthZRes` This authorize response method is called before the response is returned from Docker daemon to the client.
136 
+
137 
+#### /AuthzPlugin.AuthZReq
138 
+
139 
+**Request**:
140 
+
141 
+```
142 
+{
143 
+    "User":              "The user identification"
144 
+    "UserAuthNMethod":   "The authentication method used"
145 
+    "RequestMethod":     "The HTTP method"
146 
+    "RequestUri":        "The HTTP request URI"
147 
+    "RequestBody":       "Byte array containing the raw HTTP request body"
148 
+    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string "
149 
+    "RequestStatusCode": "Request status code"
150 
+}
151 
+```
152 
+
153 
+**Response**:
154 
+
155 
+```
156 
+{
157 
+    "Allow" : "Determined whether the user is allowed or not"
158 
+    "Msg":    "The authorization message"
159 
+}
160 
+```
161 
+
162 
+#### /AuthzPlugin.AuthZRes
163 
+
164 
+**Request**:
165 
+```
166 
+{
167 
+    "User":              "The user identification"
168 
+    "UserAuthNMethod":   "The authentication method used"
169 
+    "RequestMethod":     "The HTTP method"
170 
+    "RequestUri":        "The HTTP request URI"
171 
+    "RequestBody":       "Byte array containing the raw HTTP request body"
172 
+    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string"
173 
+    "RequestStatusCode": "Request status code"
174 
+    "ResponseBody":      "Byte array containing the raw HTTP response body"
175 
+    "ResponseHeader":    "Byte array containing the raw HTTP response header as a map[string][]string"
176 
+    "ResponseStatusCode":"Response status code"
177 
+}
178 
+```
179 
+
180 
+**Response**:
181 
+```
182 
+{
183 
+   "Allow" :               "Determined whether the user is allowed or not"
184 
+   "Msg":                  "The authorization message"
185 
+   "ModifiedBody":         "Byte array containing a modified body of the raw HTTP body (or nil if no changes required)"
186 
+   "ModifiedHeader":       "Byte array containing a modified header of the HTTP response (or nil if no changes required)"
187 
+   "ModifiedStatusCode":   "int containing the modified version of the status code (or 0 if not change is required)"
188 
+}
189 
+```
190 
+
191 
+The modified response enables the authorization plugin to manipulate the content
192 
+of the HTTP response. In case of more than one plugin, each subsequent plugin
193 
+receives a response (optionally) modified by a previous plugin.
194 
+
195 
+### Request authorization
196 
+
197 
+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.
45 198
46 
-### Request authorization
47 199 
 #### Daemon -> Plugin
48 200
49 201 
 Name                   | Type              | Description
... ... 
@@ -63,7 +215,10 @@ Name    | Type   | Description
63 63 
 Allow   | bool   | Boolean value indicating whether the request is allowed or denied
64 64 
 Message | string | Authorization message (will be returned to the client in case the access is denied)
65 65
66 
-### Response authorization
66 
+### Response authorization
67 
+
68 
+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.
69 
+
67 70 
 #### Daemon -> Plugin
68 71
69 72
... ... 
@@ -72,7 +227,7 @@ Name                    | Type              | Description
72 72 
 User                    | string            | The user identification
73 73 
 Authentication method   | string            | The authentication method used
74 74 
 Request method          | string            | The HTTP method (GET/DELETE/POST)
75 
-Request URI             | string            | The http request URI including API version (e.g., v.1.17/containers/json)
75 
+Request URI             | string            | The HTTP request URI including API version (e.g., v.1.17/containers/json)
76 76 
 Request headers         | map[string]string | Request headers as key value pairs (without the authorization header)
77 77 
 Request body            | []byte            | Raw request body
78 78 
 Response status code    | int               | Status code from the docker daemon
... ... 
@@ -85,36 +240,4 @@ Response body           | []byte            | Raw docker daemon response body
85 85 
 Name    | Type   | Description
86 86 
 --------|--------|----------------------------------------------------------------------------------
87 87 
 Allow   | bool   | Boolean value indicating whether the response is allowed or denied
88 
-Message | string | Authorization message (will be returned to the client in case the access is denied)
89 
-
90 
-## UX flows
91 
-
92 
-### Setting up docker daemon
93 
-
94 
-Authorization plugins are enabled with a dedicated command line argument. The argument contains the plugin name, which should be the same as the plugin’s socket or spec file.
95 
-Multiple authz-plugin parameters are supported.
96 
-```
97 
-$ docker daemon --authz-plugins=plugin1 --auth-plugins=plugin2,...
98 
-```
99 
-
100 
-### Calling authorized command (allow)
101 
-
102 
-No impact on command output
103 
-```
104 
-$ docker pull centos
105 
-...
106 
-f1b10cd84249: Pull complete
107 
-...
108 
-```
109 
-
110 
-### Calling unauthorized command (deny)
111 
-
112 
-```
113 
-$ docker pull centos
114 
-…
115 
-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’
116 
-```
117 
-
118 
-
119 
-
120 
-
88 
+Message | string | Authorization message (will be returned to the client in case the access is denied)
121 89 
\ No newline at end of file
docs/extend/images/authz_additional_info.png
History View file @ 8cc0892
122 90 
new file mode 100644
123 91 
Binary files /dev/null and b/docs/extend/images/authz_additional_info.png differ
docs/extend/images/authz_allow.png
History View file @ 8cc0892
124 92 
new file mode 100644
125 93 
Binary files /dev/null and b/docs/extend/images/authz_allow.png differ
docs/extend/images/authz_chunked.png
History View file @ 8cc0892
126 94 
new file mode 100644
127 95 
Binary files /dev/null and b/docs/extend/images/authz_chunked.png differ
docs/extend/images/authz_connection_hijack.png
History View file @ 8cc0892
128 96 
new file mode 100644
129 97 
Binary files /dev/null and b/docs/extend/images/authz_connection_hijack.png differ
docs/extend/images/authz_deny.png
History View file @ 8cc0892
130 98 
new file mode 100644
131 99 
Binary files /dev/null and b/docs/extend/images/authz_deny.png differ
docs/reference/commandline/daemon.md
History View file @ 8cc0892
... ... 
@@ -604,10 +604,29 @@ The currently supported cluster store options are:
604 604
605 605 
 ## Access authorization
606 606
607 
-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 
+Docker's access authorization can be extended by authorization plugins that your
608 
+organization can purchase or build themselves. You can install one or more
609 
+authorization plugins when you start the Docker `daemon` using the
610 
+`--authz-plugins=PLUGIN_ID` option.
608 611
612 
+```bash
613 
+docker daemon --authz-plugins=plugin1 --auth-plugins=plugin2,...
614 
+```
615 
+
616 
+The `PLUGIN_ID` value is either the plugin's name or a path to its specification
617 
+file. The plugin's implementation determines whether you can specify a name or
618 
+path. Consult with your Docker administrator to get information about the
619 
+plugins available to you.
620 
+
621 
+Once a plugin is installed, requests made to the `daemon` through the command
622 
+line or Docker's remote API are allowed or denied by the plugin.  If you have
623 
+multiple plugins installed, at least one must allow the request for it to
624 
+complete.
625 
+
626 
+For information about how to create an authorization plugin, see [authorization
627 
+plugin](https://docs.docker.com/engine/extend/authorization/) section in the
628 
+Docker extend section of this documentation.
609 629
610 
-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.
611 630
612 631 
 ## Miscellaneous options
613 632
... ... 
@@ -623,3 +642,6 @@ set like this:
623 623 
     # or
624 624 
     export DOCKER_TMPDIR=/mnt/disk2/tmp
625 625 
     /usr/local/bin/docker daemon -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
626 
+
627 
+
628 
+
pkg/authorization/api.md
History View file @ 8cc0892
626 629 
deleted file mode 100644
... ... 
@@ -1,83 +0,0 @@
1 
-# Docker Authorization Plug-in API
2 
-
3 
-## Introduction
4 
-
5 
-Docker authorization plug-in infrastructure enables extending the functionality of the Docker daemon with respect to user authorization. The infrastructure enables registering a set of external authorization plug-in. Each plug-in receives information about the user and the request and decides whether to allow or deny the request. Only in case all plug-ins allow accessing the resource the access is granted.
6 
-
7 
-Each plug-in operates as a separate service, and registers with Docker through general (plug-ins API) [https://blog.docker.com/2015/06/extending-docker-with-plugins/]. No Docker daemon recompilation is required in order to add / remove an authentication plug-in. Each plug-in is notified twice for each operation: 1) before the operation is performed and, 2) before the response is returned to the client. The plug-ins can modify the response that is returned to the client.
8 
-
9 
-The authorization depends on the authorization effort that takes place in parallel [https://github.com/docker/docker/issues/13697].
10 
-
11 
-This is the official issue of the authorization effort: https://github.com/docker/docker/issues/14674
12 
-
13 
-(Here)[https://github.com/rhatdan/docker-rbac] you can find an open document that discusses a default RBAC plug-in for Docker.
14 
-
15 
-## Docker daemon configuration
16 
-
17 
-In order to add a single authentication plug-in or a set of such, please use the following command line argument:
18 
-
19 
-``` docker -d authz-plugin=authZPlugin1,authZPlugin2 ```
20 
-
21 
-## API
22 
-
23 
-The skeleton code for a typical plug-in can be found here [ADD LINK]. The plug-in must implement two AP methods:
24 
-
25 
-1. */AuthzPlugin.AuthZReq* - this is the _authorize request_ method that is called before executing the Docker operation.
26 
-1. */AuthzPlugin.AuthZRes* - this is the _authorize response_ method that is called before returning the response to the client.
27 
-
28 
-#### /AuthzPlugin.AuthZReq
29 
-
30 
-**Request**:
31 
-
32 
-```
33 
-{
34 
-    "User":              "The user identification"
35 
-    "UserAuthNMethod":   "The authentication method used"
36 
-    "RequestMethod":     "The HTTP method"
37 
-    "RequestUri":        "The HTTP request URI"
38 
-    "RequestBody":       "Byte array containing the raw HTTP request body"
39 
-    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string "
40 
-    "RequestStatusCode": "Request status code"
41 
-}
42 
-```
43 
-
44 
-**Response**:
45 
-
46 
-```
47 
-{
48 
-    "Allow" : "Determined whether the user is allowed or not"
49 
-    "Msg":    "The authorization message"
50 
-}
51 
-```
52 
-
53 
-#### /AuthzPlugin.AuthZRes
54 
-
55 
-**Request**:
56 
-```
57 
-{
58 
-    "User":              "The user identification"
59 
-    "UserAuthNMethod":   "The authentication method used"
60 
-    "RequestMethod":     "The HTTP method"
61 
-    "RequestUri":        "The HTTP request URI"
62 
-    "RequestBody":       "Byte array containing the raw HTTP request body"
63 
-    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string"
64 
-    "RequestStatusCode": "Request status code"
65 
-    "ResponseBody":      "Byte array containing the raw HTTP response body"
66 
-    "ResponseHeader":    "Byte array containing the raw HTTP response header as a map[string][]string"
67 
-    "ResponseStatusCode":"Response status code"
68 
-}
69 
-```
70 
-
71 
-**Response**:
72 
-```
73 
-{
74 
-   "Allow" :               "Determined whether the user is allowed or not"
75 
-   "Msg":                  "The authorization message"
76 
-   "ModifiedBody":         "Byte array containing a modified body of the raw HTTP body (or nil if no changes required)"
77 
-   "ModifiedHeader":       "Byte array containing a modified header of the HTTP response (or nil if no changes required)"
78 
-   "ModifiedStatusCode":   "int containing the modified version of the status code (or 0 if not change is required)"
79 
-}
80 
-```
81 
-
82 
-The modified response enables the authorization plug-in to manipulate the content of the HTTP response.
83 
-In case of more than one plug-in, each subsequent plug-in will received a response (optionally) modified by a previous plug-in.
84 1 
\ No newline at end of file