This topic details how to configure authentication for custom apps and pods launched on DC/OS.
- DC/OS CLI installed and be logged in as a superuser.
- DC/OS Enterprise CLI 0.4.14 or later installed.
- If your security mode is
strict, you must get the root cert before issuing the curl commands in this section.
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.
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 (
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
In the DC/OS GUI, navigate to the Organization -> Service Accounts tab.
Click the + icon in the top right.
Enter a description and type the Service Account ID in the ID field.
Paste the public key associated with the account into the PUBLIC KEY field.
Create a Secret
Create a secret (
<secret-name>) with your service account (
service-account-id>) and private key specified (
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
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 /
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.
dcos node ssh --master-proxy --mesos-id=<mesos-id>
Run this grep command to view the
denylogs for your service account (
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.
All CLI commands can also be executed via the IAM API.
Using the CLI
You can assign permissions using the CLI. For example, to authorize the Cassandra service to be uninstalled on DC/OS:
Grant the permissions (
dcos:mesos:master:framework:role:cassandra-role) and the allowed actions (
dcos security org users grant <service-account-id> dcos:mesos:master:framework:role:cassandra-role create --description "Controls the ability of cassandra-role to register as a framework with the Mesos master"
Using the GUI
Log into the DC/OS GUI as a user with the superuser permission.
Select Organization > Service Accounts.
Select the name of the service account to grant the permission to.
From the Permissions tab, click ADD PERMISSION.
Click INSERT PERMISSION STRING to toggle the dialog.
Copy and paste the permission in the Permissions Strings field.
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
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)"
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.