AppRoles konfigurieren und verwenden

Zuletzt aktualisiert am 26. Aug. 2026

AppRole ist eine Authentifizierungsmethode für Anwendungen und automatisierte Workloads. Dabei authentifiziert sich eine Anwendung mit einer Role-ID und einer Secret-ID statt mit Benutzername und Passwort und erhält ein Vault-kompatibles Token.

Funktionsweise der AppRole-Authentifizierung

Eine AppRole besteht aus:

Einer Role-ID, die die AppRole identifiziert.
Einer oder mehreren Secret-IDs, mit denen sich ein Workload für die AppRole authentifiziert.
Einer Berechtigung für Lesezugriff oder Lese- und Schreibzugriff auf die Secrets Manager-Instanz.
Einer standardmäßigen Lebensdauer und einem Nutzungslimit für neu erstellte Secret-IDs.

Die Role-ID bleibt bestehen, bis Sie die AppRole löschen. Sie können Secret-IDs unabhängig voneinander erstellen und löschen. Dadurch können Sie Zugangsdaten rotieren, ohne die Role-ID zu ändern.

Einstellungen für Secret-IDs

Beim Erstellen einer AppRole legen Sie die folgenden Standardwerte fest:

Einstellung	Standardwert	Beschreibung
`write`	`false`	Setzen Sie den Wert auf `true`, um Lese- und Schreibzugriff zu gewähren. Standardmäßig erhält die AppRole nur Lesezugriff.
`secret_id_num_uses`	`0`	Maximale Anzahl erfolgreicher Anmeldungen mit einer neu erstellten Secret-ID. `0` bedeutet unbegrenzte Nutzung.
`secret_id_ttl`	`0s`	Lebensdauer einer neu erstellten Secret-ID. `0s` bedeutet, dass die Secret-ID zeitlich unbegrenzt gültig ist.

Geben Sie zuerst eine ganze Zahl und danach s für Sekunden, m für Minuten oder h für Stunden an, zum Beispiel 30s, 15m oder 24h. Verwenden Sie für einen Tag 24h; 1d wird nicht unterstützt.

Die Einstellungen werden beim Erstellen in die Secret-ID übernommen. Wenn Sie die AppRole aktualisieren, ändern Sie die Standardwerte für zukünftige Secret-IDs. Bestehende Secret-IDs werden nicht geändert.

Voraussetzungen

Sie haben Zugriff auf die AppRole Private Preview.
Sie haben eine Secrets Manager-Instanz erstellt.
Sie verfügen über ein Zugriffstoken mit der Berechtigung, die Instanz zu aktualisieren.
Sie kennen die Projekt-ID und die ID der Secrets Manager-Instanz.
Die Quell-IP des Workloads ist in der Zugriffssteuerungsliste (ACL) der Instanz erlaubt.

Legen Sie die Werte für die folgenden Beispiele fest:

export AUTH_TOKEN=<Ihr-Zugriffstoken>
export PROJECT_ID=<Ihre-Projekt-ID>
export INSTANCE_ID=<Ihre-Instanz-ID>
export SM_API_URL=https://secrets-manager.api.eu01.stackit.cloud
export SM_INSTANCE_URL=https://prod.sm.eu01.stackit.cloud

AppRole erstellen

Erstellen Sie eine AppRole mit Lesezugriff für einen automatisierten Workload:

curl --request POST \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Read-only deployment workload",
    "write": false,
    "secret_id_num_uses": 0,
    "secret_id_ttl": "24h"
  }' \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles"

Die Antwort enthält die generierte Role-ID:

{
  "role_id": "3f7ab266-3a25-43e0-8db1-3f9af8c80782",
  "write": false,
  "secret_id_num_uses": 0,
  "secret_id_ttl": "24h0m0s",
  "description": "Read-only deployment workload"
}

Speichern Sie die zurückgegebene role_id für die folgenden Anfragen:

export ROLE_ID=<Ihre-Role-ID>

Secret-ID erstellen

Generieren Sie eine Secret-ID für die AppRole:

curl --request POST \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"description":"Production deployment credential"}' \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles/$ROLE_ID/secretids"

Die Antwort enthält die Secret-ID und ihre Version:

{
  "version": 1,
  "secret_id": "07c053e5-c548-4873-bb93-9a741cd96aa3",
  "num_uses": 0,
  "ttl": "24h0m0s",
  "description": "Production deployment credential"
}

Speichern Sie secret_id sofort in einem sicheren Speicher für Zugangsdaten. Verwenden Sie den Wert von version als Kennung, wenn Sie die Secret-ID später auflisten, aktualisieren oder löschen.

Mit AppRole anmelden

Senden Sie die Role-ID und Secret-ID an den Vault-kompatiblen AppRole-Anmeldeendpunkt:

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "role_id": "<Ihre-Role-ID>",
    "secret_id": "<Ihre-Secret-ID>"
  }' \
  "$SM_INSTANCE_URL/v1/auth/approle/login"

Das Token wird in auth.client_token zurückgegeben:

{
  "auth": {
    "client_token": "<Vault-Token>",
    "lease_duration": 900,
    "renewable": true
  }
}

Wiederholte Anmeldeversuche mit einer falschen Secret-ID können die AppRole-Authentifizierung für die Role-ID vorübergehend sperren. Das Erstellen oder Rotieren einer Secret-ID hebt eine aktive Sperre nicht sofort auf. Informationen zu Antworten und erneuten Versuchen finden Sie unter Sperren bei der Authentifizierung behandeln.

Verwenden Sie das Token als X-Vault-Token-Header, wenn Sie auf Secrets zugreifen:

curl --header "X-Vault-Token: <Vault-Token>" \
  "$SM_INSTANCE_URL/v1/$INSTANCE_ID/data/<Secret-Name>"

Empfehlungen zur Erneuerung und zum Widerruf von Token finden Sie unter Sitzungs- und Token-Handling.

Secret-ID rotieren

So rotieren Sie eine Secret-ID ohne Unterbrechung des Zugriffs:

Erstellen Sie eine weitere Secret-ID für dieselbe AppRole.
Speichern Sie die neue Secret-ID im sicheren Speicher für Zugangsdaten des Workloads.
Konfigurieren Sie den Workload für die Verwendung der neuen Secret-ID.
Prüfen Sie, ob sich der Workload authentifizieren kann.
Löschen Sie die bisherige Secret-ID über ihre Version.

Löschen Sie die bisherige Secret-ID:

export SECRET_ID_VERSION=<Version-der-bisherigen-Secret-ID>

curl --request DELETE \
  --header "Authorization: Bearer $AUTH_TOKEN" \
  "$SM_API_URL/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/approles/$ROLE_ID/secretids/$SECRET_ID_VERSION"

Wenn Sie eine AppRole löschen, werden alle zugehörigen Secret-IDs ungültig.

Endpunkte für die Verwaltung

Operation	Methode und Pfad
AppRoles auflisten	`GET /v1/projects/{projectId}/instances/{instanceId}/approles`
AppRole erstellen	`POST /v1/projects/{projectId}/instances/{instanceId}/approles`
AppRole abrufen	`GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}`
AppRole aktualisieren	`PUT /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}`
AppRole löschen	`DELETE /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}`
Secret-IDs auflisten	`GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids`
Secret-ID erstellen	`POST /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids`
Metadaten einer Secret-ID abrufen	`GET /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}`
Beschreibung einer Secret-ID aktualisieren	`PUT /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}`
Secret-ID löschen	`DELETE /v1/projects/{projectId}/instances/{instanceId}/approles/{roleId}/secretids/{secretIdVersion}`

Beim Auflisten oder Abrufen der Metadaten wird die Secret-ID selbst nicht zurückgegeben. Die vollständigen Strukturen der Anfragen und Antworten finden Sie in der Secrets Manager API-Spezifikation.

Empfehlungen zur Sicherheit

Verwenden Sie für jeden Workload oder jede klar abgegrenzte Umgebung eine eigene AppRole.
Gewähren Sie nur Lesezugriff, wenn der Workload keine Secrets erstellen oder ändern muss.
Legen Sie eine begrenzte Lebensdauer und ein Nutzungslimit fest, wenn der Workload dies zulässt.
Speichern Sie Secret-IDs in einem dafür vorgesehenen sicheren Speicher und niemals im Quellcode.
Schreiben Sie keine Role-IDs, Secret-IDs oder Vault-Token in Anwendungsprotokolle.
Verwenden Sie mehrere Secret-IDs, um Zugangsdaten zu rotieren, ohne die Role-ID zu ändern.
Löschen Sie nicht mehr verwendete Secret-IDs sofort.
Erneuern Sie ein vorhandenes Vault-Token, anstatt sich für jede API-Anfrage erneut anzumelden.