Sesame is a Docker access authorization plugin with focous on simplicity and flexibility that is easy to configure and adapt.
Assuming that Sesame is to run on the same host as Docker engine, the easiest way is to start it with your rules (i.e. rules.json
)
and let docker engine use it as an authorization plugin. But first fetch the latest release of sesame
here and then:
# Start plugin (i.e. downloaded binary) with rules.json
./sesame rules.json
# Let Docker run with TLS enabled and use sesame as authorization plugin
# see https://docs.docker.com/engine/admin/#/configuring-docker for more
dockerd \
--tlsverify \
--tlscacert=~/.docker/ca.pem \
--tlscert=~/.docker/cert.pem \
--tlskey=~/.docker/key.pem \
--authorization-plugin=sesame
If no parameters (e.g. rules.json
) is given, sesame tries to load the rules from /etc/sesame/rules.json
. For more on rules, see
Rules section.
NOTE: Sesame can also run as a Docker container. See Docker Image section for more.
Docker engine changes rapidly and so does its remote API. To keep up with this changes, this plugin focuses on simplicity and flexibility so in case of introducing any breaking changes in the remote API, you would only need to update your rules and enhance them with matching rules to the new specification. You wouldn't need to wait for the plugin to adapt to the new changes.
Docker clients communicate with Docker engine over remote API which
is (mostly) an HTTP REST API. A rule is a combination of an HTTP method template (e.g. GET|PUT
) and a URI template (e.g. /containers/.*
)
to define ressources of remote API. Rules use regular expressions to define method and URI templates, allowing them to match multiple API
resources.
To define a rule, for example, matching starting, pausing, and unpausing of a container called MYCONTAINER
can be done using a single
rule:
{
"method": "POST",
"pattern": "/containers/MYCONTAINER/(start|pause|unpause)$"
}
The rules.json
file associates users with an array of rules:
{
"someUser": [{
"method": "GET",
"pattern": "/version$"
}],
"otherUser": [
{
"method": "GET",
"pattern": "/containers/json$"
},
{
"method": "POST",
"pattern": "/build"
}
]
}
The example above allows someUser
to get Docker engine's version and otherUser
to list containers and build images. To see more examples
see testdata/rules.json
and take a look at plugin_test.go
.
Sesame can also be used inside a container. Currently there are no ready-made Sesame images available (but planned) on Docker hub. However, an image can directly be built from the source:
# Clone the repository
https://github.com/fraunhoferfokus/sesame.git && cd sesame
# Build the binaries
make build
# Build docker image
docker build -t fraunhofer/sesame .
Note that this method requires having git
, make
, go >= 1.7
, and obviously docker
installed. You can also download the latest
binary (as mentioned in quick start) and build an image without being required to clone the repository and build from the source using the
following Dockerfile
:
FROM alpine:3.4
MAINTAINER Yan Foto <yan.foto@quaintous.com>
LABEL Description="A simple and flexible authorization plugin for Docker"
COPY sesame /usr/bin/sesame
# Volume to load rules from and another to create socket in
VOLUME ["/etc/sesame", "/run/docker/plugins"]
ENTRYPOINT ["sesame"]
To start the container, rules should be mounted at /etc/sesame/rules.json
and the socket is provided at
/run/docker/plugins/sesame.sock
of the running container. A typical procedure would look as follows:
# Start sesame as a daemon inside a container
docker run -d --restart=always --name sesame \
-v `pwd`/rules.json:/etc/sesame/rules.json \
-v /run/docker/plugins:/run/docker/plugins \
fraunhofer/sesame
# Let Docker run with TLS enabled and use sesame as authorization plugin
# see https://docs.docker.com/engine/admin/#/configuring-docker for more
dockerd \
--tlsverify \
--tlscacert=~/.docker/ca.pem \
--tlscert=~/.docker/cert.pem \
--tlskey=~/.docker/key.pem \
--authorization-plugin=sesame
This example assumes that rules.json
is available under working directory.