Azure PowerShell gebruiken om een service-principal met een certificaat te maken
Wanneer u een app of een script hebt waarvoor toegang tot resources vereist is, kunt u een identiteit voor de app instellen en de app met eigen referenties verifiëren. Deze identiteit staat bekend als een service-principal. Hiermee kunt u het volgende doen:
- Andere machtigingen aan de identiteit van de app toekennen dan uw eigen machtigingen. Deze machtigingen worden meestal beperkt tot de functies die met de app moeten kunnen worden uitgevoerd.
- Een certificaat voor verificatie gebruiken bij het uitvoeren van een onbewaakt script.
Belangrijk
In plaats van een service-principal te maken, kunt u overwegen beheerde identiteiten voor Azure-resources te gebruiken voor de identiteit van uw toepassing. Als uw code wordt uitgevoerd op een service die beheerde identiteiten ondersteunt en toegang krijgt tot resources die ondersteuning bieden voor Microsoft Entra-verificatie, zijn beheerde identiteiten een betere optie voor u. Zie Wat zijn beheerde identiteiten voor Azure-resources? voor meer informatie over beheerde identiteiten voor Azure-resources, inclusief welke service dit momenteel ondersteunen.
In dit artikel leest u hoe een service-principal maakt die zichzelf verifieert met een certificaat. Zie Een Azure-service-principal maken met Azure PowerShell voor het instellen van een service-principal met een wachtwoord.
Voor dit artikel hebt u de meest recente versie van PowerShell nodig.
Notitie
Het wordt aanbevolen de Azure Az PowerShell-module te gebruiken om te communiceren met Azure. Zie Azure PowerShell installeren om aan de slag te gaan. Raadpleeg Azure PowerShell migreren van AzureRM naar Az om te leren hoe u naar de Azure PowerShell-module migreert.
Vereiste machtigingen
Als u dit artikel wilt voltooien, moet u over voldoende machtigingen beschikken in zowel uw Microsoft Entra-id als uw Azure-abonnement. U moet in het bijzonder een app kunnen maken in Microsoft Entra-id en de service-principal toewijzen aan een rol.
De eenvoudigste manier om te controleren of uw account over voldoende machtigingen beschikt, is via het Microsoft Entra-beheercentrum.
De toepassing toewijzen aan een rol
Als u toegang wilt krijgen tot resources in uw abonnement, moet u de toepassing toewijzen aan een rol. Bepaal welke rol de juiste machtigingen biedt voor de toepassing. Zie Ingebouwde Azure-rollen voor meer informatie over de beschikbare rollen.
U kunt het bereik instellen op het niveau van het abonnement, de resourcegroep of de resource. Machtigingen worden overgenomen door lagere niveaus van het bereik. Als u bijvoorbeeld een toepassing toevoegt aan de rol Lezer voor een resourcegroep, betekent dit dat deze zowel de resourcegroep als alle resources in de groep kan lezen. Als u wilt toestaan dat de toepassing acties uitvoert, zoals opnieuw opstarten of starten en stoppen van instanties, selecteert u de rol Inzender.
Service-principal met een zelfondertekend certificaat maken
In het volgende voorbeeld wordt een eenvoudig scenario behandeld. Hierbij wordt New-AzADServicePrincipal gebruikt om een service-principal met een zelfondertekend certificaat te maken, en New-AzRoleAssignment om de rol Lezer aan de service-principal toe te wijzen. De roltoewijzing is afgestemd op uw huidige, geselecteerde Azure-abonnement. Gebruik Set-AzContext als u een ander abonnement wilt selecteren.
Notitie
De cmdlet New-SelfSignedCertificate en de PKI-module worden momenteel niet ondersteund in PowerShell Core.
$cert = New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" `
-Subject "CN=exampleappScriptCert" `
-KeySpec KeyExchange
$keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())
$sp = New-AzADServicePrincipal -DisplayName exampleapp `
-CertValue $keyValue `
-EndDate $cert.NotAfter `
-StartDate $cert.NotBefore
Sleep 20
New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $sp.AppId
In het voorbeeld wordt 20 seconden geslapen, zodat de nieuwe service-principal gedurende 20 seconden kan worden doorgegeven aan de Microsoft Entra-id. Als uw script niet lang genoeg wacht, ziet u een foutbericht met de mededeling: 'Principal {ID} bestaat niet in de map {DIR-ID}'. Als u deze fout wilt oplossen, wacht u even en voert u de opdracht New-AzRoleAssignment opnieuw uit.
U kunt de roltoewijzing beperken tot een specifieke resourcegroep met behulp van de parameter ResourceGroupName. Of tot een specifieke resource met behulp van de parameters ResourceType en ResourceName.
Als u niet over Windows 10 of Windows Server 2016 beschikt, downloadt u de cmdlet New-SelfSignedCertificateEx van PKI Solutions. Pak de inhoud uit en importeer de cmdlet die u nodig hebt.
# Only run if you could not use New-SelfSignedCertificate
Import-Module -Name c:\ExtractedModule\New-SelfSignedCertificateEx.ps1
Vervang de volgende twee regels in het script om het certificaat te genereren.
New-SelfSignedCertificateEx -StoreLocation CurrentUser `
-Subject "CN=exampleapp" `
-KeySpec "Exchange" `
-FriendlyName "exampleapp"
$cert = Get-ChildItem -path Cert:\CurrentUser\my | where {$PSitem.Subject -eq 'CN=exampleapp' }
Certificaat opgeven via een automatisch PowerShell-script
Wanneer u zich aanmeldt als een service-principal, geeft u de tenant-id van de map voor uw AD-app op. Een tenant is een exemplaar van Microsoft Entra-id.
$TenantId = (Get-AzSubscription -SubscriptionName "Contoso Default").TenantId
$ApplicationId = (Get-AzADApplication -DisplayNameStartWith exampleapp).AppId
$Thumbprint = (Get-ChildItem cert:\CurrentUser\My\ | Where-Object {$_.Subject -eq "CN=exampleappScriptCert" }).Thumbprint
Connect-AzAccount -ServicePrincipal `
-CertificateThumbprint $Thumbprint `
-ApplicationId $ApplicationId `
-TenantId $TenantId
Service-principal met certificaat van certificeringsinstantie maken
In het volgende voorbeeld wordt een service-principal gemaakt met behulp van een certificaat dat is uitgegeven door een certificeringsinstantie. De toewijzing is afgestemd op het opgegeven Azure-abonnement. De service-principal wordt toegevoegd aan de rol Lezer. Als er een fout optreedt bij het toewijzen van de rol, wordt het opnieuw geprobeerd.
Param (
[Parameter(Mandatory=$true)]
[String] $ApplicationDisplayName,
[Parameter(Mandatory=$true)]
[String] $SubscriptionId,
[Parameter(Mandatory=$true)]
[String] $CertPath,
[Parameter(Mandatory=$true)]
[String] $CertPlainPassword
)
Connect-AzAccount
Import-Module Az.Resources
Set-AzContext -Subscription $SubscriptionId
$CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force
$PFXCert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList @($CertPath, $CertPassword)
$KeyValue = [System.Convert]::ToBase64String($PFXCert.GetRawCertData())
$ServicePrincipal = New-AzADServicePrincipal -DisplayName $ApplicationDisplayName
New-AzADSpCredential -ObjectId $ServicePrincipal.Id -CertValue $KeyValue -StartDate $PFXCert.NotBefore -EndDate $PFXCert.NotAfter
Get-AzADServicePrincipal -ObjectId $ServicePrincipal.Id
$NewRole = $null
$Retries = 0;
While ($NewRole -eq $null -and $Retries -le 6)
{
# Sleep here for a few seconds to allow the service principal application to become active (should only take a couple of seconds normally)
Sleep 15
New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $ServicePrincipal.AppId | Write-Verbose -ErrorAction SilentlyContinue
$NewRole = Get-AzRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
$Retries++;
}
$NewRole
Certificaat opgeven via een automatisch PowerShell-script
Wanneer u zich aanmeldt als een service-principal, geeft u de tenant-id van de map voor uw AD-app op. Een tenant is een exemplaar van Microsoft Entra-id.
Param (
[Parameter(Mandatory=$true)]
[String] $CertPath,
[Parameter(Mandatory=$true)]
[String] $CertPlainPassword,
[Parameter(Mandatory=$true)]
[String] $ApplicationId,
[Parameter(Mandatory=$true)]
[String] $TenantId
)
$CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force
$PFXCert = New-Object `
-TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 `
-ArgumentList @($CertPath, $CertPassword)
$Thumbprint = $PFXCert.Thumbprint
Connect-AzAccount -ServicePrincipal `
-CertificateThumbprint $Thumbprint `
-ApplicationId $ApplicationId `
-TenantId $TenantId
De toepassings-id en tenant-id zijn geen gevoelige gegevens, dus u kunt deze rechtstreeks in uw script insluiten. Als u de tenant-id wilt ophalen, gebruikt u:
(Get-AzSubscription -SubscriptionName "Contoso Default").TenantId
Als u de toepassings-id wilt ophalen, gebruikt u:
(Get-AzADApplication -DisplayNameStartWith {display-name}).AppId
Referenties wijzigen
Als u de referenties voor een AD-app wilt wijzigen, bijvoorbeeld vanwege een inbreuk op de beveiliging of omdat de referenties zijn verlopen, gebruikt u de cmdlets Remove-AzADAppCredential en New-AzADAppCredential.
Als u alle referenties voor een toepassing wilt verwijderen, gebruikt u:
Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential
Als u een waarde voor een certificaat wilt toevoegen, maakt u een zelfondertekend certificaat zoals aangegeven in dit artikel. Vervolgens gebruikt u:
Get-AzADApplication -DisplayName exampleapp | New-AzADAppCredential `
-CertValue $keyValue `
-EndDate $cert.NotAfter `
-StartDate $cert.NotBefore
Fouten opsporen
Bij het maken van een service-principal kunnen de volgende foutmeldingen worden weergegeven:
'Authentication_Unauthorized' of 'Geen abonnement gevonden in de context'. - Deze fout wordt weergegeven wanneer uw account niet over de vereiste machtigingen beschikt voor de Microsoft Entra-id om een app te registreren. Normaal gesproken ziet u deze fout wanneer alleen beheerdersgebruikers in uw Microsoft Entra-id apps kunnen registreren en uw account geen beheerder is. Vraag uw beheerder om u toe te wijzen aan een beheerdersrol of om gebruikers in staat te stellen apps te registreren.
Uw account beschikt niet over machtigingen om de actie 'Microsoft.Authorization/roleAssignments/write' over scope '/subscriptions/{guid}' uit te voeren. - Deze foutmelding wordt weergegeven als uw account onvoldoende machtigingen heeft om een rol aan een identiteit toe te wijzen. Vraag de abonnementsbeheerder om u toe te voegen aan de rol Administrator voor gebruikerstoegang.
Volgende stappen
- Als u een service-principal met een wachtwoord wilt instellen, raadpleegt u Een Azure-service-principal maken met Azure PowerShell of een Azure-service-principal maken met Azure CLI.
- Zie Toepassingsobjecten en service-principalobjecten voor meer informatie over toepassingen en service-principals.
- Zie Verificatiescenario's voor Microsoft Entra-id voor meer informatie over Microsoft Entra-verificatie.
- Zie de naslaginformatie over toepassingen-API voor informatie over het werken met toepassingsregistraties met behulp van Microsoft Graph.