方法:Azure PowerShell を使用して資格情報でのサービス プリンシパルを作成するHow to: Use Azure PowerShell to create a service principal with a certificate

リソースへのアクセスを必要とするアプリやスクリプトがある場合は、アプリの ID を設定し、アプリを独自の資格情報で認証できます。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. この ID は、サービス プリンシパルと呼ばれます。This identity is known as a service principal. このアプローチを使用すると、以下のことを実行できます。This approach enables you to:

  • ユーザー自身のアクセス許可とは異なるアクセス許可を、アプリケーション ID に割り当てることができます。Assign permissions to the app identity that are different than your own permissions. 通常、こうしたアクセス許可は、アプリが行う必要があることに制限されます。Typically, these permissions are restricted to exactly what the app needs to do.
  • 無人スクリプトを実行するときに、証明書を使用して認証できます。Use a certificate for authentication when executing an unattended script.

重要

サービス プリンシパルを作成する代わりに、アプリケーション ID 用に Azure リソースのマネージド ID を使用することを検討します。Instead of creating a service principal, consider using managed identities for Azure resources for your application identity. コードが、マネージド ID をサポートするサービス上で実行され、Azure Active Directory (Azure AD) 認証をサポートするリソースにアクセスする場合、マネージド ID は優れた選択肢となります。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. Azure リソースのマネージド ID の詳細 (どのサービスが現在マネージド ID をサポートしているかなど) については、「Azure リソースのマネージド ID とは」を参照してください。To learn more about managed identities for Azure resources, including which services currently support it, see What is managed identities for Azure resources?.

この記事では、証明書を使用して認証するサービス プリンシパルの作成方法について説明します。This article shows you how to create a service principal that authenticates with a certificate. パスワードを使用するサービス プリンシパルを設定するには、「Azure PowerShell で Azure サービス プリンシパルを作成する」を参照してください。To set up a service principal with password, see Create an Azure service principal with Azure PowerShell.

このアーティクルには、PowerShell の最新バージョンが必要です。You must have the latest version of PowerShell for this article.

注意

この記事は、新しい Azure PowerShell Az モジュールを使用するために更新されました。This article has been updated to use the new Azure PowerShell Az module. AzureRM モジュールはまだ使用でき、少なくとも 2020 年 12 月までは引き続きバグ修正が行われます。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Az モジュールと AzureRM の互換性の詳細については、「Introducing the new Azure PowerShell Az module (新しい Azure PowerShell Az モジュールの概要)」を参照してください。To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Az モジュールのインストール手順については、Azure PowerShell のインストールを参照してください。For Az module installation instructions, see Install Azure PowerShell.

必要なアクセス許可Required permissions

この記事を完了するには、Azure AD と Azure サブスクリプションの両方で十分なアクセス許可を持っている必要があります。To complete this article, you must have sufficient permissions in both your Azure AD and Azure subscription. 具体的には、Azure AD でアプリケーションを作成し、ロールにサービス プリンシパルを割り当てることができる必要があります。Specifically, you must be able to create an app in the Azure AD, and assign the service principal to a role.

自分のアカウントに適切なアクセス許可があるかどうかを確認する最も簡単な方法は、ポータルを使用することです。The easiest way to check whether your account has adequate permissions is through the portal. 必要なアクセス許可のチェックに関するページを参照してください。See Check required permission.

自己署名証明書を使用したサービス プリンシパルの作成Create service principal with self-signed certificate

以下の例では、単純なシナリオについて説明します。The following example covers a simple scenario. ここでは、New-AzADServicePrincipal を使用して自己署名証明書でのサービス プリンシパルを作成し、New-AzureRmRoleAssignment を使用して共同作成者ロールをサービス プリンシパルに割り当てます。It uses New-AzADServicePrincipal to create a service principal with a self-signed certificate, and uses New-AzureRmRoleAssignment to assign the Contributor role to the service principal. ロールの割り当ては、現在選択されている Azure サブスクリプションに制限されます。The role assignment is scoped to your currently selected Azure subscription. 別のサブスクリプションを選択するには、Set-AzContext を使用します。To select a different subscription, use Set-AzContext.

$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 Contributor -ServicePrincipalName $sp.ApplicationId

この例では、新しいサービス プリンシパルが Azure AD 全体に反映されるまでの時間を設けるために、20 秒間スリープします。The example sleeps for 20 seconds to allow some time for the new service principal to propagate throughout Azure AD. スクリプトの待機時間が不足している場合は、次のエラーが表示されます。"プリンシパル {0} がディレクトリ {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}." このエラーを解決するには、しばらく待ってから New-AzRoleAssignment コマンドを再実行します。To resolve this error, wait a moment then run the New-AzRoleAssignment command again.

ResourceGroupNameパラメーターを使用して、特定のリソース グループにロールの割り当てをスコープできます。You can scope the role assignment to a specific resource group by using the ResourceGroupName parameter. ResourceTypeResourceNameパラメーターを使用して、特定のリソースをスコープすることもできます。You can scope to a specific resource by also using the ResourceType and ResourceName parameters.

Windows 10 または Windows Server 2016 を持っていない場合は、Microsoft スクリプト センターから Self-signed certificate generator をダウンロードします。If you do not have Windows 10 or Windows Server 2016, you need to download the Self-signed certificate generator from Microsoft Script Center. ダウンロードしたファイルを展開し、必要なコマンドレットをインポートします。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

このスクリプトでは、証明書を生成するために次の 2 行を置き換えます。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' }

自動化された PowerShell スクリプトから証明書を渡すProvide certificate through automated PowerShell script

サービス プリンシパルとしてサインインするときは常に、AD アプリのディレクトリのテナント ID を指定する必要があります。Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. テナントは、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

証明機関の証明書を使用したサービス プリンシパルの作成Create service principal with certificate from Certificate Authority

次の例では、証明機関から発行された証明書を使用して、サービス プリンシパルを作成します。The following example uses a certificate issued from a Certificate Authority to create service principal. 割り当ては、指定された Azure サブスクリプションに制限されます。The assignment is scoped to the specified Azure subscription. 共同作成者ロールにサービス プリンシパルが追加されます。It adds the service principal to the Contributor role. ロールの割り当て中にエラーが発生した場合は、割り当てが再試行されます。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 Contributor -ServicePrincipalName $ServicePrincipal.ApplicationId | Write-Verbose -ErrorAction SilentlyContinue
    $NewRole = Get-AzRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
    $Retries++;
 }
 
 $NewRole

自動化された PowerShell スクリプトから証明書を渡すProvide certificate through automated PowerShell script

サービス プリンシパルとしてサインインするときは常に、AD アプリのディレクトリのテナント ID を指定する必要があります。Whenever you sign in as a service principal, you need to provide the tenant ID of the directory for your AD app. テナントは、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 とテナント ID は機密情報ではないため、スクリプトに直接埋め込むことができます。The application ID and tenant ID aren't sensitive, so you can embed them directly in your script. テナント ID を取得する必要がある場合は、次のコマンドを使用します。If you need to retrieve the tenant ID, use:

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

アプリケーション ID を取得する必要がある場合は、次のコマンドを使用します。If you need to retrieve the application ID, use:

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

資格情報の変更Change credentials

セキュリティ侵害の発生または資格情報の期限切れのために AD アプリの資格情報を変更するには、Remove-AzADAppCredential コマンドレットと 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.

アプリケーションのすべての資格情報を削除するには、次のコマンドレットを使用します。To remove all the credentials for an application, use:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

証明書の値を追加するには、この記事の説明に従って自己署名証明書を作成します。To add a certificate value, create a self-signed certificate as shown in this article. その後、次のコマンドレットを使用します。Then, use:

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

デバッグDebug

サービス プリンシパルの作成時に、以下のエラーが発生する場合があります。You may get the following errors when creating a service principal:

  • "Authentication_Unauthorized" または "コンテキストにサブスクリプトが見つかりません""Authentication_Unauthorized" or "No subscription found in the context." - アカウントが Azure AD でアプリを登録するために必要なアクセス許可を持っていない場合に、このエラーが表示されます。- You see this error when your account doesn't have the required permissions on the Azure AD to register an app. 通常は、Azure Active Directory の管理者ユーザーのみがアプリを登録できるときに、自分のアカウントが管理者でない場合に、このエラーが発生します。管理者に連絡して、自分を管理者ロールに割り当ててもらうか、ユーザーがアプリケーションを登録できるようにしてもらいます。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.

  • アカウントに "'/subscriptions/{guid}' をスコープとした 'Microsoft.Authorization/roleAssignments/write' のアクションを実行するためのアクセス権限がありません" - このエラーは、自分のアカウントが ID にロールを割り当てるのに十分なアクセス許可を持っていない場合に表示されます。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. サブスクリプション管理者に連絡して、自分をユーザー アクセス管理者ロールに追加してもらいます。Ask your subscription administrator to add you to User Access Administrator role.

次の手順Next steps