Postupy: použití Azure PowerShell k vytvoření instančního objektu s certifikátemHow to: Use Azure PowerShell to create a service principal with a certificate

Pokud máte aplikaci nebo skript, který potřebuje přístup k prostředkům, můžete pro aplikaci nastavit identitu a ověřit tuto aplikaci jejími vlastními přihlašovacími údaji.When you have an app or script that needs to access resources, you can set up an identity for the app and authenticate the app with its own credentials. Tato identita se označuje jako instanční objekt.This identity is known as a service principal. Tento přístup vám umožní:This approach enables you to:

  • Přiřadit identitě aplikace oprávnění, která se budou lišit od vašich vlastních oprávnění.Assign permissions to the app identity that are different than your own permissions. Tato oprávnění jsou obvykle omezená přesně na to, co aplikace potřebuje dělat.Typically, these permissions are restricted to exactly what the app needs to do.
  • Při provádění bezobslužného skriptu použít k ověření certifikát.Use a certificate for authentication when executing an unattended script.

Důležité

Místo Vytvoření instančního objektu zvažte použití spravovaných identit pro prostředky Azure pro vaši identitu aplikace.Instead of creating a service principal, consider using managed identities for Azure resources for your application identity. Pokud je váš kód spuštěný na službě, která podporuje spravované identity, a přistupuje k prostředkům, které podporují ověřování Azure Active Directory (Azure AD), jsou spravované identity lepší volbou pro vás.If your code runs on a service that supports managed identities and accesses resources that support Azure Active Directory (Azure AD) authentication, managed identities are a better option for you. Další informace o spravovaných identitách pro prostředky Azure, včetně toho, které služby v současnosti podporují, najdete v tématu co jsou spravované identity pro prostředky Azure?.To learn more about managed identities for Azure resources, including which services currently support it, see What is managed identities for Azure resources?.

Tento článek vám ukazuje, jak vytvořit instanční objekt, který se ověřuje certifikátem.This article shows you how to create a service principal that authenticates with a certificate. Pokud chcete nastavit instanční objekt s heslem, podívejte se na článek věnovaný vytvoření instančního objektu Azure s použitím prostředí Azure PowerShell.To set up a service principal with password, see Create an Azure service principal with Azure PowerShell.

K tomuto článku musíte mít nejnovější verzi PowerShellu.You must have the latest version of PowerShell for this article.

Poznámka

Tento článek je aktualizovaný a využívá nový modul Az Azure PowerShellu.This article has been updated to use the new Azure PowerShell Az module. Můžete dál využívat modul AzureRM, který bude dostávat opravy chyb nejméně do prosince 2020.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Další informace o kompatibilitě nového modulu Az a modulu AzureRM najdete v tématu Seznámení s novým modulem Az Azure PowerShellu.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Pokyny k instalaci modulu Az najdete v tématu věnovaném instalaci Azure PowerShellu.For Az module installation instructions, see Install Azure PowerShell.

Požadovaná oprávněníRequired permissions

K dokončení tohoto článku musíte mít dostatečná oprávnění v rámci vašeho předplatného Azure AD i Azure.To complete this article, you must have sufficient permissions in both your Azure AD and Azure subscription. Konkrétně musíte být schopni vytvořit aplikaci v Azure AD a přiřadit instanční objekt roli.Specifically, you must be able to create an app in the Azure AD, and assign the service principal to a role.

Nejjednodušším způsobem, jak zkontrolovat, jestli má váš účet dostatečná oprávnění, je použít k tomu portál.The easiest way to check whether your account has adequate permissions is through the portal. Informace najdete v článku Kontrola požadovaných oprávnění.See Check required permission.

Přiřazení aplikace k roliAssign the application to a role

Pokud chcete získat přístup k prostředkům ve vašem předplatném, musíte aplikaci přiřadit k roli.To access resources in your subscription, you must assign the application to a role. Rozhodněte, která role nabízí správná oprávnění pro aplikaci.Decide which role offers the right permissions for the application. Další informace o dostupných rolích najdete v tématu předdefinované role Azure.To learn about the available roles, see Azure built-in roles.

Rozsah můžete nastavit na úrovni předplatného, skupiny prostředků nebo prostředku.You can set the scope at the level of the subscription, resource group, or resource. Oprávnění jsou zděděna na nižší úrovně rozsahu.Permissions are inherited to lower levels of scope. Například přidání aplikace do role Čtenář pro skupinu prostředků znamená, že může číst skupinu prostředků a všechny prostředky, které obsahuje.For example, adding an application to the Reader role for a resource group means it can read the resource group and any resources it contains. Pokud chcete aplikaci dovolit, aby prováděla akce, jako je restartování, spuštění a zastavení instancí, vyberte roli Přispěvatel .To allow the application to execute actions like reboot, start and stop instances, select the Contributor role.

Vytvoření instančního objektu s certifikátem podepsaným svým držitelemCreate service principal with self-signed certificate

Následující příklad popisuje jednoduchou situaci.The following example covers a simple scenario. Používá New-AzADServicePrincipal k vytvoření instančního objektu s certifikátem podepsaným svým držitelem a pomocí New-AzRoleAssignment přiřadí roli čtenáře k instančnímu objektu.It uses New-AzADServicePrincipal to create a service principal with a self-signed certificate, and uses New-AzRoleAssignment to assign the Reader role to the service principal. Přiřazení role je vymezené vaším aktuálně vybraným předplatným Azure.The role assignment is scoped to your currently selected Azure subscription. Pokud chcete vybrat jiné předplatné, použijte set-AzContext.To select a different subscription, use Set-AzContext.

Poznámka

Rutina New-SelfSignedCertificate a modul PKI se v prostředí PowerShell Core momentálně nepodporují.The New-SelfSignedCertificate cmdlet and the PKI module are currently not supported 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.ApplicationId

Příkladem je režim spánku, který po dobu 20 sekund umožní určitému novému instančnímu objektu rozšíření v rámci služby Azure AD určitou dobu.The example sleeps for 20 seconds to allow some time for the new service principal to propagate throughout Azure AD. Pokud tato čekací doba skriptu není dostatečně dlouhá, zobrazí se vám chybová zpráva: Objekt zabezpečení {ID} není v adresáři {DIR-ID}."If your script doesn't wait long enough, you'll see an error stating: "Principal {ID} does not exist in the directory {DIR-ID}." Pokud chcete tuto chybu vyřešit, chvíli počkejte a pak znovu spusťte příkaz New-AzRoleAssignment .To resolve this error, wait a moment then run the New-AzRoleAssignment command again.

Přiřazení role můžete vymezit na konkrétní skupinu prostředků pomocí parametru ResourceGroupName.You can scope the role assignment to a specific resource group by using the ResourceGroupName parameter. Vymezit konkrétní rozsah můžete také pomocí parametrů ResourceType a ResourceName.You can scope to a specific resource by also using the ResourceType and ResourceName parameters.

Pokud nemáte Windows 10 nebo Windows Server 2016, musíte si z webu Microsoft Script Center stáhnout generátor certifikátů podepsaných svým držitelem.If you do not have Windows 10 or Windows Server 2016, you need to download the Self-signed certificate generator from Microsoft Script Center. Rozbalte jeho obsah a importujte potřebnou rutinu.Extract its contents and import the cmdlet you need.

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

Ve skriptu nahraďte následující dva řádky, aby se vygeneroval certifikát.In the script, substitute the following two lines to generate the certificate.

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

Poskytnutí certifikátu pomocí automatizovaného skriptu PowerShelluProvide certificate through automated PowerShell script

Vždy, když se přihlásíte jako instanční objekt, musíte pro svoji aplikaci AD zadat ID tenanta adresáře.Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. Tenant je instance služby Azure AD.A tenant is an instance of Azure AD.

$TenantId = (Get-AzSubscription -SubscriptionName "Contoso Default").TenantId
$ApplicationId = (Get-AzADApplication -DisplayNameStartWith exampleapp).ApplicationId

$Thumbprint = (Get-ChildItem cert:\CurrentUser\My\ | Where-Object {$_.Subject -eq "CN=exampleappScriptCert" }).Thumbprint
Connect-AzAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

Vytvoření instančního objektu pomocí certifikátu z certifikační autorityCreate service principal with certificate from Certificate Authority

Následující příklad používá k vytvoření instančního objektu certifikát vydaný certifikační autoritou.The following example uses a certificate issued from a Certificate Authority to create service principal. Přiřazení je vymezené na zadané předplatné Azure.The assignment is scoped to the specified Azure subscription. Přidá instanční objekt do role čtenáře .It adds the service principal to the Reader role. Pokud dojde k chybě při přiřazení role, dojde k dalšímu pokusu o přiřazení.If an error occurs during the role assignment, it retries the assignment.

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.ApplicationId | Write-Verbose -ErrorAction SilentlyContinue
    $NewRole = Get-AzRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
    $Retries++;
 }

 $NewRole

Poskytnutí certifikátu pomocí automatizovaného skriptu PowerShelluProvide certificate through automated PowerShell script

Vždy, když se přihlásíte jako instanční objekt, musíte pro svoji aplikaci AD zadat ID tenanta adresáře.Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. Tenant je instance služby Azure AD.A tenant is an instance of Azure AD.

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

ID aplikace a ID tenanta nejsou důvěrná, takže je můžete vložit přímo do skriptu.The application ID and tenant ID aren't sensitive, so you can embed them directly in your script. Pokud potřebujete načíst ID tenanta, použijte tento kód:If you need to retrieve the tenant ID, use:

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

Pokud potřebujete načíst ID aplikace, použijte tento kód:If you need to retrieve the application ID, use:

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

Změna přihlašovacích údajůChange credentials

Pokud chcete změnit přihlašovací údaje pro aplikaci AD z důvodu bezpečnostního ohrožení nebo vypršení platnosti přihlašovacích údajů, použijte rutiny Remove-AzADAppCredential a New-AzADAppCredential .To change the credentials for an AD app, either because of a security compromise or a credential expiration, use the Remove-AzADAppCredential and New-AzADAppCredential cmdlets.

Pokud chcete odebrat všechny přihlašovací údaje pro aplikaci, použijte tento kód:To remove all the credentials for an application, use:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Pokud chcete přidat hodnotu certifikátu, vytvořte certifikát podepsaný svým držitelem, jak je znázorněno v tomto článku.To add a certificate value, create a self-signed certificate as shown in this article. Potom použijte:Then, use:

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

LaděníDebug

Při vytváření instančního objektu může dojít k následujícím chybám:You may get the following errors when creating a service principal:

  • Ověřování_neautorizované nebo V kontextu se nenašlo žádné předplatné."Authentication_Unauthorized" or "No subscription found in the context." – Tato chyba se zobrazí, pokud váš účet nemá požadovaná oprávnění k registraci aplikace v Azure AD.- You see this error when your account doesn't have the required permissions on the Azure AD to register an app. Tato chyba se obvykle zobrazuje, když můžou registrovat aplikace jenom uživatelé Azure Active Directory s právy pro správu, a váš účet není správce. Požádejte správce, aby vám přidělil roli správce nebo aby uživatelům umožnil registraci aplikací.Typically, you see this error when only admin users in your Azure Active Directory can register apps, and your account isn't an admin. Ask your administrator to either assign you to an administrator role, or to enable users to register apps.

  • Váš účet nemá autorizaci k provedení akce "Microsoft. Authorization/roleAssignments/Write" nad oborem "/Subscriptions/{GUID}". " – Tato chyba se zobrazí, pokud váš účet nemá dostatečná oprávnění k přiřazení role k identitě.Your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write' over scope '/subscriptions/{guid}'." - You see this error when your account doesn't have sufficient permissions to assign a role to an identity. Požádejte správce předplatného, aby vás přidal do role Správce přístupu uživatelů.Ask your subscription administrator to add you to User Access Administrator role.

Další krokyNext steps