Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

deprecating CI keys #1553

Merged
merged 17 commits into from
Nov 21, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
first iteration
  • Loading branch information
SimonWallner committed Nov 11, 2024
commit ff2adcf8c1b88105400112b088c4d9b35cfd0715
248 changes: 36 additions & 212 deletions content/en/getting-started/auth-token/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,242 +2,66 @@
title: "Auth Token"
weight: 20
description: >
Configure your Auth Token to start LocalStack
Configure your auth token to access and activate LocalStack.
---
### Introduction

## Introduction
Auth tokens allow you to activate the LocalStack emulator and are also used access your workspace and additional services like Cloud Pods.

The Auth Token is a personal identifier used for user authentication outside the LocalStack Web Application, particularly in conjunction with the LocalStack core cloud emulator.
Its primary functions are to retrieve the user's license and enable access to advanced features, effectively replacing the older developer API keys.
Auth tokens exist in 2 varieties.
A **personal developer auth token** and a **CI auth token:**

The Auth Token remains unchanged unless manually rotated by the user, regardless of any license assignment changes.
You can locate your Auth Token on the [Getting Started page](https://app.localstack.cloud/getting-started) or the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) in the LocalStack Web Application.
- The **developer auth token** is closely associated with a specific user in a specific workspace.
Every user has an auth token.
It can not be deleted, but it can be rotated for security purposes if required.
It can be found on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens)

{{< callout "warning" >}}
- Previously, API keys were required to activate the LocalStack core cloud emulator.
These API keys are now being replaced by Auth Tokens.
- Currently, LocalStack supports both API Keys and Auth Tokens.
However, API Keys will be discontinued in the upcoming major release of LocalStack.
- To update your LocalStack configuration, replace your API Key with an Auth Token.
Use the `LOCALSTACK_AUTH_TOKEN` environment variable in place of `LOCALSTACK_API_KEY`.
{{< /callout >}}

## Managing your License

To use LocalStack, a license is required.
You can get a license by registering on the [LocalStack Web Application](https://app.localstack.cloud/sign-up).
Choose between a 14-day trial or explore additional features with our paid offering.
During the trial period, you are welcome to use all the features of LocalStack.

After initiating your trial or acquiring a license, proceed to assign it to a user by following the steps outlined below:

- Visit the [Users & Licenses page](https://app.localstack.cloud/workspace/members).
- Select a user in the **Workspace Members** section for license assignment.
- Define user's role via the **Member Role** dropdown.
Single users automatically receive the **Admin** role.
- Toggle **Advanced Permissions** to set specific permissions.
Single users automatically receive full permissions.
- Click **Save** to complete the assignment.
Single users assign licenses to themselves.

{{< img src="assigning-a-license.png" class="img-fluid shadow rounded" width="800" >}}
<br><br>

If you have joined a workspace, you need to be assigned a license by the workspace administrator.
In case of switching workspaces or licenses, you need to make sure that you are assigned to the correct license.

{{< callout "note" >}}
If you do not assign a license, you will not be able to use LocalStack even if you have a valid Auth token.
{{< /callout >}}

To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license).
You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) to view your Auth Token.

## Configuring your Auth Token

LocalStack requires the `LOCALSTACK_AUTH_TOKEN` environment variable to contain your Auth Token.
You can configure your Auth Token in several ways, depending on your use case.
The following sections describe the various methods of setting your Auth Token.
- The **CI auth token** is not tied to a specific user and is intended for use in CI environments and other non developer related contexts.
CI auth tokens live in the workspace, and can be managed by members with the necessary permissions.
CI auth tokens can also be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens)

{{< callout "warning">}}
- It's crucial to keep your Auth Token confidential.
Do not include it in source code management systems, such as Git repositories.
- Be aware that if an Auth Token is committed to a public repository, it's at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it.
- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token).
{{< /callout >}}

### LocalStack CLI

You should set the `LOCALSTACK_AUTH_TOKEN` environment variable either before or during the startup of LocalStack using the `localstack` command-line interface (CLI).

{{< tabpane >}}
{{< tab header="macOS/Linux" lang="shell" >}}
localstack auth set-token <YOUR_AUTH_TOKEN>
localstack start
{{< /tab >}}
{{< tab header="Windows" lang="powershell" >}}
$env:LOCALSTACK_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"; localstack start
{{< /tab >}}
{{< /tabpane >}}

{{< callout "note" >}}
1. You can alternatively set the `LOCALSTACK_AUTH_TOKEN` environment variable in your shell session.
This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation.
2. The `localstack auth set-token` command is only available for `localstack` CLI and cannot be used with a Docker/Docker Compose setup.
- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it.
- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens).
{{< /callout >}}

You have the option to run your LocalStack container in the background by appending the `-d` flag to the `localstack start` command.

The `localstack` CLI automatically detects the Auth Token and appropriately conveys it to the LocalStack container.

{{< callout "note" >}}
If you are using LocalStack with an Auth Token, it's necessary to download the [LocalStack Pro image](https://docs.localstack.cloud/references/docker-images/#localstack-pro-image), which includes Pro services and several advanced features.
{{< /callout >}}

### Docker

To start LocalStack via Docker, you need to provide the Auth Token using the `-e` flag, which is used for setting environment variables.

{{< command "hl_lines=5" >}}
$ docker run \
--rm -it \
-p 4566:4566 \
-p 4510-4559:4510-4559 \
-e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \
localstack/localstack-pro
{{< / command >}}

For more information about starting LocalStack with Docker, take a look at our [Docker installation](https://docs.localstack.cloud/getting-started/installation/#docker) guide.

### Docker Compose

To start LocalStack using `docker compose`, you have to include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file:
## Activating LocalStack

```yaml
environment:
- LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN- }
```
To activate LocalStack Pro and to access additional services, simply set the auth token in the `LOCALSTACK_AUTH_TOKEN` environment variable.
This will make it also available to Docker/Docker Compose setups.

You can manually set the Auth Token, or use the `export` command to establish the Auth Token in your current shell session.
This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation.
If you are only starting the LocalStack instance via the LocalStack CLI with `localstack start` then you can configure the auth token with `localstack auth set-token <YOUR_AUTH_TOKEN>`.

## Licensing-related configuration
### Managing your License

To avoid logging any licensing-related error messages, set `LOG_LICENSE_ISSUES=0` in your environment.
Refer to our [configuration guide](https://docs.localstack.cloud/references/configuration/#localstack-pro) for more information.

## Checking license activation

The simplest method to verify if LocalStack is active is by querying the health endpoint for a list of running services:

{{< tabpane text=true >}}
{{< tab header="macOS/Linux" lang="shell" >}}

{{< command >}}
$ curl http://localhost:4566/_localstack/info | jq
{{< / command >}}

{{< /tab >}}
{{< tab header="Windows" lang="powershell" >}}

{{< command >}}
$ Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json
{{< / command >}}

{{< /tab >}}
{{< /tabpane >}}

The following output would be retrieved:

```bash
{
"version": "3.0.0:6dd3f3d",
"edition": "pro",
"is_license_activated": true,
"session_id": "7132da5f-a380-44ca-8897-6f0fdfd7b1c9",
"machine_id": "0c49752c",
"system": "linux",
"is_docker": true,
"server_time_utc": "2023-11-21T05:41:33",
"uptime": 161
}
````

You can notice the `edition` field is set to `pro` and the `is_license_activated` field is set to `true`.
Another way to confirm this is by checking the logs of the LocalStack container for a message indicating successful license activation:

{{< command >}}
[...] Successfully activated license
{{< / command >}}

Otherwise, check our collected most [common activation issues](#common-activation-issues).

## Rotating the Auth Token

Your personal Auth Token provides full access to your workspace and LocalStack license.
It's important to treat auth tokens as confidential, avoiding sharing or storing them in source control management systems (SCMs) like Git.

If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay.
When you reset a token, the old one is immediately deactivated, losing its ability to access your license or workspace.
It is not possible to restore previous tokens.

To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) and select the **Reset Auth Token** option.

### Configuring your CI environment

For use in Continuous Integration (CI) or automated test environments, a CI key is necessary.
Refer to our [CI documentation]({{< ref "user-guide/ci" >}}) for guidance on securely handling secrets, including storing your CI key in these environments.

To configure your CI key, you need to set the `LOCALSTACK_API_KEY` environment variable to your CI key.
You can find your CI key on the [CI Keys page](https://app.localstack.cloud/workspace/ci-keys) in the LocalStack Web Application.

## Common activation issues

Starting from version 2.0.0, the `localstack/localstack-pro` image in LocalStack demands a successful license activation for startup.
If the activation of the license is unsuccessful, LocalStack will exit and display error messages.

```bash
===============================================
License activation failed! 🔑❌

Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your auth token or API key in the LocalStack web app https://app.localstack.cloud.

Due to this error, Localstack has quit. LocalStack pro features can only be used with a valid license.

- Please check that your credentials are set up correctly and that you have an active license.
You can find your credentials in our webapp at https://app.localstack.cloud.
- If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`.
```
To use LocalStack, a license is required.
You can get a license by registering on the [LocalStack Web Application](https://app.localstack.cloud/sign-up).
Choose between a 14-day trial or explore additional features with our paid offering.
During the trial period, you are welcome to use all the features of LocalStack.

The key activation in LocalStack may fail for several reasons, and the most common ones are listed below in this section.
After starting your trial or subscribing to a plan, you can manage the license assignments on the [Users & Licenses page](https://app.localstack.cloud/workspace/members):

### Missing Credentials
## Configuring CI environments

You need to provide either an Auth Token or an API Key to start the LocalStack Pro image successfully.
You can find your Auth Token or API Key on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) or the [Legacy API Key page](https://app.localstack.cloud/workspace/api-keys) in the LocalStack Web Application.
CI environments are also configured the same way but **require the use of a CI auth token**. A developer auth token can not be used in CI.

Check failure on line 48 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Max 1 sentence should be on a line

content/en/getting-started/auth-token/index.md:48:91 max-one-sentence-per-line Max 1 sentence should be on a line [Context: ". A developer "] https://github.com/aepfli/markdownlint-rule-max-one-sentence-per-line

Check failure on line 48 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Max 1 sentence should be on a line

content/en/getting-started/auth-token/index.md:48:91 max-one-sentence-per-line Max 1 sentence should be on a line [Context: ". A developer "] https://github.com/aepfli/markdownlint-rule-max-one-sentence-per-line
CI auth tokens can also be found on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) page and are configured similarly to develop auth tokens.

If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token or use the following command to set it up:
## Activating older versions of localstack ( < v3.0)

{{< command >}}
$ localstack auth set-token <YOUR_AUTH_TOKEN>
{{< / command >}}
Before auth tokens were introduced, _API keys_ and the `LOCALSTACK_API_KEY` environment variable were used.

### Invalid License
To allow backwards compatibility with the new auth tokens, 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.

Check failure on line 55 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Max 1 sentence should be on a line

content/en/getting-started/auth-token/index.md:55:160 max-one-sentence-per-line Max 1 sentence should be on a line [Context: "ariable. Just "] https://github.com/aepfli/markdownlint-rule-max-one-sentence-per-line

Check failure on line 55 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Max 1 sentence should be on a line

content/en/getting-started/auth-token/index.md:55:160 max-one-sentence-per-line Max 1 sentence should be on a line [Context: "ariable. Just "] https://github.com/aepfli/markdownlint-rule-max-one-sentence-per-line

The issue may occur if there is no valid license linked to your account due to expiration or if the license has not been assigned.
You can check your license status in the LocalStack Web Application on the [My License page](https://app.localstack.cloud/workspace/my-license).
### Sunsetting legacy API keys (early 2025)

### License Server Unreachable
In early 2025 we will start phasing out legacy API keys completely.
After the sunsetting period, it will not be able to activate and use legacy API and legacy CI keys with LocalStack.

LocalStack initiates offline activation when the license server is unreachable, requiring re-activation every 24 hours.
Log output may indicate issues with your machine resolving the LocalStack API domain, which can be verified using a tool like `dig`:
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.

{{< command >}}
$ dig api.localstack.cloud
{{< / command >}}
The schedule will be communicated in advance, giving users enough time to make the switch to the new auth tokens.

If the result shows a status other than `status: NOERROR`, your machine is unable to resolve this domain.
Certain corporate DNS servers may filter requests to specific domains.
Kindly reach out to your network administrator to safelist `localstack.cloud` domain.

Check failure on line 67 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Multiple consecutive blank lines

content/en/getting-started/auth-token/index.md:67 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md012.md

Check failure on line 67 in content/en/getting-started/auth-token/index.md

View workflow job for this annotation

GitHub Actions / Markdown Lint

Multiple consecutive blank lines

content/en/getting-started/auth-token/index.md:67 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md012.md
If you have any further problems concerning your license activation, or if the steps do not help, do not hesitate to [contact us](https://localstack.cloud/contact/).
16 changes: 8 additions & 8 deletions content/en/getting-started/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ To resolve the issue follow the steps:
Additionally, it’s important to clear the cached certificate from your host machine as mentioned above.
2. **Use HTTP Instead of HTTPS**: Where possible, use `http://` instead of `https://` to avoid issues related to the revoked certificates.
This workaround works with most browsers.
However, Safari requires additional steps:
However, Safari requires additional steps:
2.1. **Safari Users**: To make this work, you’ll need to first navigate to the page in a new tab and accept the security warning.
To do this, make sure that LocalStack is started with `SKIP_SSL_CERT_DOWNLOAD=1` and that you have cleared the cached certificate as mentioned above.
Once you’ve accepted the warning, you should be able to proceed.
Expand Down Expand Up @@ -280,20 +280,20 @@ $ curl localhost:4566/_localstack/health | jq
{{< / command >}}

If a Pro-only [service]({{< ref "aws" >}}) -- like [XRay]({{< ref "xray" >}}) -- is running, LocalStack Pro or Enterprise has started successfully.
If your auth token is invalid, you will see an error message like this in the logs of LocalStack:
If your Auth Token is invalid, you will see an error message like this in the logs of LocalStack:

```bash
license activation failed! Reason: ...
```

If this error occurs, something is wrong with your auth token or license.
Make sure your auth token is set correctly (check for typos!) and your license is valid.
If the auth token still does not work, please [contact us](https://localstack.cloud/contact/).
If this error occurs, something is wrong with your Auth Token or license.
Make sure your Auth Token is set correctly (check for typos!) and your license is valid.
If the Auth Token still does not work, please [contact us](https://localstack.cloud/contact/).

### How are CI credits in LocalStack calculated?

A CI key allows you to use LocalStack in your CI environment.
Every activation of a CI key consumes one build credit.
A CI Auth Token allows you to use LocalStack in your CI environment.
Every activation with a CI Auth Token consumes one CI credit.
This means that with every build triggered through the LocalStack container you will consume one credit.
To understand the CI pricing across our product tiers, follow up with our [LocalStack in CI]({{<ref "user-guide/ci">}}) documentation.

Expand Down Expand Up @@ -329,7 +329,7 @@ $ dig api.localstack.cloud
If the result has some other status than `status: NOERROR,` your machine cannot resolve this domain.

Some corporate DNS servers might filter requests to certain domains.
Contact your network administrator to safelist`localstack.cloud` domains.
Contact your network administrator to safelist `localstack.cloud` domains.

### How does LocalStack Pro handle security patches and bug fixes?

Expand Down
Loading
Loading