Use Azure PowerShell to create a service principal with a certificate (Использование Azure PowerShell для создания субъекта-службы с сертификатом)

При наличии приложения или сценария, которому требуется доступ к ресурсам, можно настроить удостоверение для приложения и аутентифицировать его с помощью собственных учетных данных. Такое удостоверение называется субъект-служба. Такой подход позволяет выполнить следующие действия:

• Назначить удостоверению приложения разрешения, которые отличаются от ваших разрешений. Как правило, приложение получает именно те разрешения, которые требуются для его работы.
• Использовать сертификат для аутентификации при выполнении автоматического сценария.

В этой статье показано, как создать субъект-службу, который выполняет аутентификацию с помощью сертификата. Настройка субъекта-службы с паролем описана в статье Создание субъекта-службы Azure с помощью Azure PowerShell.

Для выполнения задач из этой статься требуется Azure PowerShell последней версии.

Необходимые разрешения

Чтобы завершить эту статью, необходимо иметь достаточные разрешения как в идентификаторе Microsoft Entra, так и в подписке Azure. В частности, вы должны иметь возможность создать приложение в идентификаторе Microsoft Entra и назначить субъект-службу роли.

Самый простой способ проверка, имеет ли ваша учетная запись достаточные разрешения, — через Центр администрирования Microsoft Entra.

Назначение приложению роли

Чтобы обеспечить доступ к ресурсам в подписке, необходимо назначить приложению роль. Укажите, какая роль предоставляет приложению необходимые разрешения. Дополнительные сведения о доступных ролях см. в статье Встроенные роли Azure.

Вы можете задать область действия на уровне подписки, группы ресурсов или ресурса. Разрешения наследуют более низкие уровни области действия. Например, добавление приложения в роль Читатель для группы ресурсов означает, что оно может использоваться для чтения группы ресурсов и любых содержащихся в ней ресурсов. Чтобы позволить приложению выполнять такие действия, как перезагрузка, запуск и остановка экземпляров, выберите роль Участник.

Создание субъекта-службы с самозаверяющим сертификатом

Ниже приводится простой пример сценария. В нем используется команда New-AzADServicePrincipal, чтобы создать субъект-службу с самозаверяющим сертификатом, а затем выполняется командлет New-AzRoleAssignment для присвоения этому субъекту-службе роли Читатель. Назначение ролей ограничивается текущей выбранной подпиской Azure. Чтобы выбрать другую подписку, выполните командлет 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 Reader -ServicePrincipalName $sp.AppId

В примере выполняется спящий режим в течение 20 секунд, чтобы новый субъект-служба распространился по идентификатору Microsoft Entra. Если скрипт не ожидает достаточно долгого времени, появится сообщение об ошибке "Субъект {ID} не существует в каталоге {DIR-ID}". Чтобы устранить эту ошибку, подождите некоторое время, а затем снова выполните команду New-AzRoleAssignment .

Вы можете задать область назначения ролей для определенной группы ресурсов с помощью параметра ResourceGroupName. Кроме того, вы можете задать область для определенного ресурса с помощью параметров ResourceType и ResourceName.

Если у вас нет ОС Windows 10 или Windows Server 2016, скачайте командлет New-SelfSignedCertificateEx с сайта решений PKI. Извлеките содержимое сценария и импортируйте требуемый командлет.

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

Замените в сценарии следующие две строки, чтобы создать сертификат.

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

При каждом входе в качестве субъекта-службы указывайте идентификатор клиента каталога, выделенный для приложения AD. Клиент — это экземпляр идентификатора Microsoft Entra.

$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

Создание субъекта-службы с помощью сертификата из центра сертификации

В приведенном ниже примере создается субъект-служба с сертификатом, выданным центром сертификации. Назначение ограничено указанной подпиской Azure. Субъекту-службе назначается роль Читатель. Если при назначении ролей возникнет ошибка, назначение выполняется повторно.

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

Предоставление сертификата с помощью автоматизированного сценария PowerShell

При каждом входе в качестве субъекта-службы указывайте идентификатор клиента каталога, выделенный для приложения AD. Клиент — это экземпляр идентификатора Microsoft Entra.

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

Идентификаторы приложения и клиента не являются конфиденциальными, поэтому их можно внедрить непосредственно в скрипт. Чтобы получить идентификатор клиента, используйте следующий командлет:

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

Чтобы получить идентификатор приложения, используйте следующий командлет:

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

Изменение учетных данных

Чтобы изменить учетные данные для приложения AD из-за нарушения безопасности или истечения их срока действия, используйте командлеты Remove-AzADAppCredential и New-AzADAppCredential.

Чтобы удалить все учетные данные для приложения, используйте следующую команду.

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Чтобы добавить значение сертификата, создайте самозаверяющий сертификат, как показано в этой статье. Затем используйте следующую команду.

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

Отладка

При создании субъекта-службы могут возникнуть следующие ошибки.

• "Authentication_Unauthorized" или "Подписка не найдена в контексте". — Эта ошибка возникает, если у вашей учетной записи нет необходимых разрешений на идентификаторе Microsoft Entra для регистрации приложения. Как правило, эта ошибка возникает, когда только администраторы в идентификаторе Microsoft Entra могут зарегистрировать приложения, а ваша учетная запись не является администратором. Попросите администратора назначить вам роль администратора или разрешить пользователям регистрировать приложения.

• Ваша учетная запись "не авторизована для выполнения действия 'Microsoft.Authorization/roleAssignments/write' с областью '/subscriptions/{guid}'." Эта ошибка возникает, когда учетная запись не имеет достаточно разрешений для назначения роли удостоверению. Попросите администратора подписки назначить вам роль администратора доступа пользователей.

Следующие шаги

• Сведения о настройке субъекта-службы с паролем см. в статье "Создание субъекта-службы Azure" с помощью Azure PowerShell или создание субъекта-службы Azure с помощью Azure CLI.
• Более подробное описание приложений и субъектов-служб см. в статье Объекты приложений и объекты участников-служб.
• Дополнительные сведения о проверке подлинности Microsoft Entra см. в сценариях проверки подлинности для идентификатора Microsoft Entra.
• Сведения о выполнении регистрации приложений с помощью Microsoft Graph см. в статье справочных материалах по API Приложения.