New-AzADServicePrincipal

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Module:

Az.Resources

Creates a new Azure active directory service principal.

Warning

There are upcoming breaking changes in this cmdlet. These changes are currently in preview with Az.Resources version 5.0.0-preview. They will become generally available with our next major release of the Az PowerShell module, version 7.x in December of 2021. For more information, see Azure AD to Microsoft Graph migration changes in Azure PowerShell.

Note

This is the previous version of our documentation. Please consult the most recent version for up-to-date information.

Syntax

New-AzADServicePrincipal
   [-ApplicationId <Guid>]
   [-DisplayName <String>]
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-Scope <String>]
   [-Role <String>]
   [-SkipAssignment]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationId <Guid>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationId <Guid>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationId <Guid>
   -PasswordCredential <PSADPasswordCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationId <Guid>
   -CertValue <String>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationId <Guid>
   -KeyCredential <PSADKeyCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -DisplayName <String>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -DisplayName <String>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -DisplayName <String>
   -PasswordCredential <PSADPasswordCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -DisplayName <String>
   -CertValue <String>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -DisplayName <String>
   -KeyCredential <PSADKeyCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationObject <PSADApplication>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationObject <PSADApplication>
   -PasswordCredential <PSADPasswordCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationObject <PSADApplication>
   -CertValue <String>
   [-StartDate <DateTime>]
   [-EndDate <DateTime>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzADServicePrincipal
   -ApplicationObject <PSADApplication>
   -KeyCredential <PSADKeyCredential[]>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

Creates a new Azure active directory service principal. The default parameter set uses default values for parameters if they are not provided. For more information on default values, see the description for each parameter. This cmdlet has the ability to assign a role to the service principal with the Role and Scope parameters. If both are omitted, the contributor role is assigned to the service principal. The default values for the Role and Scope parameters are Contributor for the current subscription. The cmdlet creates an application and sets its properties if an ApplicationId is not provided. To update the application-specific parameters, use the Update-AzADApplication cmdlet.

Warning

When you create a service principal using the New-AzADServicePrincipal command, the output includes credentials that you must protect. As an alternative, consider using managed identities to avoid the need to use credentials.

By default, New-AzADServicePrincipal assigns the Contributor role to the service principal at the subscription scope. To reduce your risk of a compromised service principal, assign a more specific role and narrow the scope to a resource or resource group. See Steps to add a role assignment for more information.

Examples

Example 1: Simple AD service principal creation

The following example creates an AD service principal using default values for parameters not specified. Since an application ID is not provided, an application is created for the service principal. Since no values are provided for Role or Scope, the created service principal is assigned the contributor role for the current subscription.

New-AzADServicePrincipal

Secret                : System.Security.SecureString
ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : 00000000-0000-0000-0000-000000000000
Type                  : ServicePrincipal

WARNING: Assigning role 'Contributor' over scope '/subscriptions/00000000-0000-0000-0000-000000000000' to the new service principal.

Example 2: Simple AD service principal creation with a specified role and default scope

The following example creates an AD service principal using the default values for parameters not specified. Since the application ID is not provided, an application is created for the service principal. The service principal is created with Reader permissions for the current subscription since no value is provided for the Scope parameter.

New-AzADServicePrincipal -Role Reader

Secret                : System.Security.SecureString
ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : 00000000-0000-0000-0000-000000000000
Type                  : ServicePrincipal

WARNING: Assigning role 'Reader' over scope '/subscriptions/00000000-0000-0000-0000-000000000000' to the new service principal.

Example 3: Simple AD service principal creation with a specified scope and default role

The following example creates an AD service principal using the default values for parameters not specified. Since the application ID is not provided, an application is created for the service principal. The service principal is created with Contributor permissions for the provided resource group scope since no value is provided for the Role parameter.

New-AzADServicePrincipal -Scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup

Secret                : System.Security.SecureString
ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : 00000000-0000-0000-0000-000000000000
Type                  : ServicePrincipal

WARNING: Assigning role 'Contributor' over scope '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup' to the new service principal.

Example 4: Simple AD service principal creation with a specified scope and role

The following example creates an AD service principal using the default values for parameters not specified. Since the application ID is not provided, an application is created for the service principal. The service principal is created with Reader permissions for the provided resource group scope.

New-AzADServicePrincipal -Role Reader -Scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup

Secret                : System.Security.SecureString
ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : 00000000-0000-0000-0000-000000000000
Type                  : ServicePrincipal

WARNING: Assigning role 'Reader' over scope '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup' to the new service principal.

Example 5: Create a new AD service principal using application ID with role assignment

The following example creates a new AD service principal for the application with application ID '00000000-0000-0000-0000-000000000000'. Since no values are provided for Role or Scope, the created service principal is assigned the contributor role for the current subscription.

New-AzADServicePrincipal -ApplicationId 00000000-0000-0000-0000-000000000000

ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://my-temp-app}
ApplicationId         : 00000000-0000-0000-0000-000000000000
DisplayName           : my-temp-app
Id                    : 00000000-0000-0000-0000-000000000000
Type                  : ServicePrincipal

Example 6: Create a new AD service principal using piping

The following example retrieves the application with object ID '3ede3c26-b443-4e0b-9efc-b05e68338dc3' using the Get-AzADApplication cmdlet. The results are piped to the New-AzADServicePrincipal cmdlet to create a new AD service principal for that application.

Get-AzADApplication -ObjectId 3ede3c26-b443-4e0b-9efc-b05e68338dc3 | New-AzADServicePrincipal

Example 7: Create a new AD service principal using DisplayName and password credential

The following example creates a new application with the name ServicePrincipalName and a password of StrongPassworld!23. It creates the service principal based on the created application. The start date and end date are added to the password credential.

$credentials = New-Object -TypeName Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{
  StartDate=Get-Date; EndDate=Get-Date -Year 2024; Password='StrongPassworld!23'}
$sp = New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials

ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000c
ObjectType            : ServicePrincipal
DisplayName           : ServicePrincipalName
Id                    : 00000000-0000-0000-0000-000000000000
Type                  :

Example 8: Create a new AD service principal using DisplayName and plain key credential

The following example creates a new application with the name ServicePrincipalName and a certificate $cert. It creates the service principal based on the application created. The end date is added to key credential.

$cert = 'public certificate as Base64 encoded string'
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert  -EndDate '2021-01-01'

ServicePrincipalNames : {00000000-0000-0000-0000-000000000000}
ApplicationId         : 00000000-0000-0000-0000-000000000000
ObjectType            : ServicePrincipal
DisplayName           : ServicePrincipalName
Id                    : 00000000-0000-0000-0000-000000000000
Type                  :

Parameters

-ApplicationId

The unique application ID for a service principal in a tenant. Once created this property cannot be changed. If an application ID for an existing application is not specified, an application is created.

Type:	Guid
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationObject

The object representing the application for which the service principal is created.

Type:	PSADApplication
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-CertValue

The value of the asymmetric credential type. It represents the Base64 encoded certificate.

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Type:	IAzureContextContainer
Aliases:	AzContext, AzureRmContext, AzureCredential
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-DisplayName

The friendly name of the service principal. If a display name is not provided, this value will default to azure-powershell-MM-dd-yyyy-HH-mm-ss where the suffix is the time of application creation.

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-EndDate

The effective end date of the credential usage. The default end date value is one year from today. For an asymmetric type credential, this must be set to on or before the date that the X509 certificate is valid.

Type:	DateTime
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyCredential

The collection of key credentials associated with the application.

Type:	PSADKeyCredential[]
Aliases:	KeyCredentials
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-PasswordCredential

The collection of password credentials associated with the application.

Type:	PSADPasswordCredential[]
Aliases:	PasswordCredentials
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-Role

The role that the service principal has over the scope. If no value is provided, Role defaults to the Contributor role.

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Scope

The scope that the service principal has permissions for. If no value is provided, Scope defaults to the current subscription.

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipAssignment

If set, skip creating the default role assignment for the service principal.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-StartDate

The effective start date of the credential usage. The default start date value is today. For an asymmetric type credential, this must be set to on or after the date that the X509 certificate is valid from.

Type:	DateTime
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

Guid

String

PSADApplication

PSADPasswordCredential[]

PSADKeyCredential[]

DateTime

Outputs

PSADServicePrincipal

PSADServicePrincipalWrapper

Notes

Keywords: azure, azurerm, arm, resource, management, manager, resource, group, template, deployment

Related Links

• Remove-AzADServicePrincipal
• Get-AzADServicePrincipal
• New-AzADApplication
• Remove-AzADApplication
• Get-AzADSpCredential
• New-AzADSpCredential
• Remove-AzADSpCredential