Forbind dine servere og pipelines til Uniqkey Secrets Manager med uniqkey CLI

Uniqkey Secrets Manager gemmer de secrets, dine systemer bruger: databaseadgangskoder, API-tokens, forbindelsesstrenge og certifikater. Administratorer administrerer dem i Admin Portal. Servere, scripts og CI/CD-pipelines læser og skriver dem med kommandolinjeværktøjet uniqkey (CLI) og en API-nøgle. Denne artikel forklarer, hvordan du opretter en API-nøgle, installerer og konfigurerer CLI'en, bruger den sikkert og løser de problemer, kunder oftest støder på.

Her er nogle begreber, der bruges gennem artiklen:

• En API-nøgle er den legitimationsoplysning, en maskine bruger. Den består af to dele: et Access Key ID (begynder med UKEY) og en Secret Key (begynder med uksm_), som fungerer som nøglens adgangskode.
• En secret er en værdi, du gemmer i Secrets Manager.
• En sti identificerer én secret, ligesom en fil: /production/database/password. Et præfiks er begyndelsen af en sti, f.eks. /production, og omfatter alt under den.

Hvem kan bruge dette

• Secrets Manager skal være aktiv for din organisation. Hvis du ikke kan se Secrets Manager i menuen i Admin Portal, skal du kontakte Uniqkey-support.
• API-nøgler oprettes af en administrator i organisationen. Supportkonti og almindelige medarbejdere kan ikke åbne Secrets Manager.
• En API-nøgle tilhører organisationen, ikke den administrator, der oprettede den. Den fortsætter med at fungere, hvis administratoren forlader organisationen, så når en administrator, der håndterede nøgler, stopper, skal du erstatte disse nøgler.
• CLI'en kører på Windows, macOS og Linux (x64 og ARM). Det er ét program, som ikke kræver andet at installere.
• Maskinen skal have udgående HTTPS (port 443) til secrets-manager.production.uniqkey.eu og til static.uniqkey.eu ved installation og opdatering.

Beskyt dine API-nøgler og secrets

• Secrets krypteres og dekrypteres på den maskine, der kører CLI'en. Uniqkey gemmer kun krypterede værdier og kan ikke læse dem. Uniqkey kan se en secrets sti, hvornår den blev ændret, og hvilken API-nøgle der fik adgang til den, så skriv aldrig noget hemmeligt i en sti eller i navnet på en API-nøgle.
• Den, der har en API-nøgle, kan dekryptere alt, hvad nøglen har tilladelse til at læse. Stibegrænsninger er en tilladelse, som Uniqkey kontrollerer ved hver forespørgsel, ikke separat kryptering: Der er én krypteringsnøgle pr. organisation. Giv hver nøgle det mindst mulige omfang og de nødvendige stier, og angiv en udløbsdato.
• Indsæt aldrig en Secret Key, en credentials-fil, en .env-fil eller en uredigeret log i en supportsag, e-mail eller chat. Uniqkey-support har aldrig brug for dem.
• Hvis en API-nøgle muligvis er blevet lækket: Deaktivér eller slet den straks på siden API keys, skift alle secrets, som nøglen kunne læse, ved kilden (databasen eller tredjepartstjenesten), gem de nye værdier, og kontrollér auditloggen for at se, hvad nøglen gjorde. Tidligere værdier forbliver i hver secrets versionshistorik.

Trin 1: Opret en API-nøgle

1. Log ind på Admin Portal som administrator.
2. Åbn Secrets Manager i menuen til venstre. Hvis portalen beder dig om at bekræfte på din telefon, skal du godkende anmodningen i Uniqkey-appen inden for ét minut. Secrets Manager kræver, at Trusted Portal er tilladt for din organisation.
3. Åbn API keys i menuen til venstre, og klik på Create API Key.
4. Udfyld felterne:
   • Name: hvad der skal bruge nøglen, f.eks. ci-deploy-production. Navnet vises i auditloggen for alt, hvad nøglen gør.
   • Scope: Read only, Read & write eller Admin (full access). De fleste pipelines har brug for Read only.
   • Path Restrictions: de præfikser, nøglen må bruge, f.eks. /production. Lad det kun være tomt, hvis nøglen virkelig har brug for alle secrets.
   • Expiry date (optional): anbefales. Den tidligste dato, du kan vælge, er i morgen. Nøglen fungerer indtil slutningen af den dag i din browsers tidszone.
5. Klik på Create. Dialogboksen Copy your API key now viser Access Key ID og Secret Key.
6. Kopiér begge til det sted, hvor maskinen gemmer sine legitimationsoplysninger. Secret Key vises kun én gang. Markér I have stored this API key in a safe place for at lukke dialogboksen. Hvis Secret Key mistes, skal du slette API-nøglen og oprette en ny.

Senere administration af API-nøgler:

• Siden API keys viser alle nøgler med deres omfang, stier, status, udløb (Expires) og Last used. Herfra kan en nøgle deaktiveres, aktiveres igen eller slettes. Begge handlinger træder i kraft med det samme.
• En organisation kan højst have 50 API-nøgler.
• Læsninger, ændringer og afviste forespørgsler registreres i organisationens auditlog under emnet Secrets Manager sammen med API-nøglens navn. Læsning af et helt præfiks med export eller run registreres som én post, der viser stierne.
• Sådan roterer du en API-nøgle: Opret en ny nøgle, opdatér maskinen, kontrollér, at den gamle nøgles Last used ikke længere ændres, og slet derefter den gamle nøgle.

Trin 2: Installér CLI'en

Windows (PowerShell):

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

macOS og Linux:

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

Installationsprogrammet downloader den rigtige version til maskinen og kontrollerer den mod en offentliggjort checksum, før den installeres. På Windows er programmet signeret af Uniqkey, og installationsprogrammet føjer det til din PATH: Åbn en ny terminal bagefter. På macOS og Linux installeres det i /usr/local/bin eller i ~/.local/bin, når mappen ikke kan skrives til. Hvis installationsprogrammet beder dig om at føje mappen til din PATH, skal du gøre det.

Kontrollér installationen:

uniqkey version

Sådan installerer du en bestemt version, hvilket anbefales i CI, så builds ikke ændres af sig selv:

$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

Opdatering: Kør installationsprogrammet igen. Fjernelse: Slet programmet uniqkey og mappen .uniqkey i din brugerprofil, hvilket også fjerner gemte legitimationsoplysninger. Hvis din sikkerhedspolitik ikke tillader kørsel af et downloadet installationsscript, skal du kontakte Uniqkey-support for at få en direkte download og dens checksum.

Trin 3: Konfigurér CLI'en

Kør følgende på en arbejdsstation eller server:

uniqkey configure

Den spørger om tre ting. Tryk på Enter ved API url for at beholde produktionsadressen, og indsæt derefter Access key id og Secret key. Secret Key vises på skærmen, mens du indsætter den, så gør dette et sted, hvor ingen kan se din skærm. Svarene gemmes i en credentials-fil:

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

Filen indeholder Secret Key i klartekst. Opbevar den i brugerprofilen for den konto, der kører CLI'en, kopiér den ikke mellem maskiner, og føj den aldrig til kildekontrol eller et container-image. Opbevar kun API-nøgler til produktion på de maskiner, der har brug for dem, ikke på udviklernes bærbare computere.

Filen kan indeholde flere profiler. Vælg en med --profile (eller -p), placeret før kommandoen, f.eks. uniqkey -p build-server secret list, eller angiv miljøvariablen UNIQKEY_PROFILE:

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

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

I CI/CD-pipelines skal du ikke oprette en credentials-fil. Angiv i stedet disse miljøvariabler fra pipelinens secret-lager; de har forrang frem for filen:

CLI'en bruger produktionsadressen som standard. Kun hvis Uniqkey har givet dig en anden adresse, skal du angive den ved prompten API url i uniqkey configure eller i miljøvariablen UNIQKEY_API_URL.

Godt at vide om credentials-filen:

• Nøglenavne skelner ikke mellem store og små bogstaver, men et navn, CLI'en ikke kender, er en fejl, så en slåfejl ignoreres aldrig lydløst. Opret profilen igen med uniqkey configure, hvis du får en sådan fejl.
• Hvis du opretter filen i Windows PowerShell 5 med >, kan CLI'en ikke læse den. Brug i stedet uniqkey configure.
• uniqkey configure ændrer kun den profil, den skriver, og lader resten af filen være, som den var.

Trin 4: Kontrollér, at det virker

uniqkey secret list

Hvis API-nøglen kan læse secrets, kan du se deres stier. Hvis der ikke vises noget, har nøglen endnu ingen secrets inden for sine stier. Hvis du får en fejl, kan du se "Fejlfinding".

Brug af CLI'en

Sådan læser du en secret:

uniqkey secret get /production/database/password

Sådan skriver du en secret. Send værdien gennem pipen i stedet for at skrive den som et argument, så den ikke gemmes i shellens historik:

# Windows (PowerShell): beder om værdien, som ikke gemmes i historikken
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

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

Bemærk:

• Ét linjeskift i slutningen af en pipet værdi fjernes, så echo- og PowerShell-pipes fungerer uden særlige indstillinger.
• Overskrivning bevarer beskrivelsen, tags og typen, medmindre du angiver nye. Hvis nogen ændrede secret'en, mens kommandoen kørte, stopper den med afslutningskode 6 i stedet for at overskrive ændringen. Kør den igen.
• Indstillinger som --profile og --output json skal stå før kommandoen (uniqkey --output json secret get /p); indstillinger for en kommando, såsom --overwrite, skal stå efter stien.
• Stier skelner mellem store og små bogstaver.

Sådan giver du et program secrets

uniqkey run er den sikreste måde at give secrets til et program på: De går direkte ind i programmets miljø og vises eller skrives aldrig til disken.

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

• Hver secret bliver til en miljøvariabel, der er navngivet efter den del af stien, der ligger under præfikset, skrevet med store bogstaver, og hvor andre tegn ændres til _: Under /production/api bliver /production/api/stripe-key til STRIPE_KEY.
• Hvis to secrets ville få samme navn, eller et navn ville være et, der ændrer, hvordan programmer starter (f.eks. PATH), stopper kommandoen, før noget køres. Omdøb secret'en.
• Variablerne UNIQKEY_ACCESS_KEY_ID og UNIQKEY_SECRET_KEY gives ikke videre til programmet.
• run afsluttes med afslutningskoden fra det program, den kørte.

Indlæs secrets i en shell eller .env-fil

uniqkey export viser secrets som sætninger til en shell. Standardformatet er PowerShell på Windows og POSIX-shell på macOS og Linux.

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

# macOS og Linux (bash, zsh, sh); i Git Bash på Windows skal du tilføje --format posix
eval "$(uniqkey export /production/api)"

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

• export viser secrets i klartekst. Brug den kun, hvor outputtet forbruges med det samme, og foretræk run.
• En .env-fil indeholder alle secrets under præfikset i klartekst. Hold den ude af kildekontrol (føj den til .gitignore), sørg for, at kun du kan læse den, og slet den, når du er færdig. På Windows skal du oprette den fra cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), fordi Windows PowerShell 5 skriver >-output i et format, som Docker Compose ikke kan læse.
• .env-formatet er beregnet til værktøjer, der læser .env-filer, f.eks. Docker Compose. Det er ikke et shell-script: Indlæs det aldrig med source eller . .env, fordi en værdi, der indeholder anførselstegn, $ eller backticks, så kan køre kommandoer.
• I PowerShell overføres tegn med accent, emojis og linjeskift uændret, også på låste maskiner. En tom secret fjerner variablen i stedet for at sætte den til tom.
• Hvis præfikset ikke matcher nogen secrets, viser CLI'en en advarsel og viser intet output; i PowerShell viser trinnet iex derefter en fejl om en tom streng. Kontrollér præfikset og API-nøglens stier.

Brug i CI/CD

1. Gem Access Key ID og Secret Key som secret-variabler i pipelinen, og tilknyt dem til UNIQKEY_ACCESS_KEY_ID og UNIQKEY_SECRET_KEY.
2. Installér en fastlåst version af CLI'en med kommandoerne i trin 2.
3. Kør dit trin gennem uniqkey run /production/api -- <your deploy command>.

Pipelinen maskerer de to API-nøglevariabler i sine logs, men den kender ikke de værdier, CLI'en henter under kørsel. Foretræk run, som holder dem ude af loggen. Hvis du viser eller export-værdier, skal du maskere dem eksplicit i dit CI-system og ikke bruge set -x, env eller fejllogning omkring disse trin. Kør ikke uniqkey configure i en pipeline.

Kubernetes

Til Kubernetes indeholder CLI'en en lille proxy, uniqkey serve, som External Secrets Operator læser fra. Den dekrypterer i din klynge, så applikationer modtager en almindelig Kubernetes-secret. Brug en API-nøgle med Read only, begrænset til de præfikser, klyngen har brug for, kør proxyen med et TLS-certifikat, og brug en NetworkPolicy, så kun External Secrets Operator kan nå den. De resulterende Kubernetes-secrets gemmes i din klynge i klartekst, medmindre du aktiverer kryptering i hvile. Kontakt Uniqkey-support for deployment-manifestfilerne.

Afslutningskoder

Hver kommando afsluttes med en kode, som et script kan kontrollere. Fejlmeddelelser sendes til fejloutputtet og begynder med uniqkey:; værdier sendes til det normale output. uniqkey run afsluttes med koden fra det program, den kørte.

Begrænsninger

Hver CLI-kommando låser først organisationens kryptering op, hvilket tæller med i grænsen pr. IP. Alle maskiner, der når Uniqkey via den samme offentlige IP-adresse (f.eks. bag én NAT eller proxy), deler grænsen, så en pipeline, der kører uniqkey secret get mange gange i minuttet, kan blive ratebegrænset, selv om hver API-nøgle ligger langt under sin egen grænse. Læs et helt præfiks med én run eller export i stedet for mange secret get-kald.

Fejlfinding

Når du kontakter support, skal du oplyse din organisations navn, outputtet fra uniqkey version, operativsystemet, den præcise kommando med eventuelle hemmelige værdier fjernet, hele fejlmeddelelsen, afslutningskoden (echo $? i bash, $LASTEXITCODE i PowerShell), API-nøglens navn (aldrig Secret Key) og tidspunktet for fejlen.