Temporary Credentials


Any client with a clientId and an accessToken can issue temporary credentials with a subset of its scopes. Temporary credentials consist of a clientId, accessToken and a certificate validating them.

Temporary credentials always have an explicit start and expiry date, which can be up to 31 days apart. A set of temporary credentials cannot be used to issue new temporary credentials, but they be used to generate signed URLs for untrusted sources.

Because temporary credentials can be created anywhere, there is no central registry of temporary credentials, and they cannot be listed (or revoked) anywhere in the TaskCluster API.

Certificates

A certificate looks like this:

ext = {
  // ...
  certificate: {
    version:          1,
    issuer:           "issuing-client-id",
    scopes:           ['ScopeA', 'ScopeB'],
    start:            1410399435102,
    expiry:           1410399497349,
    seed:             'KpJvYUNXSYeWqc0vnsAq9wJJgvWv5pTh6IYhd120YZTQ',
    signature:        'Yw1ETAM+6PGA0T65IAEShwyDLDQqw7M8qpFzLpG+Nm8='
  }
}

The certificate is always issued by a client, called the issuer, in this case issuing-client-id. The issuer's accessToken will be used to sign the temporary credentials.

The clientId used with the temporary credentials may be any id for which the issuer has the scope auth:create-client:<clientId>.

In the certificate the version must always be 1 (at least for now).

The scopes property is a list of scopes the temporary credentials should have access to, this must be satisfied by the issuer's scopes. In other words, the temporary credentials cannot have any scope that the issuer does not have.

The start and expiry properties are the validity start and expiration of the certificate, respectively. Both start and expiry are in milliseconds since unix epoch, and these cannot be more than 31 days apart. Notice that it is allowed to issue temporary credentials that take effect in the future, useful for delegating access to scheduled tasks.

The seed property is a 44 character string of random characters, it used for construction of the accessToken, as detailed later.

The signature property validates the authenticity of the certificate and is generated as detailed below.

Signature Generation

The signature for a certificate is generated by the issuer, using its access token. The issuer does this by generating a base64 encoded sha256 HMAC signature of the following string:

version:1\n
clientId:<clientId>\n
issuer:<issuer>\n
seed:<seed>\n
start:<start>\n
expiry:<expiry>\n
scopes:\n
<scopes[0]>\n
<scopes[1]>\n
...
<scopes[n]>

where <clientId> is the id that will be used with the temporary credentials. As described above, this can be any id that the issuer is permitted to create.

In the certificate example from previous section, the string to sign would be:

version:1\n
clientId:temporary-cred-client-id\n
issuer:issuing-client-id\n
seed:KpJvYUNXSYeWqc0vnsAq9wJJgvWv5pTh6IYhd120YZTQ\n
start:1410399435102\n
expiry:1410399497349\n
scopes:\n
ScopeA\n
ScopeB

An authenticating server will validate the certificate on every request, using the above signature algorithm.

Construction of accessToken

The accessToken must also be generated by the issuer. The issuer does this by generating a sha256 HMAC signature of the seed from the certificate, signed with the issuers accessToken.

The signature must be encoded using URL-safe base64 encoding without = padding. See RFC 4648, sec. 5 for details on URL-safe base64. Basically it amounts to replacing + with - and replacing / with _, and then drop = padding.

The resulting HMAC signature is the accessToken, which should be given to client that will be using the temporary credentials. The accessToken will be reconstructed on the authenticating server for each request.

Anonymous Temporary Credentials

For backward compatibility, TaskCluster supports "anonymous" temporary credentials. For these credentials, the temporary credentials use the issuer's clientId.

In this case, the certificate does not include an issuer property, and the clientId and issuer lines are omitted from the string used to generate the signature:

version:1\n
seed:<seed>\n
start:<start>\n
expiry:<expiry>\n
scopes:\n
<scopes[0]>\n
<scopes[1]>\n
...
<scopes[n]>

We recommend that you always use named temporary credentials, with a descriptive clientId, to assist in debugging and logging.