Skip to content

OpenID Connect (OIDC)»

Hint

For this feature to work, the service you are integrating with needs to be able to access your Spacelift instance. For example, if you have deployed your Spacelift instance with an internal rather than public-facing load balancer, you will not be able to use OIDC Federation for AWS role assumption.

OpenID Connect is a federated identity technology that allows you to exchange short-lived Spacelift credentials for temporary credentials valid for external service providers like AWS, GCP, Azure, HashiCorp Vault etc. This allows you to use Spacelift to manage your infrastructure on these cloud providers without the need of using static credentials.

OIDC is also an attractive alternative to our native AWS integration in that it implements a common protocol, requires no additional configuration on the Spacelift side, supports a wider range of external service providers and empowers the user to construct more sophisticated access policies based on JWT claims.

It is not the purpose of this document to explain the details of the OpenID Connect protocol. If you are not familiar with it, we recommend you read the OpenID Connect specification or GitHub's excellent introduction to security hardening with OpenID Connect.

About the Spacelift OIDC token»

The Spacelift OIDC token is a JSON Web Token that is signed by Spacelift and contains a set of claims that can be used to construct a set of temporary credentials for the external service provider. The token is valid for an hour and is available to every run in any paid Spacelift account. The token is available in the SPACELIFT_OIDC_TOKEN environment variable and in the /mnt/workspace/spacelift.oidc file.

Standard claims»

The token contains the following standard claims:

  • iss - the issuer of the token - the URL of your Spacelift account, for example https://demo.app.spacelift.io. This is unique for each Spacelift account;
  • sub - the subject of the token - some information about the Spacelift run that generated this token. The subject claim is constructed as follows: space:<space_id>:(stack|module):<stack_id|module_id>:run_type:<run_type>:scope:<read|write>. For example, space:legacy:stack:infra:run_type:TRACKED:scope:write. Individual values are also available as separate custom claims - see below;
  • aud - the audience of the token - the hostname of your Spacelift account. For example, demo.app.spacelift.io. This is unique for each Spacelift account;
  • exp - the expiration time of the token - the time at which the token will expire, in seconds since the Unix epoch. The token is valid for one hour;
  • iat - the time at which the token was issued, in seconds since the Unix epoch;
  • jti - the unique identifier of the token;
  • nbf - the time before which the token is not valid, in seconds since the Unix epoch. This is always set to the same value as iat;

Custom claims»

The token also contains the following custom claims:

  • spaceId - the ID of the space in which the run that owns the token was executed;
  • callerType - the type of the caller, ie. the entity that owns the run - either stack or module;
  • callerId - the ID of the caller, ie. the stack or module that generated the run;
  • runType - the type of the run (PROPOSED, TRACKED, TASK, TESTING or DESTROY;
  • runId - the ID of the run that owns the token;
  • scope - the scope of the token - either read or write.

About scopes»

Whether the token is given read or write scope depends on the type of the run that generated the token. Proposed runs get a read scope, while tracked, testing and destroy runs as well as tasks get a write scope. The only exception to that rule are tracked runs whose stack is not set to autodeploy. In that case, the token will have a read scope during the planning phase, and a write scope during the apply phase. This is because we know in advance that the tracked run requiring a manual approval should not perform write operations before human confirmation.

Note that the scope claim, as well as other claims presented by the Spacelift token are merely advisory. It depends on you whether you want to control access to your external service provider based on the scope of the token or on some other claim like space, caller or run type. In other words, Spacelift just gives you the data and it's up to you to decide whether and how to use it.

Using the Spacelift OIDC token»

You can follow guidelines under this section to see how to use the Spacelift OIDC token to authenticate with AWS, GCP, Azure, and HashiCorp Vault. In particular, we will focus on setting up the integration and using it from these services' respective Terraform providers