layout: documentation

Authorization

Authorization currently allows

Frameworks to (re-)register with authorized roles.
Frameworks to launch tasks/executors as authorized users.
Authorized principals to teardown frameworks through the “/teardown” HTTP endpoint.
Authorized principals to set and remove quotas through the “/quota” HTTP endpoint.
Authorized principals to reserve and unreserve resources through the “/reserve” and “/unreserve” HTTP endpoints, as well as with the RESERVE and UNRESERVE offer operations.
Authorized principals to create and destroy persistent volumes through the “/create-volumes” and “/destroy-volumes” HTTP endpoints, as well as with the CREATE and DESTROY offer operations.

ACLs

Authorization is implemented via Access Control Lists (ACLs). For each of the above cases, ACLs can be used to restrict access. Operators can setup ACLs in JSON format. See authorizer.proto for details.

Each ACL specifies a set of Subjects that can perform an Action on a set of Objects.

The currently supported Actions are:

“register_frameworks”: Register frameworks
“run_tasks”: Run tasks/executors
“teardown_frameworks”: Teardown frameworks
“set_quotas”: Set quotas
“remove_quotas”: Remove quotas
“reserve_resources”: Reserve resources
“unreserve_resources”: Unreserve resources
“create_volumes”: Create persistent volumes
“destroy_volumes”: Destroy persistent volumes

The currently supported Subjects are:

“principals”
- Framework principals (used by “register_frameworks”, “run_tasks”, “reserve”, “unreserve”, “create_volumes”, and “destroy_volumes” actions)
- Usernames (used by “teardown_frameworks”, “set_quotas”, “remove_quotas”, “reserve”, “unreserve”, “create_volumes”, and “destroy_volumes” actions)

The currently supported Objects are:

“roles”: Resource roles that framework can register with (used by “register_frameworks” and “set_quotas” actions)
“users”: Unix user to launch the task/executor as (used by “run_tasks” actions)
“framework_principals”: Framework principals that can be torn down by HTTP POST (used by “teardown_frameworks” actions).
“resources”: Resources that can be reserved. Currently the only types considered by the default authorizer are ANY and NONE (used by “reserves” action).
“reserver_principals”: Framework principals whose reserved resources can be unreserved (used by “unreserves” action).
“volume_types”: Types of volumes that can be created by a given principal. Currently the only types considered by the default authorizer are ANY and NONE (used by “create_volumes” action).
“creator_principals”: Principals whose persistent volumes can be destroyed (used by “destroy_volumes” action).
“quota_principals”: Principals that set the quota to be removed (used by “remove_quotas” action)

NOTE: Both Subjects and Objects can be either an array of strings or one of the special values ANY or NONE.

How does it work?

The Mesos master checks the ACLs to verify whether a request is authorized or not.

For example, when a framework (re-)registers with the master, “register_frameworks” ACLs are checked to see if the framework (FrameworkInfo.principal) is authorized to receive offers for the given resource role (FrameworkInfo.role). If not authorized, the framework is not allowed to (re-)register and gets an Error message back (which aborts the scheduler driver).

Similarly, when a framework launches a task, “run_tasks” ACLs are checked to see if the framework (FrameworkInfo.principal) is authorized to run the task/executor as the given user. If not authorized, the launch is rejected and the framework gets a TASK_LOST.

In the same vein, when a user/principal attempts to teardown a framework using the “/teardown” HTTP endpoint on the master, “teardown_frameworks” ACLs are checked to see if the principal is authorized to teardown the given framework. If not authorized, the teardown is rejected and the user receives a Forbidden HTTP response.

If no user/principal is provided in a request to an HTTP endpoint and authentication is disabled, the ANY subject is used in the authorization.

There are couple of important things to note:

ACLs are matched in the order that they are specified. In other words, the first matching ACL determines whether a request is authorized or not.
If no ACLs match a request, whether the request is authorized or not is determined by the ACLs.permissive field. This is “true” by default -- i.e., non-matching requests are authorized.

Examples

Frameworks foo and bar can run tasks as user alice.

 {
   "run_tasks": [
                  {
                    "principals": { "values": ["foo", "bar"] },
                    "users": { "values": ["alice"] }
                  }
                ]
 }

Any framework can run tasks as user guest.

 {
   "run_tasks": [
                  {
                    "principals": { "type": "ANY" },
                    "users": { "values": ["guest"] }
                  }
                ]
 }

No framework can run tasks as root.

 {
   "run_tasks": [
                  {
                    "principals": { "type": "NONE" },
                    "users": { "values": ["root"] }
                  }
                ]
 }

Framework foo can run tasks only as user guest and no other user.

 {
   "run_tasks": [
                  {
                    "principals": { "values": ["foo"] },
                    "users": { "values": ["guest"] }
                  },
                  {
                    "principals": { "values": ["foo"] },
                    "users": { "type": "NONE" }
                  }
                ]
 }

Framework foo can register with the analytics and ads roles.

 {
   "register_frameworks": [
                            {
                              "principals": {
                                "values": ["foo"]
                              },
                              "roles": {
                                "values": ["analytics", "ads"]
                              }
                            }
                          ]
 }

Only framework foo and no one else can register with the analytics role.

 {
   "register_frameworks": [
                            {
                              "principals": {
                                "values": ["foo"]
                              },
                              "roles": {
                                "values": ["analytics"]
                              }
                            },
                            {
                              "principals": {
                                "type": "NONE"
                              },
                              "roles": {
                                "values": ["analytics"]
                              }
                            }
                          ]
 }

Framework foo can only register with the analytics role but no other roles. Also, no other framework can register with any roles or run tasks.

 {
   "permissive": false,
   "register_frameworks": [
                            {
                              "principals": {
                                "values": ["foo"]
                              },
                              "roles": {
                                "values": ["analytics"]
                              }
                            }
                          ]
 }

The ops principal can teardown any framework using the “/teardown” HTTP endpoint. No other framework can register with any roles or run tasks.

 {
   "permissive": false,
   "teardown_frameworks": [
                            {
                              "principals": {
                                "values": ["ops"]
                              },
                              "framework_principals": {
                                "type": "ANY"
                              }
                            }
                          ]
 }

Configuring authorization

Authorization is configured by specifying the --acls flag when starting the master:

acls: The value could be a JSON-formatted string of ACLs or a file path containing the JSON-formatted ACLs used for authorization. Path could be of the form ‘file:///path/to/file’ or ‘/path/to/file’. See the ACLs protobuf in authorizer.proto for the expected format.

For more information on master command-line flags, see the configuration page.