Azure PowerShell gebruiken om een service-principal met een certificaat te maken

  • Artikel

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 de juiste machtigingen beschikt, verloopt via de portal. Zie Check required permission (Vereiste machtiging controleren).

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-​AzAD​Service​Principal 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