Project: Apache Mesos (Orchestration & Management / Scheduling & Orchestration)
File: authentication.md

title: Apache Mesos - Authentication layout: documentation 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 . 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 library. SASL is a flexible framework that allows two endpoints to authenticate with each other using a variety of methods. By default, Mesos uses authentication. 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 ; 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 , which are used to determine which resources a framework can use. Authentication is configured by specifying command-line flags when starting the Mesos master and agent processes. For more information, refer to the documentation. `--[no-]authenticate` - If `true`, only authenticated frameworks are allowed to register. If `false` (the default), unauthenticated frameworks are also allowed to register. `--[no-]authenticatehttpreadonly` - 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-]authenticatehttpreadwrite` - 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. `--authenticationv0timeout` - 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. `--authenticatee` - Analog to the master's `--authenticators` option to specify what module to use. Defaults to

`--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-]authenticatehttpreadonly` - 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-]authenticatehttpreadwrite` - 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-]authenticatehttpexecutors` - 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. `--authenticationbackofffactor` - 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 `--authenticationtimeout[min|max|factor]` flags. (default: 1secs) `--authenticationtimeoutmin` - The minimum amount of time the agent waits before retrying authenticating with the master. See `--authenticationbackofffactor` for more details. (default: 5secs) `--authenticationtimeoutmax` - The maximum amount of time the agent waits before retrying authenticating with the master. See `--authenticationbackofffactor` for more details. (default: 1mins) `--authenticatee` - Analog to the master's `--authenticators` option to specify what module to use. Defaults to `crammd5`. `--authenticationbackofffactor` - 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 `--authenticationtimeout[min|max|factor]` flags. (default: 1secs) `--authenticationtimeoutmin` - The minimum amount of time the scheduler waits before retrying authenticating with the master. See `--authenticationbackofffactor` for more details. (default: 5secs) `--authenticationtimeoutmax` - The maximum amount of time the scheduler waits before retrying authenticating with the master. See `--authenticationbackofffactor` for more details. (default: 1mins) 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

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 `--jwtsecretkey` 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 `MESOSEXECUTORAUTHENTICATION_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 MESOSEXECUTORAUTHENTICATION_TOKEN In order to upgrade an existing cluster to require executor authentication, the following procedure should be followed: Upgrade all agents, and provide each agent with a cryptographic key via the `--jwtsecretkey` flag. This key will be used to sign executor authentication tokens using the HMAC-SHA256 procedure. 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. 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 `--authenticatehttpexecutors` 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 `--authenticatehttpreadwrite`) when HTTP executor authentication is disabled, or HTTP executors will not be able to function correctly. 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 based on the authenticated principal, the framework developer should also copy the `Credential.principal` into `FrameworkInfo.principal` when registering. 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 --workdir=/var/lib/mesos --authenticate --authenticateagents --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: MESOSAUTHENTICATE=true DEFAULTPRINCIPAL=principal2 DEFAULT_SECRET=secret2 ./src/test-framework --master=127.0.0.1:5050