Service Login

Logging in to DC/OS as a service

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

NOTE: This demonstrates manual login for service account testing. A service login token is generated internally for the login process.

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:

  1. 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.

  1. Header

    1. {
    2.     "alg": "RS256",
    3.     "typ": "JWT"
    4. }

  2. Payload

    1. {
    2.     "uid": "<uid>",
    3.     "exp": <expiration_time>
    4. }

Service login tokens can be created manually via jwt.io or via your favorite JWT library.

NOTE: Service login tokens and DC/OS Authentication tokens are both JWTs of type RS256 with identical claims. However they are not interchangable. A service login token is signed by a service private key while a DC/OS Authentication token is signed by the IAM private key.

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.

NOTE: The IAM will reject service login tokens with a life-time greater than ten minutes.

  1. To log in a service supply <service-account-id> and <service-login-token> before executing the following command:

    1. 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'

  2. A DC/OS Authentication token will be returned in the HTTP response body similar to the below example.

    1. {
    2.   "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJib290c3RyYXB1c2VyIiwiZXhwIjoxNDgyNjE1NDU2fQ.j3_31keWvK15shfh_BII7w_10MgAj4ay700Rub5cfNHyIBrWOXbedxdKYZN6ILW9vLt3t5uCAExOOFWJkYcsI0sVFcM1HSV6oIBvJ6UHAmS9XPqfZoGh0PIqXjE0kg0h0V5jjaeX15hk-LQkp7HXSJ-V7d2dXdF6HZy3GgwFmg0Ayhbz3tf9OWMsXgvy_ikqZEKbmPpYO41VaBXCwWPmnP0PryTtwaNHvCJo90ra85vV85C02NEdRHB7sqe4lKH_rnpz980UCmXdJrpO4eTEV7FsWGlFBuF5GAy7_kbAfi_1vY6b3ufSuwiuOKKunMpas9_NfDe7UysfPVHlAxJJgg"
    3. }

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.