Łączenie serwerów i potoków z Uniqkey Secrets Manager za pomocą uniqkey CLI

Uniqkey Secrets Manager przechowuje dane uwierzytelniające używane przez systemy: hasła do baz danych, tokeny API, parametry połączeń i certyfikaty. Administratorzy zarządzają nimi w portalu administracyjnym. Serwery, skrypty i potoki CI/CD odczytują je i zapisują za pomocą narzędzia wiersza poleceń uniqkey (CLI) oraz klucza API. W tym artykule wyjaśniono, jak utworzyć klucz API, zainstalować i skonfigurować CLI, bezpiecznie go używać oraz rozwiązywać najczęstsze problemy.

Oto kilka terminów używanych w całym artykule:

• Klucz API to dane uwierzytelniające używane przez komputer. Składa się z dwóch części: identyfikatora klucza dostępu (zaczyna się od UKEY) oraz klucza tajnego (zaczyna się od uksm_), który działa jak hasło do klucza.
• Secret to wartość przechowywana w Secrets Manager.
• Ścieżka wskazuje jeden sekret, podobnie jak nazwa pliku: /production/database/password. Prefiks to początek ścieżki, na przykład /production, obejmujący wszystkie znajdujące się pod nim elementy.

Kto może korzystać z tej funkcji

• Secrets Manager musi być aktywny dla Twojej organizacji. Jeśli w menu portalu administracyjnego nie widzisz pozycji Secrets Manager, skontaktuj się z pomocą techniczną Uniqkey.
• Klucze API tworzy administrator organizacji. Konta pomocy technicznej i zwykli pracownicy nie mogą otwierać Secrets Manager.
• Klucz API należy do organizacji, a nie do administratora, który go utworzył. Będzie działać także po odejściu tego administratora, dlatego gdy administrator zajmujący się kluczami odchodzi, należy je zastąpić.
• CLI działa w systemach Windows, macOS i Linux (x64 oraz ARM). Jest to pojedynczy program, który nie wymaga instalowania dodatkowych elementów.
• Komputer musi mieć możliwość nawiązywania wychodzących połączeń HTTPS (port 443) z adresem secrets-manager.production.uniqkey.eu, a podczas instalowania i aktualizowania także z adresem static.uniqkey.eu.

Chroń klucze API i sekrety

• Sekrety są szyfrowane i odszyfrowywane na komputerze, na którym działa CLI. Uniqkey przechowuje wyłącznie zaszyfrowane wartości i nie może ich odczytać. Uniqkey może zobaczyć ścieżkę sekretu, czas jego zmiany oraz klucz API, który uzyskał do niego dostęp, dlatego nigdy nie umieszczaj informacji poufnych w ścieżce ani w nazwie klucza API.
• Każdy, kto posiada klucz API, może odszyfrować wszystko, co ten klucz może odczytać. Ograniczenia ścieżek to uprawnienia sprawdzane przez Uniqkey przy każdym żądaniu, a nie osobne szyfrowanie: dla każdej organizacji istnieje jeden klucz szyfrowania. Nadaj każdemu kluczowi najmniejszy niezbędny zakres i ograniczenia ścieżek oraz ustaw datę wygaśnięcia.
• Nigdy nie wklejaj klucza tajnego, pliku z danymi uwierzytelniającymi, pliku .env ani niezanonimizowanego dziennika do zgłoszenia, wiadomości e-mail lub czatu. Pomoc techniczna Uniqkey nigdy ich nie potrzebuje.
• Jeśli klucz API mógł wyciec: natychmiast wyłącz go lub usuń na stronie Klucze API, zmień w źródle każdy sekret, który ten klucz mógł odczytać (w bazie danych lub usłudze zewnętrznej), zapisz nowe wartości i sprawdź dziennik audytu pod kątem działań wykonanych przez klucz. Wcześniejsze wartości pozostają w historii wersji każdego sekretu.

Krok 1: Utwórz klucz API

1. Zaloguj się do portalu administracyjnego jako administrator.
2. Otwórz pozycję Secrets Manager w menu po lewej stronie. Jeśli portal poprosi o potwierdzenie na telefonie, zatwierdź żądanie w aplikacji Uniqkey w ciągu minuty. Secrets Manager wymaga zezwolenia na Trusted Portal dla organizacji.
3. Otwórz pozycję Klucze API w menu po lewej stronie i kliknij Utwórz klucz API.
4. Wypełnij pola:
   • Nazwa: określ, co będzie używać klucza, na przykład ci-deploy-production. Nazwa jest wyświetlana w dzienniku audytu przy wszystkich działaniach wykonanych przez klucz.
   • Zakres: Tylko odczyt, Odczyt i zapis lub Administrator (pełny dostęp). Większość potoków wymaga zakresu Tylko odczyt.
   • Ograniczenia ścieżek: prefiksy, których klucz może używać, na przykład /production. Pozostaw to pole puste tylko wtedy, gdy klucz rzeczywiście potrzebuje dostępu do każdego sekretu.
   • Data wygaśnięcia (opcjonalnie): zalecane. Najwcześniejsza możliwa data to jutro. Klucz działa do końca tego dnia w strefie czasowej przeglądarki.
5. Kliknij Utwórz. W oknie dialogowym Skopiuj teraz klucz API zostaną wyświetlone identyfikator klucza dostępu i klucz tajny.
6. Skopiuj oba elementy do miejsca, w którym komputer przechowuje dane uwierzytelniające. Klucz tajny jest wyświetlany tylko raz. Zaznacz opcję Przechowuję ten klucz API w bezpiecznym miejscu, aby zamknąć okno. Jeśli klucz tajny zostanie utracony, usuń klucz API i utwórz nowy.

Późniejsze zarządzanie kluczami API:

• Na stronie Klucze API znajduje się lista wszystkich kluczy wraz z ich zakresem, ścieżkami, statusem, datą wygaśnięcia (Wygasa) i informacją Ostatnio użyty. Z tego miejsca można wyłączyć, ponownie włączyć lub usunąć klucz. Obie operacje zaczynają obowiązywać natychmiast.
• Organizacja może mieć maksymalnie 50 kluczy API.
• Odczyty, zmiany i odrzucone żądania są zapisywane w dzienniku audytu organizacji w temacie Secrets Manager, wraz z nazwą klucza API. Odczyt całego prefiksu za pomocą polecenia export lub run jest zapisywany jako jeden wpis zawierający listę ścieżek.
• Aby zmienić klucz API, utwórz nowy klucz, zaktualizuj komputer, sprawdź, czy informacja Ostatnio użyty przy starym kluczu przestaje się zmieniać, a następnie usuń stary klucz.

Krok 2: Zainstaluj CLI

Windows (PowerShell):

irm https://static.uniqkey.eu/cli/install.ps1 | iex

macOS i Linux:

curl -fsSL https://static.uniqkey.eu/cli/install.sh | sh

Instalator pobiera odpowiednią wersję dla komputera i przed instalacją sprawdza ją względem opublikowanej sumy kontrolnej. W systemie Windows program jest podpisany przez Uniqkey, a instalator dodaje go do zmiennej PATH: później otwórz nowy terminal. W systemach macOS i Linux program jest instalowany w katalogu /usr/local/bin lub w katalogu ~/.local/bin, gdy pierwszy katalog nie jest zapisywalny. Jeśli instalator poinformuje, że należy dodać ten katalog do PATH, zrób to.

Sprawdź instalację:

uniqkey version

Aby zainstalować konkretną wersję, co jest zalecane w CI, aby kompilacje nie zmieniały się samoczynnie:

$env:UNIQKEY_VERSION = '1.0.1'; irm https://static.uniqkey.eu/cli/install.ps1 | iex

curl -fsSL https://static.uniqkey.eu/cli/install.sh | UNIQKEY_VERSION=1.0.1 sh

Aktualizowanie: uruchom instalator ponownie. Usuwanie: usuń program uniqkey oraz folder .uniqkey z profilu użytkownika; spowoduje to również usunięcie zapisanych danych uwierzytelniających. Jeśli zasady bezpieczeństwa nie zezwalają na uruchamianie pobranego skryptu instalacyjnego, skontaktuj się z pomocą techniczną Uniqkey w sprawie bezpośredniego pobrania i sumy kontrolnej.

Krok 3: Skonfiguruj CLI

Na stacji roboczej lub serwerze uruchom:

uniqkey configure

Polecenie poprosi o trzy rzeczy. Naciśnij Enter przy polu Adres API, aby zachować produkcyjny adres, a następnie wklej identyfikator klucza dostępu i klucz tajny. Klucz tajny jest widoczny na ekranie podczas wklejania, dlatego wykonaj tę czynność w miejscu, w którym nikt nie widzi ekranu. Odpowiedzi zostaną zapisane w pliku z danymi uwierzytelniającymi:

• Windows: %USERPROFILE%\.uniqkey\credentials
• macOS i Linux: ~/.uniqkey/credentials

Plik zawiera klucz tajny w postaci jawnego tekstu. Przechowuj go w profilu użytkownika konta uruchamiającego CLI, nie kopiuj między komputerami i nigdy nie dodawaj do systemu kontroli wersji ani obrazu kontenera. Produkcyjne klucze API przechowuj wyłącznie na komputerach, które ich potrzebują, a nie na laptopach deweloperskich.

Plik może zawierać kilka profili. Wybierz profil za pomocą opcji --profile (lub -p) umieszczonej przed poleceniem, na przykład uniqkey -p build-server secret list, albo ustaw zmienną środowiskową UNIQKEY_PROFILE:

[default]
access_key_id = UKEYXXXXXXXXXXXXXXXX
secret_key = uksm_...

[build-server]
access_key_id = UKEYYYYYYYYYYYYYYYYY
secret_key = uksm_...

W potokach CI/CD nie twórz pliku z danymi uwierzytelniającymi. Zamiast tego ustaw te zmienne środowiskowe na podstawie magazynu sekretów potoku; mają one pierwszeństwo przed plikiem:

CLI domyślnie używa adresu produkcyjnego. Tylko jeśli Uniqkey podał Ci inny adres, ustaw go w polu Adres API polecenia uniqkey configure albo w zmiennej środowiskowej UNIQKEY_API_URL.

Warto wiedzieć o pliku z danymi uwierzytelniającymi:

• Nazwy kluczy nie uwzględniają wielkości liter, ale nieznana CLI nazwa powoduje błąd, więc literówka nigdy nie zostanie zignorowana bez ostrzeżenia. Jeśli tak się stanie, utwórz profil ponownie za pomocą uniqkey configure.
• Jeśli utworzysz plik w Windows PowerShell 5 za pomocą >, CLI nie będzie mogło go odczytać. Zamiast tego użyj uniqkey configure.
• uniqkey configure zmienia tylko profil, który zapisuje, i pozostawia resztę pliku bez zmian.

Krok 4: Sprawdź działanie

uniqkey secret list

Jeśli klucz API może odczytywać sekrety, zobaczysz ich ścieżki. Jeśli nic nie zostanie wyświetlone, klucz nie ma jeszcze żadnych sekretów w ramach swoich ścieżek. W razie błędu zobacz sekcję „Rozwiązywanie problemów”.

Korzystanie z CLI

Odczytywanie sekretu:

uniqkey secret get /production/database/password

Zapisywanie sekretu. Przekaż wartość przez potok zamiast wpisywać ją jako argument, aby nie trafiła do historii powłoki:

# Windows (PowerShell): prosi o wartość, która nie trafia do historii
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

# macOS i Linux
openssl rand -base64 32 | uniqkey secret set /production/api/session-key --overwrite

Uwagi:

• Jeden znak końca wiersza na końcu wartości przekazywanej przez potok jest usuwany, dzięki czemu potoki echo i PowerShell działają bez specjalnych opcji.
• Zastąpienie zachowuje opis, tagi i typ, chyba że podasz nowe wartości. Jeśli ktoś zmieni sekret podczas działania polecenia, polecenie zakończy się kodem wyjścia 6 zamiast zastąpić tę zmianę. Uruchom je ponownie.
• Opcje takie jak --profile i --output json umieszcza się przed poleceniem (uniqkey --output json secret get /p); opcje polecenia, takie jak --overwrite, umieszcza się za ścieżką.
• Wielkość liter w ścieżkach ma znaczenie.

Przekazywanie sekretów do programu

uniqkey run to najbezpieczniejszy sposób przekazywania sekretów do programu: trafiają bezpośrednio do jego środowiska i nigdy nie są wyświetlane ani zapisywane na dysku.

uniqkey run /production/api -- <your command>

• Każdy sekret staje się zmienną środowiskową nazwaną na podstawie części ścieżki znajdującej się za prefiksem, zapisaną wielkimi literami, a inne znaki są zamieniane na _: w ramach /production/api ścieżka /production/api/stripe-key staje się STRIPE_KEY.
• Jeśli dwa sekrety otrzymałyby tę samą nazwę lub nazwa zmieniałaby sposób uruchamiania programów (na przykład PATH), polecenie zakończy się przed uruchomieniem czegokolwiek. Zmień nazwę sekretu.
• Zmienne UNIQKEY_ACCESS_KEY_ID i UNIQKEY_SECRET_KEY nie są przekazywane do programu.
• run kończy działanie z kodem wyjścia uruchomionego programu.

Ładowanie sekretów do powłoki lub pliku .env

uniqkey export wyświetla sekrety jako instrukcje dla powłoki. Domyślny format to PowerShell w systemie Windows oraz powłoka POSIX w systemach macOS i Linux.

# Windows (PowerShell)
uniqkey export /production/api | Out-String | iex

# macOS i Linux (bash, zsh, sh); w Git Bash w systemie Windows dodaj --format posix
eval "$(uniqkey export /production/api)"

# Plik .env Docker Compose (macOS i Linux)
(umask 077; uniqkey export /production/api --format dotenv > .env)

• export wyświetla sekrety w postaci jawnego tekstu. Używaj go tylko wtedy, gdy dane wyjściowe są natychmiast wykorzystywane, i preferuj run.
• Plik .env zawiera w postaci jawnego tekstu każdy sekret w ramach prefiksu. Nie przechowuj go w systemie kontroli wersji (dodaj go do .gitignore), ogranicz możliwość jego odczytu do siebie i usuń go po zakończeniu pracy. W systemie Windows utwórz go za pomocą cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), ponieważ Windows PowerShell 5 zapisuje dane wyjściowe > w formacie, którego Docker Compose nie może odczytać.
• Format .env jest przeznaczony dla narzędzi odczytujących pliki .env, takich jak Docker Compose. Nie jest to skrypt powłoki: nigdy nie ładuj go za pomocą source ani . .env, ponieważ wartość zawierająca cudzysłowy, $ lub odwrotne apostrofy może wtedy uruchomić polecenia.
• W PowerShell znaki diakrytyczne, emoji i znaki końca wiersza są przekazywane bez zmian, także na komputerach z ograniczeniami. Pusty sekret usuwa zmienną zamiast ustawiać ją jako pustą.
• Jeśli prefiks nie pasuje do żadnych sekretów, CLI wyświetla ostrzeżenie i nic nie zwraca; w PowerShell krok iex wyświetli wtedy błąd dotyczący pustego ciągu. Sprawdź prefiks i ścieżki klucza API.

Korzystanie z CI/CD

1. Zapisz identyfikator klucza dostępu i klucz tajny jako zmienne sekretów w potoku i przypisz je do zmiennych UNIQKEY_ACCESS_KEY_ID oraz UNIQKEY_SECRET_KEY.
2. Zainstaluj przypiętą wersję CLI za pomocą poleceń z kroku 2.
3. Uruchom krok za pomocą uniqkey run /production/api -- <your deploy command>.

Potok maskuje w dziennikach dwie zmienne klucza API, ale nie zna wartości pobieranych przez CLI w czasie działania. Preferuj run, które nie umieszcza ich w dzienniku. Jeśli wyświetlasz lub używasz polecenia export, jawnie zamaskuj wartości w systemie CI i nie używaj set -x, env ani rejestrowania debugowania w tych krokach. Nie uruchamiaj uniqkey configure w potoku.

Kubernetes

W przypadku Kubernetes CLI zawiera niewielki serwer proxy, uniqkey serve, z którego odczytuje dane operator External Secrets. Odszyfrowuje on dane wewnątrz klastra, dzięki czemu aplikacje otrzymują zwykły sekret Kubernetes. Użyj klucza API Tylko odczyt, ograniczonego do prefiksów potrzebnych klastrowi, uruchom proxy z certyfikatem TLS i użyj NetworkPolicy, aby tylko operator External Secrets mógł się z nim łączyć. Wynikowe sekrety Kubernetes są przechowywane w klastrze w postaci jawnego tekstu, chyba że włączysz szyfrowanie danych w spoczynku. Skontaktuj się z pomocą techniczną Uniqkey w sprawie manifestów wdrożenia.

Kody wyjścia

Każde polecenie kończy działanie kodem, który może sprawdzić skrypt. Komunikaty o błędach trafiają do standardowego wyjścia błędów i zaczynają się od uniqkey:; wartości trafiają do standardowego wyjścia. uniqkey run kończy działanie kodem programu, który uruchomiło.

Limity

Każde polecenie CLI najpierw odblokowuje szyfrowanie organizacji, co jest uwzględniane w limicie na adres IP. Wszystkie komputery łączące się z Uniqkey za pośrednictwem tego samego publicznego adresu IP (na przykład za jednym NAT-em lub serwerem proxy) współdzielą ten limit. W związku z tym potok uruchamiający uniqkey secret get wiele razy na minutę może zostać objęty ograniczeniem, nawet jeśli każdy klucz API jest znacznie poniżej własnego limitu. Odczytaj cały prefiks za pomocą jednego polecenia run lub export zamiast wykonywać wiele wywołań secret get.

Rozwiązywanie problemów

Kontaktując się z pomocą techniczną, podaj nazwę organizacji, wynik polecenia uniqkey version, system operacyjny, dokładne polecenie bez żadnej wartości sekretu, pełny komunikat o błędzie, kod wyjścia (echo $? w bashu, $LASTEXITCODE w PowerShell), nazwę klucza API (nigdy klucz tajny) oraz godzinę wystąpienia problemu.