Dela via

Använd Azure PowerShell för att skapa ett huvudnamn för tjänsten med certifikat

  • Artikel

När du har en app eller ett skript som behöver åtkomst till resurser, kan du ställa in en identitet för appen och autentisera den med sina egna autentiseringsuppgifter. Den här identiteten kallas tjänstens huvudnamn. Med den här metoden kan du:

  • Tilldela behörigheter till app-identiteten som skiljer sig från din egen behörighet. Vanligen är dessa behörigheter begränsade till exakt vad appen behöver göra.
  • Använda ett certifikat för autentisering när du kör oövervakade skript.

Viktigt!

I stället för att skapa ett huvudnamn för tjänsten bör du överväga att använda hanterade identiteter för Azure-resurser för din programidentitet. Om koden körs på en tjänst som stöder hanterade identiteter och har åtkomst till resurser som stöder Microsoft Entra-autentisering är hanterade identiteter ett bättre alternativ för dig. Mer information om hanterade identiteter för Azure-resurser, inklusive vilka tjänster som för närvarande stöder det, finns i Vad är hanterade identiteter för Azure-resurser?.

Den här artikeln visar hur du skapar ett huvudnamn för tjänsten som autentiserar med ett certifikat. Om du vill konfigurera ett huvudnamn för tjänsten med lösenord, se Skapa tjänstens huvudnamn för Azure med Azure PowerShell.

Du måste ha den senaste versionen av PowerShell för den här artikeln.

Kommentar

Vi rekommenderar att du använder Azure Az PowerShell-modulen för att interagera med Azure. Se Installera Azure PowerShell för att komma igång. Information om hur du migrerar till Az PowerShell-modulen finns i artikeln om att migrera Azure PowerShell från AzureRM till Az.

Behörigheter som krävs

För att kunna slutföra den här artikeln måste du ha tillräcklig behörighet i både ditt Microsoft Entra-ID och din Azure-prenumeration. Mer specifikt måste du kunna skapa en app i Microsoft Entra-ID och tilldela tjänstens huvudnamn till en roll.

Det enklaste sättet att kontrollera om ditt konto har tillräckliga behörigheter är via administrationscentret för Microsoft Entra.

Tilldela programmet till en roll

För att få åtkomst till resurser i din prenumeration måste du tilldela programmet till en roll. Bestäm vilken roll som ger rätt behörigheter för programmet. Mer information om tillgängliga roller finns i Inbyggda Roller i Azure.

Du kan ange omfånget på prenumerationsnivå, resursgrupp eller resursnivå. Behörigheter ärvs till lägre omfångsnivåer. Om du till exempel lägger till ett program i rollen Läsare för en resursgrupp kan det läsa resursgruppen och alla resurser som den innehåller. Om du vill att programmet ska kunna köra åtgärder som omstart, starta och stoppa instanser väljer du rollen Deltagare .

Skapa huvudnamn för tjänsten med självsignerade certifikat

Följande exempel visar ett enkelt scenario. Den använder New-AzADServicePrincipal för att skapa ett huvudnamn för tjänsten med ett självsignerat certifikat och använder New-AzRoleAssignment för att tilldela rollen Läsare till tjänstens huvudnamn. Rolltilldelningen är begränsad till den valda Azure-prenumerationen. Om du vill välja en annan prenumeration använder du Set-AzContext.

Kommentar

Cmdleten New-SelfSignedCertificate och PKI-modulen stöds för närvarande inte i 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

Exemplet ligger i viloläge i 20 sekunder så att det nya tjänstens huvudnamn kan spridas i Microsoft Entra-ID. Om skriptet inte väntar tillräckligt länge visas ett fel som anger: "Huvudnamn {ID} finns inte i katalogen {DIR-ID}." Lös det här felet genom att vänta en stund och sedan köra kommandot New-AzRoleAssignment igen.

Du kan ange omfånget för rolltilldelningen till en viss resursgrupp med hjälp av parametern ResourceGroupName. Du kan också ange omfånget för en viss resurs med parametrarna ResourceType och ResourceName.

Om du inte har Windows 10 eller Windows Server 2016 laddar du ned cmdleten New-SelfSignedCertificateEx från PKI Solutions. Extrahera innehållet och importera den cmdlet som du behöver.

# Only run if you could not use New-SelfSignedCertificate
Import-Module -Name c:\ExtractedModule\New-SelfSignedCertificateEx.ps1

Ersätt följande två rader i skriptet för att generera certifikatet.

New-SelfSignedCertificateEx -StoreLocation CurrentUser `
  -Subject "CN=exampleapp" `
  -KeySpec "Exchange" `
  -FriendlyName "exampleapp"
$cert = Get-ChildItem -path Cert:\CurrentUser\my | where {$PSitem.Subject -eq 'CN=exampleapp' }

Ange certifikat via det automatiska PowerShell-skriptet

När du loggar in som tjänstens huvudnamn anger du klientorganisations-ID för katalogen för din AD-app. En klientorganisation är en instans av 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

Skapa tjänstens huvudnamn med certifikat från certifikatutfärdaren

I följande exempel används ett certifikat som utfärdats från en certifikatutfärdare för att skapa tjänstens huvudnamn. Tilldelningen begränsas till den angivna Azure-prenumerationen. Tjänstens huvudnamn läggs till i rollen Läsare . Om ett fel inträffar under rolltilldelningen försöker det göra om tilldelningen.

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

Ange certifikat via det automatiska PowerShell-skriptet

När du loggar in som tjänstens huvudnamn anger du klientorganisations-ID för katalogen för din AD-app. En klientorganisation är en instans av 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

App-ID och klientorganisations-ID är inte känsliga data, så du kan bädda in dem direkt i skriptet. Om du behöver hämta klientorganisations-ID, använd:

(Get-AzSubscription -SubscriptionName "Contoso Default").TenantId

Om du behöver hämta app-ID, använd:

(Get-AzADApplication -DisplayNameStartWith {display-name}).AppId

Ändra autentiseringsuppgifter

Om du vill ändra autentiseringsuppgifterna för en AD-app använder du cmdletarna Remove-AzADAppCredential och New-AzADAppCredential, antingen på grund av en säkerhetskompromation eller ett förfallodatum för autentiseringsuppgifter.

För att ta bort alla autentiseringsuppgifter för en app, använd:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Skapa ett självsignerat certifikat för att lägga till ett certifikatvärde som visas i den här artikeln. Använd sedan:

Get-AzADApplication -DisplayName exampleapp | New-AzADAppCredential `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore

Felsöka

Du kan få följande fel när du skapar ett huvudnamn för tjänsten:

  • "Authentication_Unauthorized" eller "Ingen prenumeration hittades i kontexten." – Det här felet visas när ditt konto inte har de behörigheter som krävs för Microsoft Entra-ID:t för att registrera en app. Vanligtvis ser du det här felet när endast administratörsanvändare i ditt Microsoft Entra-ID kan registrera appar och ditt konto inte är administratör. Be administratören att antingen tilldela dig en administratörsroll eller att göra det möjligt för användare att registrera appar.

  • Ditt konto "har inte behörighet att utföra åtgärden 'Microsoft.Authorization/roleAssignments/write' över omfånget '/subscriptions/{guid}'." – Det här felet visas när ditt konto inte har tillräcklig behörighet för att tilldela en roll till en identitet. Be din prenumerationsadministratör att ge dig rollen som administratör för användaråtkomst.

Nästa steg