mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-07-05 19:51:52 +00:00
Johannes Engler
a2824f7166
Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Sergio Garcia <hello@mistercloudsec.com> Co-authored-by: Hugo P.Brito <hugopbrit@gmail.com> Co-authored-by: Hugo Pereira Brito <101209179+HugoPBrito@users.noreply.github.com>
101 lines
4.5 KiB
Plaintext
101 lines
4.5 KiB
Plaintext
---
|
|
title: 'StackIT Authentication'
|
|
---
|
|
|
|
Prowler authenticates with StackIT using a **service account key file**. The StackIT SDK signs the RSA challenge in the key file and mints/refreshes access tokens internally for the life of the scan, so no manual token rotation is needed.
|
|
|
|
## Service Account Key
|
|
|
|
StackIT uses RSA key-pair based service account keys. They are issued once, must be stored securely, and are read by the SDK on every scan to mint short-lived access tokens transparently.
|
|
|
|
### Option 1: Create the Key via the StackIT Portal
|
|
|
|
1. Open the [StackIT Portal](https://portal.stackit.cloud/) and select your project.
|
|
2. In the left sidebar, click **Service Accounts**.
|
|
3. Create a service account if you do not have one already. Assign:
|
|
- `iaas.viewer` for the IaaS security group checks currently shipped, or
|
|
- `project.owner` if you want to cover any future service Prowler adds.
|
|
4. Open the service account and go to **Service Account Keys**.
|
|
5. Click **Create key** and choose **STACKIT-generated key pair** (recommended). Download the resulting JSON file and store it securely (for example, `~/.stackit/sa-key.json`). The private material is only shown once.
|
|
|
|
### Option 2: Create the Key via the StackIT CLI
|
|
|
|
```bash
|
|
# Install the StackIT CLI from https://github.com/stackitcloud/stackit-cli first
|
|
stackit service-account key create --email my-service-account@example.com
|
|
```
|
|
|
|
## Project ID
|
|
|
|
Your StackIT project ID is a UUID. You can find it in:
|
|
|
|
1. The portal URL when viewing the project: `https://portal.stackit.cloud/projects/{PROJECT_ID}/...`
|
|
2. The project settings page
|
|
3. `stackit project list`
|
|
|
|
## Passing Credentials to Prowler
|
|
|
|
You can give Prowler either the **path** to the key file on disk or the **inline JSON content** of the key. Both go through the same StackIT SDK flow and refresh access tokens internally.
|
|
|
|
### Option A: Key File Path (workstation, persistent agents)
|
|
|
|
Recommended when the key is stored on disk.
|
|
|
|
```bash
|
|
export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json"
|
|
export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc"
|
|
|
|
prowler stackit
|
|
```
|
|
|
|
Or as CLI flags:
|
|
|
|
```bash
|
|
prowler stackit \
|
|
--stackit-service-account-key-path ~/.stackit/sa-key.json \
|
|
--stackit-project-id 12345678-1234-1234-1234-123456789abc
|
|
```
|
|
|
|
<Note>
|
|
Keep the key file outside of source control and lock it down with `chmod 600 ~/.stackit/sa-key.json`. Anyone with the JSON can mint access tokens for the service account.
|
|
</Note>
|
|
|
|
### Option B: Inline Key Content (CI/CD, secret managers)
|
|
|
|
Recommended when the key is fetched at run time from a secret manager (GitHub Actions secret, AWS Secrets Manager, HashiCorp Vault, etc.) and you do not want to write it to disk.
|
|
|
|
```bash
|
|
export STACKIT_SERVICE_ACCOUNT_KEY="$(vault kv get -field=key stackit/sa)"
|
|
export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc"
|
|
|
|
prowler stackit
|
|
```
|
|
|
|
<Note>
|
|
Prefer the `STACKIT_SERVICE_ACCOUNT_KEY` environment variable over the matching CLI flag (`--stackit-service-account-key`); passing the secret on the command line leaks it through process listings and shell history.
|
|
</Note>
|
|
|
|
When both the inline content and a key path are set, the inline content wins.
|
|
|
|
## Credential Lookup Order
|
|
|
|
Prowler resolves credentials in this order:
|
|
|
|
1. CLI arguments: `--stackit-service-account-key`, `--stackit-service-account-key-path`, `--stackit-project-id`
|
|
2. Environment variables: `STACKIT_SERVICE_ACCOUNT_KEY`, `STACKIT_SERVICE_ACCOUNT_KEY_PATH`, `STACKIT_PROJECT_ID`
|
|
|
|
When both the inline key and the key file path are set, the inline content takes precedence.
|
|
|
|
## Token Lifetime
|
|
|
|
Access tokens are minted on demand by the SDK from the key file and refreshed before they expire. There is nothing to rotate while Prowler is running.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely Cause | Fix |
|
|
|---------|--------------|-----|
|
|
| `401 Unauthorized` during scan | Key file is missing fields, the public key is no longer registered, or the key was revoked | Re-issue the service account key in the StackIT portal and update `STACKIT_SERVICE_ACCOUNT_KEY_PATH` |
|
|
| `403 Forbidden` during scan | Service account lacks role on the project | Re-check role assignment in the StackIT portal; `iaas.viewer` is the minimum for the shipped IaaS checks |
|
|
| `StackIT project ID must be a valid UUID` | The project ID is not in UUID format | Copy the UUID from the portal URL or `stackit project list` |
|
|
| `StackIT service account credentials are required` | None of the four credential inputs is set | Export `STACKIT_SERVICE_ACCOUNT_KEY_PATH` or `STACKIT_SERVICE_ACCOUNT_KEY` (or use their CLI counterparts) before running Prowler |
|