Service Accounts



About service authentication

DC/OS Enterprise uses public-private key cryptography and JSON web tokens (JWT) to authenticate services. Services required to authenticate must create a public-private key pair and then create a service account with their public key. The service will then generate a JWT signed with their private key and pass this to DC/OS. DC/OS uses the public key in the service account to verify the service’s signature, then returns a DC/OS authentication token signed by the Identity and Access Management Service. The service can use the DC/OS authentication token to gain access to the necessary resources.

Authentication tokens expire by default after five days. Services can use a variety of means to refresh their tokens. Ideally, a service should calculate the length of time until the token expires, which is embedded within the token itself, and request a new one before it expires. However, a service can also wait until it receives a 401 to request a new token.

About systemd-started services

In strict or permissive security mode, the DC/OS services that are started by systemd are automatically provisioned with the necessary credentials and permissions during the bootstrap sequence. You can review these service accounts from the System -> Organization -> Service Accounts tab of the DC/OS web interface.

Important: Modifying the permissions of any of the automatically provisioned service accounts may cause the service to fail.

About custom services

You may need to manually provision your custom service or script with a service account so that it can authenticate at runtime. This requirement varies according to your security mode, the origin of the service’s requests, and the type of resource it needs to access. The following table details the circumstances under which a service requires an account.

Requests originate from Service account required Service account optional
Outside of the cluster All security modes N/A
Inside the cluster strict permissive

For detailed instructions on how to set up a custom service or script with a service account, refer to Provisioning custom services with service accounts.

About services in the default Universe

Not all services in the default Universe can be provisioned with a service account. If a service requires a service account and cannot be provisioned with one, you won’t be able to deploy the service. This requirement varies according to your security mode.

The following table lists the Universe services that can be provisioned with service accounts. It also identifies when a service account is optional or required.

Service disabled permissive strict
Cassandra Not possible Optional Required
Confluent Not possible Optional N/A*
HDFS Not possible Optional Required
Kafka Not possible Optional Required
Marathon-LB Optional Optional Required
Spark Not possible Optional Required

* These services cannot be deployed in strict mode at this time.

If the service supports authentication in permissive, we encourage you to provision it with a service account. Otherwise, the service will default to running with the superuser permission. This will also make it easier to upgrade to strict mode in the future.

You may also want to provision Marathon-LB with a service account in disabled mode to make it easier to upgrade to permissive or strict.

Refer to the following sections for more details about how and when to provision each service with a service account.