방법: 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 AD(Azure Active Directory) 인증을 지원하는 리소스에 액세스하는 경우 관리 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 및 이것이 지원되는 서비스를 알아보려면 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. 새 Az 모듈 및 AzureRM 호환성에 대한 자세한 내용은 새 Azure PowerShell Az 모듈 소개를 참조하세요.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 설치 지침은 Azure PowerShell 설치를 참조하세요.For 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. 스크립트가 대기하는 시간이 충분히 길지 않으면 "보안 주체 {ID}이(가) 디렉터리 {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 스크립트 센터에서 자체 서명된 인증서 생성기를 다운로드해야 합니다.If you do not have Windows 10 or Windows Server 2016, you need to download the Self-signed certificate generator from Microsoft Script Center. 해당 내용을 추출하고 필요한 cmdlet을 가져옵니다.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

스크립트에서 다음 두 줄을 바꾸어 인증서를 생성합니다.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-AzADAppCredentialNew-AzADAppCredential cmdlet을 사용합니다.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