Tworzenie jednostki usługi z certyfikatem przy użyciu programu Azure PowerShell

  • Artykuł

Jeśli masz aplikację lub skrypt, które potrzebują dostępu do zasobów, możesz skonfigurować tożsamość aplikacji i uwierzytelnić aplikację przy użyciu jej własnych poświadczeń. Ta tożsamość jest określana jako jednostka usługi. Takie podejście umożliwia:

  • Przypisywanie uprawnień do tożsamości aplikacji — są to uprawnienia inne niż Twoje. Zazwyczaj te uprawnienia są ograniczone tylko do czynności, które aplikacja musi wykonywać.
  • Używanie certyfikatu do uwierzytelnienia podczas wykonywania skryptu nienadzorowanego.

Ważne

Zamiast tworzyć jednostkę usługi, rozważ użycie tożsamości zarządzanych dla zasobów platformy Azure dla tożsamości aplikacji. Jeśli kod jest uruchamiany w usłudze obsługującej tożsamości zarządzane i uzyskuje dostęp do zasobów obsługujących uwierzytelnianie firmy Microsoft Entra, tożsamości zarządzane są dla Ciebie lepszym rozwiązaniem. Aby dowiedzieć się więcej o tożsamościach zarządzanych dla zasobów platformy Azure, w tym o usługach, które obecnie obsługują, zobacz Co to są tożsamości zarządzane dla zasobów platformy Azure?.

W tym artykule przedstawiono sposób tworzenia jednostki usługi uwierzytelnianej przy użyciu certyfikatu. Aby skonfigurować jednostkę przy użyciu hasła, zobacz Tworzenie jednostki usługi platformy Azure za pomocą programu Azure PowerShell.

Aby wykonać czynności z tego artykułu, musisz mieć najnowszą wersję programu PowerShell.

Uwaga

Do interakcji z platformą Azure zalecamy używanie modułu Azure Az w programie PowerShell. Zobacz Instalowanie programu Azure PowerShell, aby rozpocząć. Aby dowiedzieć się, jak przeprowadzić migrację do modułu Az PowerShell, zobacz Migracja programu Azure PowerShell z modułu AzureRM do modułu Az.

Wymagane uprawnienia

Aby ukończyć ten artykuł, musisz mieć wystarczające uprawnienia zarówno w ramach identyfikatora Microsoft Entra ID, jak i subskrypcji platformy Azure. W szczególności musisz mieć możliwość utworzenia aplikacji w usłudze Microsoft Entra ID i przypisania jednostki usługi do roli.

Najłatwiejszym sposobem sprawdzenia, czy Twoje konto ma odpowiednie uprawnienia, jest skorzystanie z portalu. Zobacz Sprawdzanie wymaganego uprawnienia.

Przypisywanie aplikacji do roli

Aby uzyskać dostęp do zasobów w ramach subskrypcji, musisz przypisać aplikację do roli. Zdecyduj, która rola oferuje odpowiednie uprawnienia dla aplikacji. Aby dowiedzieć się więcej o dostępnych rolach, zobacz Role wbudowane platformy Azure.

Zakres można ustawić na poziomie subskrypcji, grupy zasobów lub zasobu. Uprawnienia są dziedziczone do niższych poziomów zakresu. Na przykład dodanie aplikacji do roli Czytelnik dla grupy zasobów oznacza, że może odczytać grupę zasobów i wszystkie zawarte w niej zasoby. Aby umożliwić aplikacji wykonywanie akcji, takich jak ponowne uruchomienie, uruchamianie i zatrzymywanie wystąpień, wybierz rolę Współautor .

Tworzenie jednostki usługi z certyfikatem z podpisem własnym

Poniższy przykład przedstawia prosty scenariusz. Używa polecenia New-AzADServicePrincipal do utworzenia jednostki usługi z certyfikatem z podpisem własnym i używa polecenia New-AzRoleAssignment , aby przypisać rolę Czytelnik do jednostki usługi. Zakres przypisania roli to aktualnie wybrana subskrypcja platformy Azure. Aby wybrać inną subskrypcję, użyj polecenia Set-AzContext.

Uwaga

Polecenie cmdlet New-SelfSignedCertificate i moduł PKI nie są obecnie obsługiwane w programie 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

Przykład jest w stanie uśpienia przez 20 sekund, aby umożliwić propagację nowej jednostki usługi przez cały identyfikator Entra firmy Microsoft. Jeśli skrypt nie czeka wystarczająco długo, zostanie wyświetlony błąd z informacją: "Podmiot zabezpieczeń {ID} nie istnieje w katalogu {DIR-ID}". Aby rozwiązać ten błąd, zaczekaj chwilę, a następnie ponownie uruchom polecenie New-AzRoleAssignment .

Zakres przypisania roli do określonej grupy zasobów można określić za pomocą parametru ResourceGroupName. Zakres konkretnego zasobu można również określić za pomocą parametrów ResourceType i ResourceName.

Jeśli nie masz systemu Windows 10 lub Windows Server 2016, pobierz polecenie cmdlet New-SelfSignedCertificateEx z usługi PKI Solutions. Wyodrębnij jego zawartość i zaimportuj potrzebne polecenie cmdlet.

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

W skrypcie zastąp dwa poniższe wiersze w celu wygenerowania certyfikatu.

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

Udostępnianie certyfikatu za pośrednictwem zautomatyzowanego skryptu programu PowerShell

Za każdym razem, gdy logujesz się jako jednostka usługi, podaj identyfikator dzierżawy katalogu dla aplikacji usługi AD. Dzierżawa jest wystąpieniem identyfikatora Entra firmy Microsoft.

$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

Tworzenie jednostki usługi z certyfikatem od urzędu certyfikacji

W poniższym przykładzie użyto certyfikatu wystawionego przez urząd certyfikacji w celu utworzenia jednostki usługi. Zakres przypisania obejmuje określoną subskrypcję platformy Azure. Dodaje jednostkę usługi do roli Czytelnik . Jeśli podczas przypisywania roli wystąpi błąd, zostanie ponownie podjęta próba przypisania.

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

Udostępnianie certyfikatu za pośrednictwem zautomatyzowanego skryptu programu PowerShell

Za każdym razem, gdy logujesz się jako jednostka usługi, podaj identyfikator dzierżawy katalogu dla aplikacji usługi AD. Dzierżawa jest wystąpieniem identyfikatora Entra firmy Microsoft.

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

W identyfikatorach aplikacji i dzierżawy nie jest uwzględniana wielkość liter, więc można je osadzać bezpośrednio w skrypcie. Jeśli musisz pobrać identyfikator dzierżawy, użyj polecenia:

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

Jeśli musisz pobrać identyfikator aplikacji, użyj polecenia:

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

Zmienianie poświadczeń

Aby zmienić poświadczenia aplikacji usługi AD z powodu naruszenia zabezpieczeń lub wygaśnięcia poświadczeń, użyj poleceń cmdlet Remove-AzADAppCredential i New-AzADAppCredential.

Aby usunąć wszystkie poświadczenia aplikacji, należy użyć polecenia:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Aby dodać wartość certyfikatu, należy utworzyć certyfikat z podpisem własnym, jak pokazano w tym artykule. Następnie należy użyć polecenia:

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

Debugowanie

Podczas tworzenia jednostki usługi mogą wystąpić następujące błędy:

  • "Authentication_Unauthorized" lub "Nie znaleziono subskrypcji w kontekście". — Ten błąd jest wyświetlany, gdy Twoje konto nie ma wymaganych uprawnień do identyfikatora Entra firmy Microsoft w celu zarejestrowania aplikacji. Zazwyczaj ten błąd występuje, gdy tylko administratorzy w identyfikatorze Entra firmy Microsoft mogą rejestrować aplikacje, a Twoje konto nie jest administratorem. Poproś administratora o przypisanie Cię do roli administratora lub umożliwienie użytkownikom rejestrowania aplikacji.

  • Twoje konto "nie ma autoryzacji do wykonania akcji "Microsoft.Authorization/roleAssignments/write" w zakresie "/subscriptions/{guid}". — Ten błąd jest wyświetlany, gdy twoje konto nie ma wystarczających uprawnień do przypisania roli do tożsamości. Poproś administratora subskrypcji o dodanie Cię do roli Administrator dostępu użytkowników.

Następne kroki