Bulk uitrol Yubico Fido2 beveiligingssleutel

Pascal
22 jun
6 minuten om te lezen

Bijgewerkt op: 25 jun

Introductie

In deze blog gaan we dieper in op bulk-enrolment van Yubico Security Keys i.c.m. Microsoft Entra ID (voorheen Azure AD). Waar Microsoft standaard uitgaat van self-service registratie door eindgebruikers, komt bij grootschalige uitrol al snel de vraag op: hoe kunnen we deze FIDO2-keys centraal, efficiënt en betrouwbaar inschrijven voor een grote gebruikersgroep?

Zowel Jan Bakker als YubicoLabs hebben eerder oplossingen gedeeld waarbij gebruik wordt gemaakt van Python-scripts om dit proces te automatiseren. Deze aanpak biedt in theorie een werkbaar pad voor bulk-registratie van security keys, maar in de praktijk blijkt de implementatie niet altijd even rechtlijnig, mede doordat er nauw gekeken moet worden welke versie van Python gebruikt moet worden.

Zelf liep ik tegen meerdere uitdagingen aan om deze oplossing werkend te krijgen. Gelukkig heb ik hierbij hulp gehad van Yubico zelf, want er zitten wel degelijk wat haken en ogen aan de praktische uitvoering o.a. een nieuw Python script die gebruikt kan worden. Daarom neem ik jullie graag stapsgewijs mee in hoe ik het werkt heb gekregen.

Ter informatie: Momenteel is er nog geen out-of-the-box oplossing en wordt deze methode van Bulk-Enrollment gezien als Proof-of-Concept.

Voorwaardes

Voor deze oplossing zijn de volgende componenten van belang (let op, ook de specifieke versies).

Tip: Heb je momenteel al Python geïnstalleerd dan zou mijn advies zijn om deze volledig te verwijderen of in ieder geval te beginnen met een schone installatie.

De onderstaande componenten zijn essentieel voor deze Bulk-Enrollment PoC:

Python 3.10 for Windows (link)
GIT for Windows (link)
Python scripts (YubicoLabs Github)
Entra Registered App (ClientID + Secret)
Voldoende rechten, zowel lokaal (run e.g. python) als op Entra ID
YubiKeys (Security Keys or YubiKey by Yubico)
Entra ID Security Group
User CSV file
Config JSON file
Requirement text file

Proces Flow

Voor de bulk enrollment wordt er gebruik gemaakt van twee Python scripts. Op de github pagina van Saint-ScobberLotcher is het proces van de twee scripts duidelijk uitgelegd, hieronder het overzicht:

Process Flow Bulk-Enrollment FIDO2 Python Scripts

Script 1Het eerste script step1GetFIDO2Challenges.py zal worden gebruikt om:

Een lijst van gebruikers op te halen die in aanmerking komen voor de registratie van FIDO2-gegevens. Dit wordt momenteel beheerd door lidmaatschap van een groep die is ingesteld in het configs.json bestand.
Voor elk van de leden van de groep zal het script de Graph API aanroepen voor /users/{userPrincipalName | id}/authentication/fido2Methods/creationOptions. Dit eindpunt retourneert de parameters voor het aanmaken van FIDO2-gegevens. Deze gegevens zullen later worden gebruikt om een gegeven op een YubiKey aan te maken.
Het script schrijft de relevante details naar een csv-bestand.

Script 2Het tweede script step2CreateAndActivateCredential.py zal worden gebruikt om:

Het csv-bestand één voor één te verwerken en:
- De csv te gebruiken om de FIDO2-gegevens aanmaakparameters te bouwen om een gegeven op een YubiKey aan te maken.
- Het antwoord van de YubiKey op te halen en de Graph API aan te roepen voor: /users/{userPrincipalName | id}/authentication/fido2Methods. Dit eindpunt zal de FIDO2-gegevens toewijzen en activeren op het gebruikersprofiel in Entra ID.
Het script schrijft ook een rij naar een csv-bestand met de userPrincipalName, entra object id voor de registratie, serienummer (indien beschikbaar), en ook de PIN als de PIN willekeurig door het script werd gegenereerd.

Setup

Stap 1 Aanmaken van een Entra App Registratie

Registreer een Entra App-registratiea.
1. Ga naar de Entra ID App Registrations sectie.
2. Maak een Standaard App Registratie aan en geef het een logische naam.
3. Noteer de Application (Client) ID die gegenereerd wordt bij de creatie. Dit zal in stap 2 worden gebruikt als client_id.
Configureer API-machtigingena.
1. Navigeer naar API permissions en voeg de volgende toepassingsmachtigingen voor Microsoft Graph toe (zorg ervoor dat je Delegated permissions niet selecteert, maar Application permissions):
  1. UserAuthenticationMethod.ReadWrite.All
  2. GroupMember.Read.All
  3. User.Read (standaard)
2. Verleen admin consent voor deze machtigingen.
Maak een Client Secreta. Navigeer naar Certificates & secrets en voeg een New Client secret toe.
1. Noteer de Value die wordt weergegeven wanneer je het nieuwe geheim maakt. Dit zal worden gebruikt in de configs.json als client_secret. Noteer naast de waarde ook de ClientID en Tenant Name.

Stap 2 Installatie en uitvoeren scripts

Download en installeer Python 3.10 voor Windows (latere versies kunnen fouten veroorzaken) via de volgende link:https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe Kies "Advanced Options/Advanced Install" en zorg ervoor dat Add Python to environment variables is aangevinkt.

Python install advanced options
Tijdens de installatie (laatste pagina) selecteer de optie “disable path length limit.
Python install Disable path length limit
Als je nog geen Git hebt geïnstalleerd, doe dit dan nu. Je kunt het hier downloaden:https://git-scm.com/downloads/win Installeer het op je systeem en zorg ervoor dat de optie Use Git and optional Unix tools from the Command Prompt is geselecteerd. Als je Git al hebt geïnstalleerd, moet je mogelijk opnieuw installeren en deze optie selecteren. Het kiezen van de standaardinstellingen op de overige installatiepagina's is meestal voldoende, tenzij je een specifieke vereiste hebt buiten het gebruik van het bulkregistratiescript.
GIT install path environment
Open a command window (not Powershell) as an administrator and run python to confirm it launches without issues and is the correct version (3.10.11)Zodra de versie is geverifieerd kan er exit() worden ingevuld om Python te sluiten.
Python version check
Maak een virtuele omgeving door het volgende in te typen: python -m venv bulkreg-env Opmerking: Door de bovenstaande opdracht uit te voeren, wordt een omgeving aangemaakt op de locatie waar de opdracht wordt uitgevoerd. Dit zal enkele seconden duren om te voltooien. Zodra het klaar is, typ je het volgende in: bulkreg-env\Scripts\activate.bat Je zou nu een prompt moeten zien die begint met bulkreg-env. Telkens wanneer je het script in de toekomst wilt uitvoeren, moet je eerst die activate.bat opdracht uitvoeren om de virtuele omgeving te activeren.
Python create environment
Voeg het volgende toe aan een nieuw notepad-tekstbestand genaamd requirements.txt in de bulkreg-env map (voer notepad bulkreg-env\requirements.txt uit vanuit de opdrachtregel) en sla het bestand op.Zorg ervoor dat de inhoud van het requirements.txt bestand de benodigde Python-pakketten bevat voor de scriptuitvoering. Het bestand zou ongeveer als volgt kunnen zijn: cryptography==42.0.5
requests==2.31.0
fido2==1.1.1
pywin32; platform_system=="Windows"
Python requirement text file
Navigeer naar de bulkreg-env map en voer dir uit om te bevestigen dat requirements.txt op de juiste locatie staat.
Python environment Bulk
Installeer YubiKey Manager via Git. Let op de “.” aan het einde van de laatste regel, deze is vereist. Run command: git clone https://github.com/Yubico/yubikey-manager.git Open folder: cd yubikey-manager Run command: python -m pip install .
Git and install yubikey-manager
Navigeer terug naar de bulkreg-env map (met cd ..) en voer de opdracht uit: pip install -r requirements.txt
Install Python Yubico Requirements
Installeer het bulkregistratiescript. Dit is noodzakelijk, zelfs als je het eerder hebt geïnstalleerd en gebruikt. git clone https://github.com/YubicoLabs/entraId-register-passkeys-on-behalf-of-users.git Navigeer naar de map bulkRegistration binnen het gekloonde repository: cd entraId-register-passkeys-on-behalf-of-users/bulkRegistration

Open folder git repository
Dit zorgt ervoor dat je het benodigde script op de juiste locatie hebt staan voor verdere configuratie en gebruik.
Voer notepad configs.json uit en pas de velden aan op basis van je vereisten en omgeving. Je hebt de tenant, client_id en client_secret nodig van Entra, die zijn aangemaakt in Stap 1. Een voorbeeld van een ingevuld configs.json bestand wordt hieronder weergegeven:
Example configs.json Entra Authentication
Belangrijk: Vervang de waarden voor tenant, client_id, en client_secret door de gegevens die je in Stap 1 hebt gekregen bij het aanmaken van de app-registratie in Entra.
Na het aanpassen van de configuratie, sla het bestand op.
Voer het script step1GetFIDO2Challenges.py uit.
Dit zal door alle gebruikers in je usersInScopeGroup itereren en deze toevoegen aan het bestand usersToRegister.csv.
step1 Get Users from Entra Security Group Script
Om dit te doen, voer je het volgende commando uit in de opdrachtregel (zorg ervoor dat je virtuele omgeving geactiveerd is): python step1GetFIDO2Challenges.py Na uitvoering van dit script zal het de gebruikers doorlopen die je hebt toegevoegd aan de usersInScopeGroup en hun gegevens opslaan in usersToRegister.csv.
Als alles goed is ingesteld, zou je nu het CSV-bestand moeten kunnen vinden met de gebruikers die in aanmerking komen voor registratie.
Output Users.csv
Verwijder step2CreateAndActivateCredential.py uit de map en sla de onderstaande versie daarvoor in plaats. Dit lost een bug op in het script waarbij het niet in staat is de YubiKey te benaderen door een ontbrekende functie.

.TXT verwijderen zodat het een Python script wordt. Zorg ervoor dat je de beveiligingssleutel (YubiKey) op het apparaat is aangesloten en voer daarna het volgende uit: python step2CreateAndActivateCredential.py Door dit script uit te voeren, zal de YubiKey geconfigureerd en geactiveerd worden voor de opgegeven gebruikers in het bestand usersToRegister.csv.
Zorg ervoor dat je YubiKey correct is aangesloten op je apparaat voordat je het script uitvoert, zodat het proces zonder problemen kan verlopen.
Step 2 Register multiple Yubikeys to User(s)
Dit script zal door je usersToRegister itereren en op basis van je instellingen in configs.json gegevens (credentials).
Volg de onderstaande instructies:
Volg alle prompts die verschijnen tijdens de uitvoering van het script en verander de sleutels wanneer daarom wordt gevraagd.
Verander de beveiligingssleutel (YubiKey) elke keer wanneer een nieuwe gebruiker moet worden geregistreerd of geconfigureerd.
Dit betekent dat je na elke gebruiker de YubiKey moet verwisselen voor een nieuwe gebruiker, zodat elke gebruiker zijn eigen unieke credential krijgt.