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:

1. To require that frameworks be authenticated in order to register with the master.
2. To require that agents be authenticated in order to register with the master.
3. 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 the framework’s roles, which are 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.

• --authentication_v0_timeout - The timeout within which an authentication is expected to complete against a v0 framework or agent. This does not apply to the v0 or v1 HTTP APIs.(default: 15secs)

• --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. Note that for backward compatibility reasons, the V1 executor API is not affected by this flag.

• --[no-]authenticate_http_executors - If true, authentication is required to make HTTP requests to the V1 executor API. If false (the default), that API can be used without authentication. If this flag is true and custom HTTP authenticators are not specified, then the default JWT authenticator is loaded to handle executor authentication.

• --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.

• --authentication_backoff_factor - The agent will time out its authentication with the master based on exponential backoff. The timeout will be randomly chosen within the range [min, min + factor*2^n] where n is the number of failed attempts. To tune these parameters, set the --authentication_timeout_[min|max|factor] flags. (default: 1secs)

• --authentication_timeout_min - The minimum amount of time the agent waits before retrying authenticating with the master. See --authentication_backoff_factor for more details. (default: 5secs)

• --authentication_timeout_max - The maximum amount of time the agent waits before retrying authenticating with the master. See --authentication_backoff_factor for more details. (default: 1mins)

Scheduler Driver

• --authenticatee - Analog to the master’s --authenticators option to specify what module to use. Defaults to crammd5.

• --authentication_backoff_factor - The scheduler will time out its authentication with the master based on exponential backoff. The timeout will be randomly chosen within the range [min, min + factor*2^n] where n is the number of failed attempts. To tune these parameters, set the --authentication_timeout_[min|max|factor] flags. (default: 1secs)

• --authentication_timeout_min - The minimum amount of time the scheduler waits before retrying authenticating with the master. See --authentication_backoff_factor for more details. (default: 5secs)

• --authentication_timeout_max - The maximum amount of time the scheduler waits before retrying authenticating with the master. See --authentication_backoff_factor for more details. (default: 1mins)

Multiple HTTP Authenticators

Multiple HTTP authenticators may be loaded into the Mesos master and agent. In order to load multiple authenticators, specify them as a comma-separated list using the --http_authenticators flag. The authenticators will be called serially, and the result of the first successful authentication attempt will be returned.

If you wish to specify the default basic HTTP authenticator in addition to custom authenticator modules, add the name basic to your authenticator list. To specify the default JWT HTTP authenticator in addition to custom authenticator modules, add the name jwt to your authenticator list.

Executor

If HTTP executor authentication is enabled on the agent, then all requests from HTTP executors must be authenticated. This includes the default executor, HTTP command executors, and custom HTTP executors. By default, the agent’s JSON web token (JWT) HTTP authenticator is loaded to handle executor authentication on both the executor and operator API endpoints. Note that command and custom executors not using the HTTP API will remain unauthenticated.

When a secret key is loaded via the --jwt_secret_key flag, the agent will generate a default JWT for each executor before it is launched. This token is passed into the executor’s environment via the MESOS_EXECUTOR_AUTHENTICATION_TOKEN environment variable. In order to authenticate with the agent, the executor should place this token into the Authorization header of all its requests as follows:

    Authorization: Bearer MESOS_EXECUTOR_AUTHENTICATION_TOKEN

In order to upgrade an existing cluster to require executor authentication, the following procedure should be followed:

1. Upgrade all agents, and provide each agent with a cryptographic key via the --jwt_secret_key flag. This key will be used to sign executor authentication tokens using the HMAC-SHA256 procedure.

2. Before executor authentication can be enabled successfully, all HTTP executors must have executor authentication tokens in their environment and support authentication. To accomplish this, executors which were already running before the upgrade must be restarted. This could either be done all at once, or the cluster may be left in this intermediate state while executors gradually turn over.

3. Once all running default/HTTP command executors have been launched by upgraded agents, and any custom HTTP executors have been upgraded, the agent processes can be restarted with the --authenticate_http_executors flag set. This will enable required HTTP executor authentication, and since all executors now have authentication tokens and support authentication, their requests to the agent will authenticate successfully.

Note that HTTP executors make use of the agent operator API in order to make nested container calls. This means that authentication of the v1 agent operator API should not be enabled (via --authenticate_http_readwrite) when HTTP executor authentication is disabled, or HTTP executors will not be able to function correctly.

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

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

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

2. 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
   

3. Create another file with a single credential in it (/home/user/agent_credential):

    {
      "principal": "principal1",
      "secret": "secret1"
    }
   

4. Start the agent:

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

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

6. 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