Secure service login
A service logs in to DC/OS without transmitting a password by entering a service login token in a cryptographically secure manner.
Service login tokens are always generated by the service that wants to perform a service login, ideally on-demand. The idea is that they are generated for one-time usage only (for example, for a single service login procedure). Therefore, any service login token should include an expiration time.
The secure service login is enabled through a service login token being signed by the private key of the service that generated it.
Logging in using the DC/OS CLI
Prerequisite:
Using the DC/OS CLI one can log in as service by specifying the dcos-services
login provider.
To test a service login using the DC/OS CLI specify the dcos-services
login provider with the auth login command. Replace <service-account-id>
and <private-key-path>
with the corresponding values before executing the following command:
dcos auth login --provider=dcos-services --username=<service-account-id> --private-key=<private-key-path>
Logging in using the IAM API
Construct a service login token
For DC/OS, service login tokens must be RFC 7519 JSON Web Tokens (JWT) of type RS256.
A service login token for DC/OS is constructed by adding the service account ID via the (uid
) claim and the expiration time in Unix seconds via the (exp
) claim to the JWT payload. The JWT header must specify the RS256 algorithm. The token is signed with the service account’s private key.
-
Header
{ "alg": "RS256", "typ": "JWT" }
-
Payload
{ "uid": "<uid>", "exp": <expiration_time> }
Service login tokens can be created manually via jwt.io or via your favorite JWT library.
Logging in using a service login token
Prerequisite:
During a service login a service login token is sent to the DC/OS Identity and Access Management (IAM) API.
-
To log in a service supply
<service-account-id>
and<service-login-token>
before executing the following command:curl -k -X POST https://<host-ip>/acs/api/v1/auth/login -d '{"uid": "<service-account-id>", "token": "<service-login-token>"}' -H 'Content-Type: application/json'
-
A DC/OS Authentication token will be returned in the HTTP response body similar to the below example.
{ "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJib290c3RyYXB1c2VyIiwiZXhwIjoxNDgyNjE1NDU2fQ.j3_31keWvK15shfh_BII7w_10MgAj4ay700Rub5cfNHyIBrWOXbedxdKYZN6ILW9vLt3t5uCAExOOFWJkYcsI0sVFcM1HSV6oIBvJ6UHAmS9XPqfZoGh0PIqXjE0kg0h0V5jjaeX15hk-LQkp7HXSJ-V7d2dXdF6HZy3GgwFmg0Ayhbz3tf9OWMsXgvy_ikqZEKbmPpYO41VaBXCwWPmnP0PryTtwaNHvCJo90ra85vV85C02NEdRHB7sqe4lKH_rnpz980UCmXdJrpO4eTEV7FsWGlFBuF5GAy7_kbAfi_1vY6b3ufSuwiuOKKunMpas9_NfDe7UysfPVHlAxJJgg" }
Authentication token renewal
In DC/OS Open Source Authentication, tokens expire after five days. The service account login is intended for long-running services to obtain new DC/OS Authentication tokens automatically. Multiple strategies exist to mitigate the load that is placed on the IAM when multiple token renewals are due at the same time.
Ideally, a service should calculate the length of time until the authentication 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 authentication token.
An API consumer should be able to handle when its current authentication token expires.
- Post-Expiration Renewal With this method, you obtain a new authentication token after an “invalid token” response is received. An invalid authentication token is responded to with a 401 HTTP status code and the service re-invokes the service account login procedure. It attempts to get a fresh authentication token (with retry and back-off). During the period where the service has no valid authentication token, the service might need to hold back operations, resulting in latency spikes.
- Pre-Expiration Renewal With this method, the token is refreshed before it expires. The service can schedule asynchronous token renewal ahead of the expiration. It can fetch a new authentication token while the old one is still valid. This prevents the latency spikes caused by an expired authentication token.