Je servers en pipelines verbinden met Uniqkey Secrets Manager via de uniqkey CLI

Uniqkey Secrets Manager slaat de secrets op die je systemen gebruiken: databasewachtwoorden, API-tokens, verbindingsreeksen en certificaten. Beheerders beheren deze in het Admin Portal. Servers, scripts en CI/CD-pipelines lezen en schrijven ze met het opdrachtregelprogramma (CLI) uniqkey en een API-sleutel. In dit artikel wordt uitgelegd hoe je een API-sleutel maakt, de CLI installeert en configureert, deze veilig gebruikt en de problemen oplost waar klanten het vaakst tegenaan lopen.

Een aantal termen die in dit artikel worden gebruikt:

• Een API-sleutel is het legitimatiemiddel dat een machine gebruikt. Deze bestaat uit twee delen: een Access Key ID (begint met UKEY) en een Secret Key (begint met uksm_), die werkt als het wachtwoord van de sleutel.
• Een secret is een waarde die je opslaat in Secrets Manager.
• Een pad benoemt één secret, zoals een bestand: /production/database/password. Een prefix is het begin van een pad, zoals /production, en omvat alles daaronder.

Wie dit kan gebruiken

• Secrets Manager moet actief zijn voor je organisatie. Als je Secrets Manager niet ziet in het menu van het Admin Portal, neem je contact op met Uniqkey Support.
• API-sleutels worden gemaakt door een beheerder van de organisatie. Supportaccounts en gewone medewerkers kunnen Secrets Manager niet openen.
• Een API-sleutel behoort toe aan de organisatie, niet aan de beheerder die deze heeft gemaakt. De sleutel blijft werken als die beheerder vertrekt. Vervang daarom de sleutels wanneer een beheerder die ze beheerde vertrekt.
• De CLI werkt op Windows, macOS en Linux (x64 en ARM). Het is één programma waarvoor niets anders hoeft te worden geïnstalleerd.
• De machine heeft uitgaande HTTPS (poort 443) nodig naar secrets-manager.production.uniqkey.eu en naar static.uniqkey.eu voor installatie en updates.

Houd je API-sleutels en secrets veilig

• Secrets worden versleuteld en ontsleuteld op de machine waarop de CLI draait. Uniqkey slaat alleen versleutelde waarden op en kan deze niet lezen. Uniqkey kan het pad van een secret zien, wanneer dit is gewijzigd en welke API-sleutel er toegang toe had. Zet daarom nooit geheime informatie in een pad of in de naam van een API-sleutel.
• Iedereen die een API-sleutel bezit, kan alles ontsleutelen wat de sleutel mag lezen. Padbeperkingen zijn een machtiging die Uniqkey bij elk verzoek controleert, geen afzonderlijke versleuteling: er is één versleutelingssleutel per organisatie. Geef elke sleutel het kleinst mogelijke bereik en alleen de paden die nodig zijn, en stel een vervaldatum in.
• Plak nooit een Secret Key, een legitimatiebestand, een .env-bestand of een ongeschoond logboek in een ticket, e-mail of chat. Uniqkey Support heeft deze nooit nodig.
• Als een API-sleutel mogelijk is uitgelekt: schakel deze onmiddellijk uit of verwijder deze op de pagina API keys, wijzig elke secret die de sleutel kon lezen bij de bron (de database of de externe service), sla de nieuwe waarden op en controleer het auditlog om te zien wat de sleutel heeft gedaan. Eerdere waarden blijven in de versiegeschiedenis van elke secret staan.

Stap 1: Een API-sleutel maken

1. Meld je als beheerder aan bij het Admin Portal.
2. Open Secrets Manager in het menu aan de linkerkant. Als het portal je vraagt dit op je telefoon te bevestigen, keur je het verzoek binnen één minuut goed in de Uniqkey-app. Voor Secrets Manager moet Trusted Portal voor je organisatie zijn toegestaan.
3. Open API keys in het menu aan de linkerkant en klik op Create API Key.
4. Vul de velden in:
   • Name: wat de sleutel zal gebruiken, bijvoorbeeld ci-deploy-production. De naam wordt in het auditlog weergegeven voor alles wat de sleutel doet.
   • Scope: Read only, Read & write of Admin (full access). De meeste pipelines hebben Read only nodig.
   • Path Restrictions: de prefixes die de sleutel mag gebruiken, bijvoorbeeld /production. Laat dit alleen leeg als de sleutel echt elke secret nodig heeft.
   • Expiry date (optional): aanbevolen. De vroegste datum die je kunt kiezen is morgen. De sleutel werkt tot het einde van die dag in de tijdzone van je browser.
5. Klik op Create. In het dialoogvenster Copy your API key now worden de Access Key ID en de Secret Key weergegeven.
6. Kopieer beide naar de locatie waar de machine de legitimatiegegevens bewaart. De Secret Key wordt maar één keer weergegeven. Vink I have stored this API key in a safe place aan om het dialoogvenster te sluiten. Als de Secret Key verloren gaat, verwijder je de API-sleutel en maak je een nieuwe.

API-sleutels later beheren:

• Op de pagina API keys staan alle sleutels met hun scope, paden, status, vervaldatum (Expires) en Last used. Hier kun je een sleutel uitschakelen, opnieuw inschakelen of verwijderen. Beide acties worden onmiddellijk uitgevoerd.
• Een organisatie kan maximaal 50 API-sleutels hebben.
• Leesacties, wijzigingen en afgewezen verzoeken worden vastgelegd in het auditlog van de organisatie onder het onderwerp Secrets Manager, met de naam van de API-sleutel. Het lezen van een volledige prefix met export of run wordt als één item vastgelegd met daarin de paden.
• Een API-sleutel roteren: maak een nieuwe sleutel, werk de machine bij, controleer of Last used van de oude sleutel niet meer verandert en verwijder daarna de oude sleutel.

Stap 2: De CLI installeren

Windows (PowerShell):

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

macOS en Linux:

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

Het installatieprogramma downloadt de juiste versie voor de machine en controleert deze vóór de installatie aan de hand van een gepubliceerde checksum. In Windows is het programma ondertekend door Uniqkey en voegt het installatieprogramma het toe aan je PATH: open daarna een nieuwe terminal. In macOS en Linux wordt het geïnstalleerd in /usr/local/bin, of in ~/.local/bin als die map niet schrijfbaar is. Als het installatieprogramma meldt dat je die map aan je PATH moet toevoegen, doe dit dan.

Controleer de installatie:

uniqkey version

Een specifieke versie installeren, wat wordt aanbevolen in CI zodat builds niet vanzelf veranderen:

$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

Bijwerken: voer het installatieprogramma opnieuw uit. Verwijderen: verwijder het programma uniqkey en de map .uniqkey uit je gebruikersprofiel; hiermee worden ook opgeslagen legitimatiegegevens verwijderd. Als je beveiligingsbeleid het uitvoeren van een gedownload installatie­script niet toestaat, neem je contact op met Uniqkey Support voor een directe download en de checksum daarvan.

Stap 3: De CLI configureren

Voer op een werkstation of server het volgende uit:

uniqkey configure

Er wordt naar drie dingen gevraagd. Druk bij API url op Enter om het productieadres te behouden en plak daarna de Access key id en de Secret key. De Secret Key is tijdens het plakken zichtbaar op het scherm. Doe dit daarom op een plek waar niemand je scherm kan zien. De antwoorden worden opgeslagen in een legitimatiebestand:

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

Het bestand bevat de Secret Key als tekst zonder versleuteling. Bewaar dit in het gebruikersprofiel van het account dat de CLI uitvoert, kopieer het niet tussen machines en voeg het nooit toe aan broncodebeheer of een containerimage. Bewaar productie-API-sleutels alleen op machines die ze nodig hebben, niet op laptops van ontwikkelaars.

Het bestand kan meerdere profielen bevatten. Kies een profiel met --profile (of -p), dat vóór de opdracht wordt geplaatst, bijvoorbeeld uniqkey -p build-server secret list, of stel de omgevingsvariabele UNIQKEY_PROFILE in:

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

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

Maak in CI/CD-pipelines geen legitimatiebestand. Stel deze omgevingsvariabelen in vanuit de secretopslag van de pipeline; ze hebben voorrang op het bestand:

De CLI gebruikt standaard het productieadres. Stel alleen een ander adres in als Uniqkey dit aan je heeft gegeven. Doe dit bij de prompt API url van uniqkey configure of in de omgevingsvariabele UNIQKEY_API_URL.

Goed om te weten over het legitimatiebestand:

• Namen van sleutels zijn niet hoofdlettergevoelig, maar een naam die de CLI niet kent is een fout. Een typefout wordt dus nooit stilzwijgend genegeerd. Maak het profiel opnieuw met uniqkey configure als je zo'n fout krijgt.
• Als je het bestand in Windows PowerShell 5 maakt met >, kan de CLI het niet lezen. Gebruik in plaats daarvan uniqkey configure.
• uniqkey configure wijzigt alleen het profiel dat het schrijft en laat de rest van het bestand ongewijzigd.

Stap 4: Controleren of het werkt

uniqkey secret list

Als de API-sleutel secrets kan lezen, zie je de bijbehorende paden. Als er niets wordt weergegeven, heeft de sleutel nog geen secrets binnen de bijbehorende paden. Raadpleeg bij een foutmelding 'Problemen oplossen'.

De CLI gebruiken

Een secret lezen:

uniqkey secret get /production/database/password

Een secret schrijven. Pipe de waarde in plaats van deze als argument te typen, zodat deze niet in de shellgeschiedenis terechtkomt:

# Windows (PowerShell): vraagt om de waarde, die niet in de geschiedenis wordt opgeslagen
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

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

Opmerkingen:

• Eén regeleinde aan het einde van een gepipete waarde wordt verwijderd. Daardoor werken echo en PowerShell-pipes zonder speciale opties.
• Bij overschrijven blijven de beschrijving, tags en het type behouden, tenzij je nieuwe opgeeft. Als iemand de secret heeft gewijzigd terwijl de opdracht werd uitgevoerd, stopt de opdracht met afsluitcode 6 in plaats van de wijziging te overschrijven. Voer de opdracht opnieuw uit.
• Opties zoals --profile en --output json komen vóór de opdracht (uniqkey --output json secret get /p); opties van een opdracht, zoals --overwrite, komen na het pad.
• Paden zijn hoofdlettergevoelig.

Secrets aan een programma geven

uniqkey run is de veiligste manier om secrets aan een programma door te geven: ze gaan rechtstreeks naar de omgeving en worden nooit afgedrukt of naar schijf geschreven.

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

• Elke secret wordt een omgevingsvariabele met de naam van het deel van het pad onder de prefix, in hoofdletters, waarbij andere tekens worden vervangen door _: onder /production/api wordt /production/api/stripe-key STRIPE_KEY.
• Als twee secrets dezelfde naam zouden krijgen, of als een naam de manier verandert waarop programma's starten (zoals PATH), stopt de opdracht voordat er iets wordt uitgevoerd. Hernoem de secret.
• De variabelen UNIQKEY_ACCESS_KEY_ID en UNIQKEY_SECRET_KEY worden niet aan het programma doorgegeven.
• run sluit af met de afsluitcode van het uitgevoerde programma.

Secrets in een shell of .env-bestand laden

uniqkey export drukt de secrets af als instructies voor een shell. De standaardindeling is PowerShell in Windows en een POSIX-shell in macOS en Linux.

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

# macOS en Linux (bash, zsh, sh); voeg in Git Bash op Windows --format posix toe
eval "$(uniqkey export /production/api)"

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

• export drukt secrets af als tekst zonder versleuteling. Gebruik dit alleen wanneer de uitvoer onmiddellijk wordt gebruikt en geef de voorkeur aan run.
• Een .env-bestand bevat elke secret onder de prefix als tekst zonder versleuteling. Houd het buiten broncodebeheer (voeg het toe aan .gitignore), zorg dat alleen jij het kunt lezen en verwijder het wanneer je klaar bent. Maak het in Windows vanuit cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), omdat Windows PowerShell 5 uitvoer met > opslaat in een indeling die Docker Compose niet kan lezen.
• De indeling .env is bedoeld voor hulpprogramma's die .env-bestanden lezen, zoals Docker Compose. Het is geen shellscript: laad het nooit met source of . .env, omdat een waarde met aanhalingstekens, $ of backticks dan opdrachten kan uitvoeren.
• In PowerShell komen tekens met accenten, emoji's en regeleinden ongewijzigd aan, ook op vergrendelde machines. Een lege secret verwijdert de variabele in plaats van deze leeg in te stellen.
• Als de prefix geen secrets vindt, geeft de CLI een waarschuwing en wordt er niets uitgevoerd. In PowerShell geeft de stap iex dan een fout over een lege tekenreeks. Controleer de prefix en de paden van de API-sleutel.

Gebruiken in CI/CD

1. Sla de Access Key ID en Secret Key op als geheime variabelen in de pipeline en koppel ze aan UNIQKEY_ACCESS_KEY_ID en UNIQKEY_SECRET_KEY.
2. Installeer een vastgezette versie van de CLI met de opdrachten in stap 2.
3. Voer je stap uit via uniqkey run /production/api -- <your deploy command>.

De pipeline maskeert de twee API-sleutelvariabelen in de logboeken, maar weet niets van waarden die de CLI tijdens runtime ophaalt. Geef de voorkeur aan run, waarmee ze uit het logboek blijven. Als je waarden afdrukt of export gebruikt, maskeer je deze expliciet in je CI-systeem en gebruik je geen set -x, env of foutopsporingslogboeken rond die stappen. Voer uniqkey configure niet uit in een pipeline.

Kubernetes

Voor Kubernetes bevat de CLI een kleine proxy, uniqkey serve, waar de External Secrets Operator verbinding mee maakt. Deze ontsleutelt binnen je cluster, zodat toepassingen een gewone Kubernetes-secret ontvangen. Gebruik een API-sleutel met Read only, beperkt tot de prefixes die het cluster nodig heeft, voer de proxy uit met een TLS-certificaat en gebruik een NetworkPolicy zodat alleen de External Secrets Operator toegang heeft. De resulterende Kubernetes-secrets worden zonder versleuteling in je cluster opgeslagen, tenzij je versleuteling at rest inschakelt. Neem contact op met Uniqkey Support voor de deploymentmanifests.

Afsluitcodes

Elke opdracht sluit af met een code die een script kan controleren. Foutmeldingen gaan naar de foutuitvoer en beginnen met uniqkey:; waarden gaan naar de normale uitvoer. uniqkey run sluit af met de code van het uitgevoerde programma.

Limieten

Elke CLI-opdracht ontgrendelt eerst de versleuteling van de organisatie. Dit telt mee voor de limiet per IP-adres. Alle machines die Uniqkey via hetzelfde openbare IP-adres bereiken (bijvoorbeeld achter één NAT of proxy) delen deze limiet. Een pipeline die vele keren per minuut uniqkey secret get uitvoert, kan dus worden beperkt, ook als elke API-sleutel ver onder de eigen limiet blijft. Lees een volledige prefix met één run of export in plaats van met veel aanroepen van secret get.

Problemen oplossen

Wanneer je contact opneemt met Support, vermeld je de naam van je organisatie, de uitvoer van uniqkey version, het besturingssysteem, de exacte opdracht waarbij je eventuele secretwaarden hebt verwijderd, de volledige foutmelding, de afsluitcode (echo $? in bash, $LASTEXITCODE in PowerShell), de naam van de API-sleutel (nooit de Secret Key) en het tijdstip waarop dit gebeurde.