If you're new to Mesos

See the getting started page for more information about downloading, building, and deploying Mesos.

If you'd like to get involved or you're looking for support

See our community page for more details.

Authentication

Authentication permits only trusted entities to interact with a Mesos cluster. Authentication can be used by Mesos in three ways:

To require that frameworks be authenticated in order to register with the master.
To require that agents be authenticated in order to register with the master.
To require that operators be authenticated to use many HTTP endpoints.

Authentication is disabled by default. When authentication is enabled, operators can configure Mesos to either use the default authentication module or to use a custom authentication module.

The default Mesos authentication module uses the Cyrus SASL library. SASL is a flexible framework that allows two endpoints to authenticate with each other using a variety of methods. By default, Mesos uses CRAM-MD5 authentication.

Credentials, Principals, and Secrets

When using the default CRAM-MD5 authentication method, an entity that wants to authenticate with Mesos must provide a credential, which consists of a principal and a secret. The principal is the identity that the entity would like to use; the secret is an arbitrary string that is used to verify that identity. Principals are similar to user names, while secrets are similar to passwords.

Principals are used primarily for authentication and authorization; note that a principal is different from a framework’s user, which is the operating system account used by the agent to run executors, and a framework’s role, which is used to determine which resources a framework can use.

Configuration

Authentication is configured by specifying command-line flags when starting the Mesos master and agent processes. For more information, refer to the configuration documentation.

Master

--[no-]authenticate - If true, only authenticated frameworks are allowed to register. If false (the default), unauthenticated frameworks are also allowed to register.
--[no-]authenticate_http_readonly - If true, authentication is required to make HTTP requests to the read-only HTTP endpoints that support authentication. If false (the default), these endpoints can be used without authentication. Read-only endpoints are those which cannot be used to modify the state of the cluster.
--[no-]authenticate_http_readwrite - If true, authentication is required to make HTTP requests to the read-write HTTP endpoints that support authentication. If false (the default), these endpoints can be used without authentication. Read-write endpoints are those which can be used to modify the state of the cluster.
--[no-]authenticate_agents - If true, only authenticated agents are allowed to register. If false (the default), unauthenticated agents are also allowed to register.
--authenticators - Specifies which authenticator module to use. The default is crammd5, but additional modules can be added using the --modules option.
--http_authenticators - Specifies which HTTP authenticator module to use. The default is basic (basic HTTP authentication), but additional modules can be added using the --modules option.
--credentials - The path to a text file which contains a list of accepted credentials. This may be optional depending on the authenticator being used.

Agent

--authenticatee - Analog to the master’s --authenticators option to specify what module to use. Defaults to crammd5.
--credential - Just like the master’s --credentials option except that only one credential is allowed. This credential is used to identify the agent to the master.
--[no-]authenticate_http_readonly - If true, authentication is required to make HTTP requests to the read-only HTTP endpoints that support authentication. If false (the default), these endpoints can be used without authentication. Read-only endpoints are those which cannot be used to modify the state of the agent.
--[no-]authenticate_http_readwrite - If true, authentication is required to make HTTP requests to the read-write HTTP endpoints that support authentication. If false (the default), these endpoints can be used without authentication. Read-write endpoints are those which can be used to modify the state of the agent.
--http_authenticators - Specifies which HTTP authenticator module to use. The default is basic, but additional modules can be added using the --modules option.
--http_credentials - The path to a text file which contains a list (in JSON format) of accepted credentials. This may be optional depending on the authenticator being used.

Framework

If framework authentication is enabled, each framework must be configured to supply authentication credentials when registering with the Mesos master. How to configure this differs between frameworks; consult your framework’s documentation for more information.

As a framework developer, supporting authentication is straightforward: the scheduler driver handles the details of authentication when a Credential object is passed to its constructor. To enable authorization based on the authenticated principal, the framework developer should also copy the Credential.principal into FrameworkInfo.principal when registering.

CRAM-MD5 Example

Create the master’s credentials file with the following content:

 {
   "credentials" : [
     {
       "principal": "principal1",
       "secret": "secret1"
     },
     {
       "principal": "principal2",
       "secret": "secret2"
     }
   ]
 }

Start the master using the credentials file (assuming the file is /home/user/credentials):

 ./bin/mesos-master.sh --ip=127.0.0.1 --work_dir=/var/lib/mesos --authenticate --authenticate_agents --credentials=/home/user/credentials

Create another file with a single credential in it (/home/user/agent_credential):
```
 {
   "principal": "principal1",
   "secret": "secret1"
 }
```

Start the agent:

 ./bin/mesos-agent.sh --master=127.0.0.1:5050 --credential=/home/user/agent_credential

Your new agent should have now successfully authenticated with the master.

You can test out framework authentication using one of the test frameworks provided with Mesos as follows:

  MESOS_AUTHENTICATE=true DEFAULT_PRINCIPAL=principal2 DEFAULT_SECRET=secret2 ./src/test-framework --master=127.0.0.1:5050