Ροή Ελέγχου Ταυτότητας

Η σελίδα αυτή περιγράφει τον τρόπο με τον οποίο οι εφαρμογές πελάτη πραγματοποιούν έλεγχο ταυτότητας στο VaultPAM REST API του επιπέδου ελέγχου.

---

Επισκόπηση

Το VaultPAM υποστηρίζει δύο τύπους διακριτικών:

Τύπος διακριτικού	Περίπτωση χρήσης	Διάρκεια ζωής
Διακριτικό συνεδρίας	Διαδραστική ή βραχύχρονη αυτοματοποίηση	Ελεγχόμενη από το πεδίο expires_in στην απάντηση
Personal Access Token (PAT)	Μακροχρόνιες ολοκληρώσεις, αγωγοί CI/CD	Έως PAT_ABSOLUTE_MAX_TTL_DAYS (180 ημέρες)

Και οι δύο τύποι είναι Bearer διακριτικά που μεταφέρονται στην κεφαλίδα Authorization σε κάθε αίτημα.

---

Απόκτηση Διακριτικού Συνεδρίας

Βήμα 1 — POST /api/v1/auth/login

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

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

Επιτυχημένη απάντηση (200):

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

Το πεδίο expires_in είναι η εξουσιοδοτημένη διάρκεια ζωής του διακριτικού σε δευτερόλεπτα. Αντιμετωπίστε αυτήν την τιμή ως την πηγή αλήθειας για τη λογική λήξης του διακριτικού σας — μην βασίζεστε σε καμία σταθερά με καθορισμένη τιμή.

Απάντηση σφάλματος: Όλες οι αποτυχίες ελέγχου ταυτότητας επιστρέφουν ένα ενιαίο σφάλμα AUTH_FAILED ανεξάρτητα από την πραγματική αιτία της αποτυχίας (λάθος κωδικός πρόσβασης, άγνωστο email, κλειδωμένος λογαριασμός). Αυτό είναι σκόπιμο — το VaultPAM δεν αποκαλύπτει ποιο τμήμα του διακριτικού ήταν μη έγκυρο.

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

Βήμα 2 — Προσδιορισμός του ενεργού οργανισμού

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

Απάντηση:

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

Χρησιμοποιήστε το active_org_id ως τιμή για την κεφαλίδα X-Active-Org-Id στα επόμενα αιτήματα.

---

Πραγματοποίηση Αυθεντικευμένων Αιτημάτων

Συμπεριλάβετε και τις δύο κεφαλίδες σε κάθε κλήση API:

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

Παράδειγμα:

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

---

Λήξη Διακριτικού Συνεδρίας

Τα διακριτικά συνεδρίας δεν είναι ανανεώσιμα. Δεν υπάρχει τελικό σημείο ανανέωσης — ένα αίτημα στο /api/v1/auth/refresh επιστρέφει 404. Όταν λήξει το διακριτικό σας, πραγματοποιήστε ξανά έλεγχο ταυτότητας καλώντας το POST /api/v1/auth/login.

Ο πελάτης σας θα πρέπει:

1. Να αποθηκεύσει την τιμή expires_in από την απάντηση σύνδεσης.
2. Να πραγματοποιήσει ξανά έλεγχο ταυτότητας πριν λήξει το διακριτικό (συνιστώμενο: αφαιρέστε 60 δευτερόλεπτα ως ενδιάμεσο χώρο).
3. Να δοκιμάσει ξανά το αρχικό αίτημα με το νέο διακριτικό.

Χωρίς αυτόματη ανανέωση

Το VaultPAM δεν υποστηρίζει διακριτικά ανανέωσης τύπου OAuth. Απαιτείται εκ νέου σύνδεση κατά τη λήξη.

---

Αποσύνδεση

Ακυρώστε ένα διακριτικό συνεδρίας αμέσως:

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

Απάντηση: 204 No Content

---

Personal Access Tokens (PATs)

Τα PAT είναι διακριτικά μακράς διάρκειας για αυτοματοποίηση και ολοκληρώσεις. Φέρουν το πρόθεμα pat_AIC_.

Δημιουργία ενός 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
}

Η τιμή του διακριτικού επιστρέφεται μόνο μία φορά κατά τη δημιουργία και δεν μπορεί να ανακτηθεί ξανά.

Ανάκληση ενός PAT

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

Απάντηση: 204 No Content

Επιβολή Εύρους

Η επιβολή εύρους δημιουργείται κατά οικογένεια τελικών σημείων. Κλήσεις με ένα PAT με εύρος σε ένα τελικό σημείο εκτός των δηλωμένων εύρων του διακριτικού μπορεί να επιστρέψουν 403. Χρησιμοποιήστε το ελάχιστο εύρος που απαιτείται για την περίπτωση χρήσης σας.

---

Αποθήκευση Διακριτικού

Αποθηκεύστε τα διακριτικά με ασφάλεια

Τα διακριτικά παρέχουν πλήρη πρόσβαση στο API εντός των χορηγημένων εύρων τους. Τα λάθη χειρισμού διακριτικών μπορούν να οδηγήσουν σε μη εξουσιοδοτημένη πρόσβαση.

Απαιτούμενες πρακτικές:

1. Ποτέ μην δεσμεύσετε διακριτικά στον έλεγχο πηγής. Ακόμη και σε ιδιωτικά αποθετήρια, τα διακριτικά σε δεσμευμένο κώδικα είναι ένας διαρκής κίνδυνος ασφάλειας. Χρησιμοποιήστε μεταβλητές περιβάλλοντος ή διαχειριστή μυστικών.
2. Χρησιμοποιήστε ένα keychain του λειτουργικού συστήματος ή διαχειριστή μυστικών στην παραγωγή. Παραδείγματα: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
3. Ποτέ μην καταγράφετε τιμές διακριτικών. Εξετάστε τη διαμόρφωση καταγραφής σας για να βεβαιωθείτε ότι τα διακριτικά στις κεφαλίδες ή τα σώματα αιτημάτων κρύβονται.
4. Ανακαλέστε διακριτικά όταν δεν είναι πλέον απαραίτητα. Χρησιμοποιήστε DELETE /api/v1/auth/api-tokens/{token_id} για PAT. Τα διακριτικά συνεδρίας λήγουν αυτόματα αλλά θα πρέπει να αντιμετωπίζονται ως ανακλήσιμα.
5. Ρυθμίστε εργαλεία ανίχνευσης μυστικών για να ανιχνεύσετε το πρόθεμα pat_AIC_. Αυτό το πρόθεμα υπάρχει σε όλα τα VaultPAM PAT και επιτρέπει σε εργαλεία όπως το GitHub Advanced Security να σημαιοφορήσουν τυχαία έκθεση.

---

Επόμενα βήματα

• curl Quickstart — ολοκληρωμένο παράδειγμα χρησιμοποιώντας τη γραμμή εντολών
• Python Quickstart — παράδειγμα ολοκλήρωσης Python
• TypeScript Quickstart — παράδειγμα ολοκλήρωσης TypeScript/Node.js
• Rate Limits — κατανόηση των κεφαλίδων x-ratelimit-* και της συμπεριφοράς επανάληψης