Authentication

To authenticate to all of the STACKIT Developer Tools, you can use a service account. For the SDK and the Terraform Provider, this is the only supported way of authentication.

For the CLI, you can also login with your personal user account.

For more details for the specific tools, refer to:

• SDK
• Terraform Provider
• CLI

Create a service account

If you don't have a service account for your project, you will need to create one and assign it the necessary permissions, e.g. editor. There are two ways to do it:

• Using the STACKIT Portal:
  • Create a Service Account
  • Assign permissions to a Service Account
• Using the STACKIT CLI:
  • Login with your personal user: stackit auth login
  • Create a Service Account: stackit service-account create --name my-service-account
  • Assign permissions to a Service Account: stackit project member add my-service-account@email.com --role editor

Authentication flows

There are two ways to authenticate:

• Key flow (recommended)
• Token flow

When setting up authentication, the tools will always try to use the key flow by default and search for credentials in several locations, following a specific order:

1. Explicit configuration, e.g. by using the option config.WithServiceAccountKeyPath("path/to/sa_key.json") in the SDK

2. Environment variable, e.g. by setting STACKIT_SERVICE_ACCOUNT_KEY_PATH

3. Credentials file

   The SDK will check the credentials file located in the path defined by the STACKIT_CREDENTIALS_PATH env var, if specified, or in $HOME/.stackit/credentials.json as a fallback. The credentials file should be a json and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example:

   {
     "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
     "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
   }

   CODE

Key flow

The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `editor`.

To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.

When creating the service account key, a new pair can be created automatically, which will be included in the service account key. This will make it much easier to configure the key flow authentication in the tools, by just providing the service account key.

Optionally, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the tools, additionally to the service account key. Check the STACKIT Knowledge Base for an example of how to create your own key-pair.

Create a service account key in the CLI

1. In the CLI, run `stackit service-account key create --email <SERVICE_ACCOUNT_EMAIL>`

Alternatively: Create a service account key in the STACKIT Portal

1. Go to the Service Accounts tab
2. Choose a Service Account
3. Go to Service Account Keys to create a key.

For more details, see Create a service account key

Save the content of the service account key by copying it and saving it in a JSON file

The expected format of the service account key is a json with the following structure:

{
  "id": "uuid",
  "publicKey": "public key",
  "createdAt": "2023-08-24T14:15:22Z",
  "validUntil": "2023-08-24T14:15:22Z",
  "keyType": "USER_MANAGED",
  "keyOrigin": "USER_PROVIDED",
  "keyAlgorithm": "RSA_2048",
  "active": true,
  "credentials": {
    "kid": "string",
    "iss": "my-sa@sa.stackit.cloud",
    "sub": "uuid",
    "aud": "string",
    (optional) "privateKey": "private key when generated by the SA service"
  }
}

Configure the service account key for authentication

1. Explicitly
   1. SDK: using the configuration options config.WithServiceAccountKey or config.WithServiceAccountKeyPath
   2. Terraform Provider: setting the fields service_account_key or service_account_key_path in the provider block
   3. CLI: stackit auth activate-service-account --service-account-key-path path/to/service_account_key.json
2. Setting the environment variable STACKIT_SERVICE_ACCOUNT_KEY_PATH
3. Setting STACKIT_SERVICE_ACCOUNT_KEY_PATH in the credentials file (see above)
4. Optionally, only if you have provided your own RSA key-pair when creating the service account key, you also need to configure your private key (takes precedence over the one included in the service account key, if present). The private key must be PEM encoded and can be provided using one of the options below:
   1. Explicitly:
      1. SDK: using the configuration options config.WithPrivateKey or config.WithPrivateKeyPath
      2. Terraform Provider: setting the fields private_key or private_key_path in the provider block
      3. CLI: stackit auth activate-service-account --service-account-key-path path/to/service_account_key.json --private-key-path path/to/key.pem
   2. Setting the environment variable STACKIT_PRIVATE_KEY_PATH
   3. Setting STACKIT_PRIVATE_KEY_PATH in the credentials file (see above)

The tools will search for the keys and, if valid, will use them to get access and refresh tokens which will be used to authenticate all the requests.

Token flow

Using this flow is less secure since the token is long-lived. You can provide the token in several ways:

1. Explicitly
   1. SDK: using the configuration options config.WithToken
   2. Terraform Provider: setting the fields service_account_token the provider block
   3. CLI: stackit auth activate-service-account --service-account-token TOKEN
2. Setting the environment variable STACKIT_SERVICE_ACCOUNT_TOKEN
3. Setting STACKIT_SERVICE_ACCOUNT_TOKEN in the credentials file (see above)

Examples

• SDK
• Terraform Provider
• CLI