Completing the Transition to Auth Tokens

Auth Tokens have been the default way to access and activate LocalStack for the past year. Auth Tokens are more secure and enable us to bring more features and finer grained access control in the future.

With the release of LocalStack 4.0, we will take the next step in this direction and unify everything under the Auth Token concept. This means that will no longer be issuing CI keys. This post explains what’s changing when it comes to Auth Tokens in order to help you prepare.

Two Types of Auth Tokens

There are now 2 main varieties of Auth Tokens within LocalStack:

• Personal developer Auth Token: Every user in a workspace already has a personal Auth Token. It is like a fingerprint that identifies a user and grants them access to LocalStack and services like Cloud Pods.

• (NEW) CI Auth Token: CI Auth Tokens provide an added layer of security by separating individual access from CI pipeline access, ensuring that user-specific credentials aren’t exposed in CI environments. They’re also designed to be easier to rotate within teams, allowing a shared access point for anyone maintaining CI pipelines.

  Please note: The use of CI credentials (CI Auth Token) in CI is still mandatory. A personal developer Auth Token cannot be used in CI environments.

Using the New CI Auth Token

The newly introduced CI Auth Token allows you to access and activate LocalStack just like with the legacy CI key. The CI Auth Tokens are used similarly to developer Auth Tokens and are also configured in the LOCALSTACK_AUTH_TOKEN environment variable.

Making the transition to the new CI Auth Token is easy: any CI credential created or rotated after the v4 release will automatically be a CI Auth Token. Nothing else about how CI credentials are used changes. Simply place it in the LOCALSTACK_AUTH_TOKEN environment variable in the same manner as before.

Using the Personal Auth Token

If you are already using your personal developer Auth Token to activate LocalStack, then you are already good to go – no action required!

If you are still using a legacy API key, then you’ll need to transition to your Auth Token. To find your personal developer Auth Token, go to the Auth Tokens page in the LocalStack web app and then configure it for your local environment. For more details on how to do that for either the LocalStack CLI or within Docker, visit the docs.

Sunsetting the Legacy API/CI Key Service in 2025

All existing legacy API and CI keys will remain operational until the sunsetting of the service starts in early 2025. After the sunsetting period, legacy API/CI keys will not be able to access and activate LocalStack with legacy API or CI keys.

To allow forward compatibility with older versions, we updated our back-end so that a new Auth Token can be used inside the LOCALSTACK_API_KEY variable. Just use the new Auth Token and configure it as you did with the API key in the past.

During the sunsetting period, the legacy service will undergo scheduled downtimes. This schedule will be designed to encourage the transition, but to limit the impact on users if they were not able to update yet.

The schedule will be communicated in advance, giving users enough time to make the switch to the new Auth Tokens.

To avoid any potential service disruptions, we recommend reviewing your current legacy credentials and rotating CI keys to the new Auth Token format. This ensures a seamless transition to using Auth Tokens for activating and accessing LocalStack.

LocalStack CLI

With the 4.0 release we will also make the transition in the CLI to only use Auth Tokens to identify and authenticate users. The localstack auth login command will be deprecated and the CLI will either pick up the Auth Token from the LOCALSTACK_AUTH_TOKEN environment variable or you can set the Auth Token directly in the CLI with the localstack auth set-token command.

Looking Forward to a More Secure Future

We believe that the change to the two types of Auth Tokens for individual users and CI will help reduce confusion for users and provide a foundation for future improvements to access control. As always, if you have any questions, we invite you to connect with us via the LocalStack Community Slack or via your account manager.