Przejdź do głównej zawartości

Przebieg uwierzytelniania

Ta strona opisuje, w jaki sposób aplikacje klienckie uwierzytelniają się w API REST warstwy sterowania (control-plane) VaultPAM.

Przegląd​

VaultPAM obsługuje dwa typy poświadczeń:

Typ poświadczeniaPrzypadek użyciaCzas życia
Token sesjiInteraktywne lub krótkotrwałe scenariusze automatyzacjiKontrolowany przez pole expires_in w odpowiedzi
Personal Access Token (PAT)Długotrwałe integracje, potoki CI/CDDo PAT_ABSOLUTE_MAX_TTL_DAYS (180 dni)

Oba typy to tokeny Bearer przenoszone w nagłówku Authorization w każdym żądaniu.

Pozyskiwanie tokenu sesji​

Krok 1 — POST /api/v1/auth/login​

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "operator@example.com",
  "password": "<password>"
}

Pomyślna odpowiedź (200):

{
  "access_token": "eyJ...",
  "expires_in": 3600
}

Pole expires_in jest autorytatywnym czasem życia tokenu wyrażonym w sekundach. Traktuj tę wartość jako źródło prawdy w logice wygasania tokenu — nie polegaj na żadnej zakodowanej na stałe stałej.

Odpowiedź z błędem: Wszystkie niepowodzenia uwierzytelniania zwracają jednolity błąd AUTH_FAILED, niezależnie od rzeczywistej przyczyny niepowodzenia (błędne hasło, nieznany adres e-mail, zablokowane konto). Jest to zamierzone — VaultPAM nie ujawnia, która część poświadczenia była nieprawidłowa.

{
  "error": "AUTH_FAILED",
  "message": "Authentication failed."
}

Krok 2 — Zidentyfikuj aktywną organizację​

GET /api/v1/org/memberships
Authorization: Bearer <access_token>

Odpowiedź:

{
  "active_org_id": "org_01HXZ...",
  "memberships": [
    { "org_id": "org_01HXZ...", "role": "operator" }
  ]
}

Użyj active_org_id jako wartości nagłówka X-Active-Org-Id w kolejnych żądaniach.

Wykonywanie uwierzytelnionych żądań​

Dołączaj oba nagłówki w każdym wywołaniu API:

Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Przykład:

GET /api/v1/safes
Authorization: Bearer eyJ...
X-Active-Org-Id: org_01HXZ...

Wygasanie tokenu sesji​

Tokeny sesji nie są odnawialne. Nie istnieje punkt końcowy odnawiania — żądanie do /api/v1/auth/refresh zwraca 404. Gdy token wygaśnie, uwierzytelnij się ponownie, ponownie wywołując POST /api/v1/auth/login.

Twój klient powinien:

  1. Zapisać wartość expires_in z odpowiedzi logowania.
  2. Uwierzytelnić się ponownie przed wygaśnięciem tokenu (zalecane: odjąć 60 sekund jako bufor).
  3. Ponowić pierwotne żądanie z nowym tokenem.
Brak automatycznego odnawiania

VaultPAM nie obsługuje tokenów odświeżających w stylu OAuth. Po wygaśnięciu wymagane jest ponowne zalogowanie.

Wylogowanie​

Natychmiastowe unieważnienie tokenu sesji:

POST /api/v1/auth/logout
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Odpowiedź: 204 No Content

Personal Access Tokens (PAT)​

Tokeny PAT to długotrwałe tokeny przeznaczone do automatyzacji i integracji. Mają prefiks pat_AIC_.

Utwórz token PAT​

POST /api/v1/auth/api-tokens
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>
Content-Type: application/json

{
  "name": "ci-pipeline-token",
  "scopes": ["safes.read"],
  "expires_in_days": 90
}

Wartość tokenu jest zwracana jednokrotnie w momencie utworzenia i nie można jej ponownie odzyskać.

Unieważnij token PAT​

DELETE /api/v1/auth/api-tokens/{token_id}
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Odpowiedź: 204 No Content

Egzekwowanie zakresów

Egzekwowanie zakresów jest wdrażane stopniowo dla poszczególnych rodzin punktów końcowych. Wywołania z tokenem PAT o ograniczonym zakresie do punktu końcowego spoza zadeklarowanych zakresów tokenu mogą zwrócić 403. Używaj minimalnych zakresów niezbędnych dla Twojego przypadku użycia.

Przechowywanie tokenów​

Przechowuj tokeny w bezpieczny sposób

Tokeny zapewniają pełny dostęp do API w ramach przyznanych zakresów. Niewłaściwe obchodzenie się z tokenami może prowadzić do nieautoryzowanego dostępu.

Wymagane praktyki:

  1. Nigdy nie umieszczaj tokenów w systemie kontroli wersji. Nawet w prywatnych repozytoriach tokeny w zatwierdzonym kodzie stanowią trwałe zagrożenie bezpieczeństwa. Używaj zmiennych środowiskowych lub menedżera sekretów.
  2. W środowisku produkcyjnym używaj pęku kluczy systemu operacyjnego lub menedżera sekretów. Przykłady: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, pęk kluczy jądra Linux.
  3. Nigdy nie loguj wartości tokenów. Przejrzyj konfigurację logowania, aby upewnić się, że tokeny w nagłówkach lub treściach żądań są maskowane.
  4. Unieważniaj tokeny, gdy nie są już potrzebne. Dla tokenów PAT użyj DELETE /api/v1/auth/api-tokens/{token_id}. Tokeny sesji wygasają automatycznie, ale należy je traktować jako możliwe do unieważnienia.
  5. Skonfiguruj narzędzia do skanowania sekretów tak, aby wykrywały prefiks pat_AIC_. Prefiks ten występuje we wszystkich tokenach PAT VaultPAM i pozwala narzędziom takim jak GitHub Advanced Security oznaczać przypadkowe ujawnienia.

Następne kroki​

Ostatnia aktualizacja dnia
Report an issue with this page