Azure PowerShell ile bir Azure hizmet sorumlusu oluşturmaCreate an Azure service principal with Azure PowerShell

Azure hizmetlerini kullanan otomatikleştirilmiş araçlar her zaman kısıtlı erişime sahip olmalıdır.Automated tools that use Azure services should always have restricted permissions. Azure, uygulamaların tam ayrıcalığa sahip kullanıcılar olarak oturum açmasına izin vermek yerine hizmet sorumlularını sunuyor.Instead of having applications sign in as a fully privileged user, Azure offers service principals.

Azure hizmet sorumlusu, Azure kaynaklarına erişen uygulamalar, barındırılan hizmetler ve otomatikleştirilmiş araçlar ile kullanılmak için oluşturulan bir kimliktir.An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Bu erişim, hizmet sorumlusuna atanan roller tarafından kısıtlanır ve hangi kaynaklara hangi düzeyde erişilebileceğini kontrol edebilirsiniz.This access is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level. Güvenlik nedeniyle, otomatikleştirilmiş araçların kullanıcı kimliği ile oturum açmalarına izin vermek yerine her zaman hizmet sorumlularını kullanmanız önerilir.For security reasons, it's always recommended to use service principals with automated tools rather than allowing them to log in with a user identity.

Bu makale, Azure PowerShell ile hizmet sorumlusu oluşturma, sıfırlama ve hakkında bilgi alma adımlarını gösterir.This article shows you the steps for creating, getting information about, and resetting a service principal with Azure PowerShell.

Uyarı

New-AzADServicePrincipal komutunu kullanarak hizmet sorumlusu oluşturduğunuzda, çıkışta korumanız gereken kimlik bilgileri yer alır.When you create a service principal using the New-AzADServicePrincipal command, the output includes credentials that you must protect. Alternatif olarak, kimlik bilgilerini kullanma gereksinimini ortadan kaldırmak için yönetilen kimlikleri kullanabilirsiniz.As an alternative, consider using managed identities to avoid the need to use credentials.

New-AzADServicePrincipal varsayılan olarak Katkıda bulunan rolünü abonelik kapsamında hizmet sorumlusuna atar.By default, New-AzADServicePrincipal assigns the Contributor role to the service principal at the subscription scope. Güvenliği ihlal edilmiş hizmet sorumlusu riskinizi azaltmak için daha belirli bir rol atayın ve kapsamı kaynağa ya da kaynak grubuna daraltın.To reduce your risk of a compromised service principal, assign a more specific role and narrow the scope to a resource or resource group. Daha fazla bilgi için bkz. Rol ataması ekleme adımları.See Steps to add a role assignment for more information.

Hizmet sorumlusu oluşturmaCreate a service principal

New-AzADServicePrincipal cmdlet’i ile hizmet sorumlusu oluşturun.Create a service principal with the New-AzADServicePrincipal cmdlet. Hizmet sorumlusu oluştururken, kullanacağınız oturum açma kimlik doğrulaması türünü seçebilirsiniz.When creating a service principal, you choose the type of sign-in authentication it uses.

Not

Hesabınız hizmet sorumlusu oluşturma iznine sahip değilse New-AzADServicePrincipal, “İşlemi tamamlamak için yeterli ayrıcalık yok” iletisini içeren bir hata döndürür.If your account doesn't have permission to create a service principal, New-AzADServicePrincipal will return an error message containing "Insufficient privileges to complete the operation". Hizmet sorumlusu oluşturmak için Azure Active Directory yöneticinizle iletişime geçin.Contact your Azure Active Directory admin to create a service principal.

Hizmet sorumluları için iki tür kimlik doğrulaması kullanılabilir: Parola tabanlı kimlik doğrulaması ve sertifika tabanlı kimlik doğrulaması.There are two types of authentication available for service principals: Password-based authentication, and certificate-based authentication.

Parola tabanlı kimlik doğrulamasıPassword-based authentication

Önemli

Parola tabanlı kimlik doğrulaması hizmet sorumlusu için varsayılan rol Katkıda Bulunan’dır.The default role for a password-based authentication service principal is Contributor. Bu rol, bir Azure hesabında okuma ve yazma için tam izne sahiptir.This role has full permissions to read and write to an Azure account. Rol atamalarını yönetme hakkında bilgi için bkz. Hizmet sorumlusu rollerini yönetme.For information on managing role assignments, see Manage service principal roles.

Diğer kimlik doğrulaması parametreleri olmadan parola tabanlı kimlik doğrulaması kullanılır ve sizin için rastgele bir parola oluşturulur.Without any other authentication parameters, password-based authentication is used and a random password created for you. Parola tabanlı kimlik doğrulaması istiyorsanız bu yöntem önerilir.If you want password-based authentication, this method is recommended.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

Döndürülen nesne, oluşturulan parolayı içeren bir SecureString olan Secret üyesini içerir.The returned object contains the Secret member, which is a SecureString containing the generated password. Hizmet sorumlusuyla kimlik doğrulaması yapabilmek için bu değeri güvenli bir yerde depoladığınızdan emin olun.Make sure that you store this value somewhere secure to authenticate with the service principal. Değeri, konsol çıkışında görüntülenmez.Its value won't be displayed in the console output. Parolayı kaybederseniz hizmet sorumlusu kimlik bilgilerini sıfırlayın.If you lose the password, reset the service principal credentials.

Aşağıdaki kod, gizli diziyi dışarı aktarmanıza olanak tanır:The following code will allow you to export the secret:

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
$UnsecureSecret = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

Kullanıcı tarafından sağlanan parolalar için -PasswordCredential bağımsız değişkeni Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential nesnelerini alır.For user-supplied passwords, the -PasswordCredential argument takes Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential objects. Bu nesneler, geçerli StartDate ve EndDate değerleri içermeli ve düz metin Password kabul etmelidir.These objects must have a valid StartDate and EndDate, and take a plaintext Password. Parola oluştururken Azure Active Directory parola kurallarına ve kısıtlamalarına uyduğunuzdan emin olun.When creating a password, make sure you follow the Azure Active Directory password rules and restrictions. Zayıf bir parola kullanmayın ve parolaları tekrar kullanmayın.Don't use a weak password or reuse a password.

Import-Module -Name Az.Resources # Imports the PSADPasswordCredential object
$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{StartDate=Get-Date; EndDate=Get-Date -Year 2024; Password=<Choose a strong password>}
$sp = New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials

New-AzADServicePrincipal cmdlet’inden döndürülen nesne Id ve DisplayName üyelerini içerir. Hizmet sorumlusuyla oturum açmak için bunların herhangi birini kullanabilirsiniz.The object returned from New-AzADServicePrincipal contains the Id and DisplayName members, either of which can be used for sign in with the service principal.

Önemli

Hizmet sorumlusuyla oturum açmak için hizmet sorumlusunun altında oluşturulduğu kiracı kimliği gerekir.Signing in with a service principal requires the tenant ID which the service principal was created under. Hizmet sorumlusu oluşturulduğunda etkin olan kiracıyı almak için hizmet sorumlusu oluşturulduktan hemen sonra şu komutu çalıştırın:To get the active tenant when the service principal was created, run the following command immediately after service principal creation:

(Get-AzContext).Tenant.Id

Sertifika tabanlı kimlik doğrulamasıCertificate-based authentication

Önemli

Sertifika tabanlı kimlik doğrulaması hizmet sorumlusu oluşturulurken atanan varsayılan bir rol yoktur.There is no default role assigned when creating a certificate-based authentication service principal. Rol atamalarını yönetme hakkında bilgi için bkz. Hizmet sorumlusu rollerini yönetme.For information on managing role assignments, see Manage service principal roles.

Sertifika tabanlı kimlik doğrulaması kullanan hizmet sorumluları -CertValue parametresiyle oluşturulur.Service principals using certificate-based authentication are created with the -CertValue parameter. Bu parametre, ortak sertifikanın base64 biçiminde kodlanmış ASCII dizesini alır.This parameter takes a base64-encoded ASCII string of the public certificate. Bu, PEM dosyası ya da metin biçiminde kodlanmış CRT veya CER olarak temsil edilir.This is represented by a PEM file, or a text-encoded CRT or CER. Ortak sertifikanın ikili kodlamaları desteklenmez.Binary encodings of the public certificate aren't supported. Bu yönergeler, mevcut bir sertifikanızın olduğunu varsayar.These instructions assume that you already have a certificate available.

$cert = <public certificate as base64-encoded string>
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert

PSADKeyCredential nesnelerini alan -KeyCredential parametresini de kullanabilirsiniz.You can also use the -KeyCredential parameter, which takes PSADKeyCredential objects. Bu nesneler geçerli StartDate ile EndDate değerleri içermelidir ve CertValue üyesi, ortak sertifikanın base64 biçiminde kodlanmış ASCII dizesine ayarlı olmalıdır.These objects must have a valid StartDate, EndDate, and have the CertValue member set to a base64-encoded ASCII string of the public certificate.

$cert = <public certificate as base64-encoded string>
$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADKeyCredential -Property @{StartDate=Get-Date; EndDate=Get-Date -Year 2024; KeyId=New-Guid; CertValue=$cert}
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -KeyCredential $credentials

New-AzADServicePrincipal cmdlet’inden döndürülen nesne Id ve DisplayName üyelerini içerir. Hizmet sorumlusuyla oturum açmak için bunların herhangi birini kullanabilirsiniz.The object returned from New-AzADServicePrincipal contains the Id and DisplayName members, either of which can be used for sign in with the service principal. Hizmet sorumlusuyla oturum açan kullanıcıların sertifikanın özel anahtarına da erişim sağlamaları gerekir.Clients which sign in with the service principal also need access to the certificate's private key.

Önemli

Hizmet sorumlusuyla oturum açmak için hizmet sorumlusunun altında oluşturulduğu kiracı kimliği gerekir.Signing in with a service principal requires the tenant ID which the service principal was created under. Hizmet sorumlusu oluşturulduğunda etkin olan kiracıyı almak için hizmet sorumlusu oluşturulduktan hemen sonra şu komutu çalıştırın:To get the active tenant when the service principal was created, run the following command immediately after service principal creation:

(Get-AzContext).Tenant.Id

Mevcut bir hizmet sorumlusunu almaGet an existing service principal

Etkin kiracı için hizmet sorumlularının listesini Get-AzADServicePrincipal ile alabilirsiniz.A list of service principals for the active tenant can be retrieved with Get-AzADServicePrincipal. Bu komut, varsayılan olarak bir kiracıdaki tüm hizmet sorumlularını döndürür.By default this command returns all service principals in a tenant. Büyük kuruluşlarda sonuçların döndürülmesi uzun sürebilir.For large organizations, it may take a long time to return results. Bunun yerine, isteğe bağlı sunucu tarafı filtreleme bağımsız değişkenlerinin birini kullanmanız önerilir:Instead, using one of the optional server-side filtering arguments is recommended:

  • -DisplayNameBeginsWith, sağlanan değer ile eşleşen ön eke sahip hizmet sorumlularını ister.-DisplayNameBeginsWith requests service principals that have a prefix that match the provided value. Hizmet sorumlusunun görünen adı, oluşturma sırasında -DisplayName ile ayarlanan değerdir.The display name of a service principal is the value set with -DisplayName during creation.
  • -DisplayName, bir hizmet sorumlusu adının tam eşleşmesini ister.-DisplayName requests an exact match of a service principal name.

Hizmet sorumlusu rollerini yönetmeManage service principal roles

Azure PowerShell, rol atamalarını yönetmek için aşağıdaki cmdlet’leri içerir:Azure PowerShell has the following cmdlets to manage role assignments:

Parola tabanlı kimlik doğrulaması hizmet sorumlusu için varsayılan rol Katkıda Bulunan’dır.The default role for a password-based authentication service principal is Contributor. Bu rol, bir Azure hesabında okuma ve yazma için tam izne sahiptir.This role has full permissions to read and write to an Azure account. Okuyucu rolü daha kısıtlayıcıdır, yalnızca salt okunur erişime sahiptir.The Reader role is more restrictive, with read-only access. Rol Tabanlı Erişim Denetimi (RBAC) ve roller hakkında daha fazla bilgi için bkz. RBAC: Yerleşik roller.For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

Bu örnek, Okuyucu rolünü ekler ve Katkıda Bulunan rolünü kaldırır:This example adds the Reader role and removes the Contributor one:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName 'Reader'
Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName 'Contributor'

Önemli

Rol atama cmdlet'leri, hizmet sorumlusu nesne kimliğini almaz.Role assignment cmdlets don't take the service principal object ID. Oluşturma zamanında üretilen ilişkili uygulama kimliğini alırlar.They take the associated application ID, which is generated at creation time. Hizmet sorumlusuna uygulama kimliği almak için Get-AzADServicePrincipal kullanın.To get the application ID for a service principal, use Get-AzADServicePrincipal.

Not

Hesabınızın rol atama izni yoksa hesabınızın “'Microsoft.Authorization/roleAssignments/write' eylemini gerçekleştirme yetkisi olmadığını” belirten bir hata iletisiyle karşılaşırsınız.If your account doesn't have permission to assign a role, you see an error message that your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write'". Rolleri yönetmek için Azure Active Directory yöneticinizle iletişime geçin.Contact your Azure Active Directory admin to manage roles.

Bir rol eklendiğinde, önceden atanmış izinler kısıtlanmaz.Adding a role doesn't restrict previously assigned permissions. Bir hizmet sorumlusunun izinlerini kısıtlarken Katkıda Bulunan rolü kaldırılmalıdır.When restricting a service principal's permissions, the Contributor role should be removed.

Atanan roller listelenerek değişiklikler doğrulanabilir:The changes can be verified by listing the assigned roles:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Hizmet sorumlusu kullanarak oturum açmaSign in using a service principal

Oturum açarak yeni hizmet sorumlusunun kimlik bilgilerini ve izinlerini test edin.Test the new service principal's credentials and permissions by signing in. Hizmet sorumlusu ile oturum açmak için, hizmet sorumlusuyla ilişkilendirilen applicationId değeri ve altında oluşturulduğu kiracı gereklidir.To sign in with a service principal, you need the applicationId value associated with it, and the tenant it was created under.

Hizmet sorumlusunda parola kullanarak oturum açmak için:To sign in with a service principal using a password:

# Use the application ID as the username, and the secret as password
$credentials = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $credentials -Tenant <tenant ID>

Sertifika tabanlı kimlik doğrulaması, Azure PowerShell’in sertifika parmak izini temel alarak bir yerel sertifika deposundan bilgi alabilir olmasını gerektirir.Certificate-based authentication requires that Azure PowerShell can retrieve information from a local certificate store based on a certificate thumbprint.

Connect-AzAccount -ServicePrincipal -Tenant <TenantId> -CertificateThumbprint <Thumbprint> -ApplicationId <ApplicationId>

Bir sertifikayı, PowerShell tarafından erişilebilir olan bir kimlik bilgileri deposundan içeri aktarmak için bkz. Azure PowerShell ile Oturum AçmaFor instructions on importing a certificate into a credential store accessible by PowerShell, see Sign in with Azure PowerShell

Kimlik bilgilerini sıfırlamaReset credentials

Hizmet sorumlusunun kimlik bilgilerini unutursanız rastgele bir parola ile yeni kimlik bilgileri eklemek için New-AzADSpCredential kullanın.If you forget the credentials for a service principal, use New-AzADSpCredential to add a new credential with a random password. Bu cmdlet, parola sıfırlanırken kullanıcı tanımlı kimlik bilgilerini desteklemez.This cmdlet does not support user-defined credentials when resetting the password.

Önemli

Yeni kimlik bilgileri atamadan önce, mevcut kimlik bilgileri kullanılarak oturum açılmasını önlemek için bunları silebilirsiniz.Before assigning any new credentials, you may want to remove existing credentials to prevent sign in with them. Bunu yapmak için, Remove-AzADSpCredential cmdlet’ini kullanın:To do so, use the Remove-AzADSpCredential cmdlet:

Remove-AzADSpCredential -DisplayName ServicePrincipalName
$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Sorun gidermeTroubleshooting

Şu hatayı alırsanız: “New-AzADServicePrincipal: identifierUris özelliğine yönelik aynı değere sahip başka bir nesne zaten var.” aynı ada sahip başka bir hizmet sorumlusunun zaten mevcut olup olmadığını doğrulayın.If you receive the error: "New-AzADServicePrincipal: Another object with the same value for property identifierUris already exists.", verify that a service principal with the same name doesn't already exist.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Mevcut hizmet sorumlusu artık gerekmiyorsa bunu aşağıdaki örneği kullanarak kaldırabilirsiniz.If the existing service principal is no longer needed, you can remove it using the following example.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Ayrıca, önceden Azure Active Directory uygulaması için bir hizmet sorumlusu oluşturduysanız bu hatayla karşılaşabilirsiniz.This error can also occur when you've previously created a service principal for an Azure Active Directory application. Hizmet sorumlusunu kaldırsanız da uygulama kullanılabilir.If you remove the service principal, the application is still available. Bu uygulama, aynı ada sahip başka bir hizmet sorumlusu oluşturmanızı engeller.This application prevents you from creating another service principal with the same name.

Aynı ada sahip başka bir Azure Active Directory uygulaması olup olmadığını doğrulamak için aşağıdaki örneği kullanabilirsiniz:You can use the following example to verify that an Azure Active Directory application with the same name doesn't exist:

Get-AzADApplication -DisplayName ServicePrincipalName

Aynı ada sahip başka bir uygulama varsa ve artık bu uygulamaya ihtiyaç duymuyorsanız aşağıdaki örneği kullanarak bunu kaldırabilirsiniz.If an application with the same name does exist and is no longer needed, it can be removed using the following example.

Remove-AzADApplication -DisplayName ServicePrincipalName

Bu uygulamaya ihtiyaç duyuyorsanız oluşturmayı denediğiniz yeni hizmet sorumlusu için alternatif bir ad seçin.Otherwise, choose an alternate name for the new service principal that you're attempting to create.