Authenticating DC/OS Services


This topic details how to configure authentication for custom apps and pods launched on DC/OS.


Create a Key Pair

In this step, a 2048-bit RSA public-private key pair is created using the DC/OS Enterprise CLI.

Create a public-private key pair and save each value into a separate file within the current directory.

dcos security org service-accounts keypair <private-key>.pem <public-key>.pem

Tip: You can use the DC/OS Secret Store to secure the key pair.

Create a Service Account

You can use either the DC/OS Enterprise CLI or the DC/OS GUI to create a service account.

Using the DC/OS Enterprise CLI

From a terminal prompt, create a new service account (<service-account-id>) containing the public key (<your-public-key>.pem).

dcos security org service-accounts create -p <your-public-key>.pem -d "<description>" <service-account-id>

Tip: You can verify your new service account using the following command.

dcos security org service-accounts show <service-account-id>

Using the GUI

  1. In the DC/OS GUI, navigate to the Organization -> Service Accounts tab.

  2. Click the + icon in the top right.

    Click the service account create button

  3. Enter a description and type the Service Account ID in the ID field.

  4. Paste the public key associated with the account into the PUBLIC KEY field.

    Create service account UI

Create a Secret

Create a secret (<secret-name>) with your service account (service-account-id>) and private key specified (<private-key>.pem).


dcos security secrets create-sa-secret <private-key>.pem <service-account-id> <secret-name>


In strict mode, the service account name (<service-account-id>) must match the name specified in the framework principal.

dcos security secrets create-sa-secret --strict <private-key>.pem <service-account-id> <secret-name>

Tip: You can list the secrets with this command:

dcos security secrets list /

Create and Assign Permissions

Determine the Required Permissions

You can determine what access your service account requires by using this procedure. This will allow you to rule out any functional issues that might be caused by incorrect permissions.

  1. SSH to your node.

    dcos node ssh --master-proxy --mesos-id=<mesos-id>
  2. Run this grep command to view the deny logs for your service account (<service-account-id>).

    journalctl -u "dcos-*" |grep "audit" |grep "<service-account-id>" |grep "deny"

    This command will return a list of the audit logs that are generated when your service was denied access due to insufficient permissions or a bad token. The rejection messages should include the permission that was missing. You might need to repeat this process several times to determine the full list of required permissions.


  • You can grant your service superuser permission to rule out any functional issues. All valid services should be able to run as superuser.

    curl -x put --cacert dcos-ca.crt \
    -h "authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:superuser/users/<service-account-id>/full

For more information, see the permissions reference.

Assign the Permissions

Using the permissions reference and the log output, assign permissions to your service.

Using the CLI

You can assign permissions using curl commands. To assign permissions you must create the folder and then assign permissions to it. For example, to authorize the Cassandra service to be uninstalled on DC/OS:

  1. Create a folder for the permission (dcos:mesos:master:framework:role:cassandra-role).

    curl -X PUT --cacert dcos-ca.crt \
    -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:mesos:master:framework:role:cassandra-role \
    -d '{"description":"Controls the ability of cassandra-role to register as a framework with the Mesos master"}' \
    -H 'Content-Type: application/json'
  2. Grant the permissions (dcos:mesos:master:framework:role:cassandra-role) and the allowed actions (create).

    curl -X PUT --cacert dcos-ca.crt \
    -H "Authorization: token=$(dcos config show core.dcos_acs_token)" $(dcos config show core.dcos_url)/acs/api/v1/acls/dcos:mesos:master:framework:role:cassandra-role/users/<service-account-id>/create

Using the GUI

  1. Log into the DC/OS GUI as a user with the superuser permission.

  2. Select Organization > Service Accounts.

  3. Select the name of the service account to grant the permission to.

    Select service acccount

  4. From the Permissions tab, click ADD PERMISSION.

  5. Click INSERT PERMISSION STRING to toggle the dialog.

  6. Copy and paste the permission in the Permissions Strings field.

    Service account permission string

Request an Authentication Token

Generate a service login token, where the service account (<service-account-id>) and private key (<private-key>.pem) are specified.

dcos auth login --username=<service-account-id> --private-key=<private-key>.pem

Pass the Authentication Token in Subsequent Requests

After the service has successfully logged in, an authentication token is created. The authentication token should used in subsequent requests to DC/OS endpoints. You can reference the authentication token as a shell variable, for example:

curl -H "Authorization: token=$(dcos config show core.dcos_acs_token)"

Refresh the Authentication Token

By default, authentication tokens expire after five days. Your service will need to renew its token either before or after it expires. The token itself contains the expiration, so your service can use this information to proactively refresh the token. Alternatively, you can wait to get a 401 from DC/OS and then refresh it.

To refresh your authentication token, just repeat the process discussed in Request an authentication token.