New-AzADServicePrincipal

Module:
Az.Resources

Creates a new azure active directory service principal.

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>
   [-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 the user does not provide one for them. For more information on the default values used, please see the description for the given parameters below. This cmdlet has the ability to assign a role to the service principal with the Role and Scope parameters; if neither of these parameters are provided, no role will be assigned to the service principal. The default values for the Role and Scope parameters are "Contributor" and the current subscription, respectively (note: the defaults are only used when the user provides a value for one of the two parameters, but not the other). The cmdlet also implicitly creates an application and sets its properties (if the ApplicationId is not provided). In order to update the application specific parameters please use Set-AzADApplication cmdlet.

Warning

When you create a service principal using the New-AzADServicePrincipal command, the output includes credentials that you must protect. Be sure that you do not include these credentials in your code or check the credentials into your source control. 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

PS C:\> New-AzADServicePrincipal

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://azure-powershell-05-22-2018-18-23-43}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Type                  : ServicePrincipal

The above command creates an AD service principal using default values for parameters not provided. Since an application id was not provided, an application was created for the service principal. Since no values were provided for Role or Scope, the created service principal does not have any permissions.

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

PS C:\> New-AzADServicePrincipal -Role Reader

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://azure-powershell-05-22-2018-18-23-43}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Type                  : ServicePrincipal

WARNING: Assigning role 'Reader' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz' to the new service principal.

The above command creates an AD service principal using the default values for parameters not provided. Since the application id was not provided, an application was created for the service principal. The service principal was created with "Reader" permissions over the current subscription (since no value was provided for the Scope parameter).

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

PS C:\> New-AzADServicePrincipal -Scope /subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://azure-powershell-05-22-2018-18-23-43}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Type                  : ServicePrincipal

WARNING: Assigning role 'Contributor' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup' to the new service principal.

The above command creates an AD service principal using the default values for parameters not provided. Since the application id was not provided, an application was created for the service principal. The service principal was created with "Contributor" permissions (since no value was provided for the Role parameter) over the provided resource group scope.

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

PS C:\> New-AzADServicePrincipal -Role Reader -Scope /subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://azure-powershell-05-22-2018-18-23-43}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DisplayName           : azure-powershell-05-22-2018-18-23-43
Id                    : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Type                  : ServicePrincipal

WARNING: Assigning role 'Reader' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup' to the new service principal.

The above command creates an AD service principal using the default values for parameters not provided. Since the application id was not provided, an application was created for the service principal. The service principal was created with "Reader" permissions over the provided resource group scope.

Example 5 - Create a new AD service principal using application id with role assignment

PS C:\> New-AzADServicePrincipal -ApplicationId 34a28ad2-dec4-4a41-bc3b-d22ddf90000e

ServicePrincipalNames : {34a28ad2-dec4-4a41-bc3b-d22ddf90000e, http://my-temp-app}
ApplicationId         : 34a28ad2-dec4-4a41-bc3b-d22ddf90000e
DisplayName           : my-temp-app
Id                    : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Type                  : ServicePrincipal

Creates a new AD service principal for the application with application id '34a28ad2-dec4-4a41-bc3b-d22ddf90000e'. Since no values were provided for Role or Scope, the created service principal does not have any permissions.

Example 6 - Create a new AD service principal using piping

PS C:\> Get-AzADApplication -ObjectId 3ede3c26-b443-4e0b-9efc-b05e68338dc3 | New-AzADServicePrincipal

Gets the application with object id '3ede3c26-b443-4e0b-9efc-b05e68338dc3' and pipes that to the New-AzADServicePrincipal cmdlet to create a new AD service principal for that application.

Parameters

-ApplicationId

The unique application id for a service principal in a tenant. Once created this property cannot be changed. If an application id is not specified, one will be generated.

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:Microsoft.Azure.Commands.ActiveDirectory.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 base 64 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:Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.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:Microsoft.Azure.Commands.ActiveDirectory.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:Microsoft.Azure.Commands.ActiveDirectory.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 a value for Scope is provided, but no value is provided for Role, then Role will default 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 on. If a value for Role is provided, but no value is provided for Scope, then Scope will default to the current subscription.

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

If set, will 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

Microsoft.Azure.Commands.ActiveDirectory.PSADApplication

Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential[]

Microsoft.Azure.Commands.ActiveDirectory.PSADKeyCredential[]

DateTime

Outputs

Microsoft.Azure.Commands.ActiveDirectory.PSADServicePrincipal

Microsoft.Azure.Commands.Resources.Models.Authorization.PSADServicePrincipalWrapper

Notes

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