diff --git a/src/Resources/Resources/help/New-AzADServicePrincipal.md b/src/Resources/Resources/help/New-AzADServicePrincipal.md index 545a68656cfd..612aae53f37f 100644 --- a/src/Resources/Resources/help/New-AzADServicePrincipal.md +++ b/src/Resources/Resources/help/New-AzADServicePrincipal.md @@ -9,11 +9,12 @@ schema: 2.0.0 # New-AzADServicePrincipal ## SYNOPSIS -Creates a new azure active directory service principal. +Creates a new Azure active directory service principal. ## SYNTAX ### SimpleParameterSet (Default) + ``` New-AzADServicePrincipal [-ApplicationId ] [-DisplayName ] [-StartDate ] [-EndDate ] [-Scope ] [-Role ] [-SkipAssignment] @@ -21,222 +22,279 @@ New-AzADServicePrincipal [-ApplicationId ] [-DisplayName ] [-Start ``` ### ApplicationWithoutCredentialParameterSet + ``` New-AzADServicePrincipal -ApplicationId [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationWithPasswordPlainParameterSet + ``` New-AzADServicePrincipal -ApplicationId [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationWithPasswordCredentialParameterSet + ``` New-AzADServicePrincipal -ApplicationId -PasswordCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationWithKeyPlainParameterSet + ``` New-AzADServicePrincipal -ApplicationId -CertValue [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationWithKeyCredentialParameterSet + ``` New-AzADServicePrincipal -ApplicationId -KeyCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### DisplayNameWithoutCredentialParameterSet + ``` New-AzADServicePrincipal -DisplayName [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### DisplayNameWithPasswordPlainParameterSet + ``` New-AzADServicePrincipal -DisplayName [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### DisplayNameWithPasswordCredentialParameterSet + ``` New-AzADServicePrincipal -DisplayName -PasswordCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### DisplayNameWithKeyPlainParameterSet + ``` New-AzADServicePrincipal -DisplayName -CertValue [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### DisplayNameWithKeyCredentialParameterSet + ``` New-AzADServicePrincipal -DisplayName -KeyCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationObjectWithPasswordPlainParameterSet + ``` New-AzADServicePrincipal -ApplicationObject [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationObjectWithPasswordCredentialParameterSet + ``` New-AzADServicePrincipal -ApplicationObject -PasswordCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationObjectWithKeyPlainParameterSet + ``` New-AzADServicePrincipal -ApplicationObject -CertValue [-StartDate ] [-EndDate ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### ApplicationObjectWithKeyCredentialParameterSet + ``` New-AzADServicePrincipal -ApplicationObject -KeyCredential [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ## 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. + +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 [Set-AzADApplication](./get-azadapplication.md) cmdlet. ## EXAMPLES -### Example 1 - Simple AD service principal creation +### 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. + +```powershell +New-AzADServicePrincipal ``` -PS C:\> New-AzADServicePrincipal +```Output 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 +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://azure-powershell-05-22-2018-18-23-43} +ApplicationId : 00000000-0000-0000-0000-000000000000 DisplayName : azure-powershell-05-22-2018-18-23-43 -Id : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy +Id : 00000000-0000-0000-0000-000000000000 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 -### 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. +```powershell +New-AzADServicePrincipal -Role Reader ``` -PS C:\> New-AzADServicePrincipal -Role Reader +```Output 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 +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://azure-powershell-05-22-2018-18-23-43} +ApplicationId : 00000000-0000-0000-0000-000000000000 DisplayName : azure-powershell-05-22-2018-18-23-43 -Id : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy +Id : 00000000-0000-0000-0000-000000000000 Type : ServicePrincipal -WARNING: Assigning role 'Reader' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz' to the new service principal. +WARNING: Assigning role 'Reader' over scope '/subscriptions/00000000-0000-0000-0000-000000000000' 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 -### 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. +```powershell +New-AzADServicePrincipal -Scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup ``` -PS C:\> New-AzADServicePrincipal -Scope /subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup +```Output 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 +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://azure-powershell-05-22-2018-18-23-43} +ApplicationId : 00000000-0000-0000-0000-000000000000 DisplayName : azure-powershell-05-22-2018-18-23-43 -Id : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy +Id : 00000000-0000-0000-0000-000000000000 Type : ServicePrincipal -WARNING: Assigning role 'Contributor' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup' to the new service principal. +WARNING: Assigning role 'Contributor' over scope '/subscriptions/00000000-0000-0000-0000-000000000000/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 -### 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. +```powershell +New-AzADServicePrincipal -Role Reader -Scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup ``` -PS C:\> New-AzADServicePrincipal -Role Reader -Scope /subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup +```Output 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 +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://azure-powershell-05-22-2018-18-23-43} +ApplicationId : 00000000-0000-0000-0000-000000000000 DisplayName : azure-powershell-05-22-2018-18-23-43 -Id : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy +Id : 00000000-0000-0000-0000-000000000000 Type : ServicePrincipal -WARNING: Assigning role 'Reader' over scope '/subscriptions/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/resourceGroups/myResourceGroup' to the new service principal. +WARNING: Assigning role 'Reader' over scope '/subscriptions/00000000-0000-0000-0000-000000000000/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 -### 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. +```powershell +New-AzADServicePrincipal -ApplicationId 00000000-0000-0000-0000-000000000000 ``` -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 +```Output +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://my-temp-app} +ApplicationId : 00000000-0000-0000-0000-000000000000 DisplayName : my-temp-app -Id : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy +Id : 00000000-0000-0000-0000-000000000000 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 -### 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](./get-azadapplication.md) +cmdlet. The results are piped to the `New-AzADServicePrincipal` cmdlet to create a new AD service +principal for that application. -``` -PS C:\> Get-AzADApplication -ObjectId 3ede3c26-b443-4e0b-9efc-b05e68338dc3 | New-AzADServicePrincipal +```powershell +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. +### Example 7: Create a new AD service principal using DisplayName and password credential -### 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. +```powershell +$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 ``` -PS C:\> $credentials = New-Object -TypeName Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{ StartDate=Get-Date; EndDate=Get-Date -Year 2024; Password="StrongPassworld!23"} -PS C:\> $sp = New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials -ServicePrincipalNames : {exxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxc, http://ServicePrincipalName} -ApplicationId : exxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxcc +```Output +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://ServicePrincipalName} +ApplicationId : 00000000-0000-0000-0000-000000000000c ObjectType : ServicePrincipal DisplayName : ServicePrincipalName -Id : 6xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxb +Id : 00000000-0000-0000-0000-000000000000 Type : ``` -Creates a new application with name "ServicePrincipalName" and password "StrongPassworld!23" and creates the service principal based on the application just created. The start date and end date are added to password credential. +### Example 8: Create a new AD service principal using DisplayName and plain key credential -### 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. +```powershell +$cert = 'public certificate as Base64 encoded string' +$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert -EndDate '2021-01-01' ``` -PS C:\> $cert = -PS C:\> $sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert -EndDate "2021-01-01" -ServicePrincipalNames : {cxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx6, http://ServicePrincipalName} -ApplicationId : cxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx6 +```Output +ServicePrincipalNames : {00000000-0000-0000-0000-000000000000, http://ServicePrincipalName} +ApplicationId : 00000000-0000-0000-0000-000000000000 ObjectType : ServicePrincipal DisplayName : ServicePrincipalName -Id : cxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxc +Id : 00000000-0000-0000-0000-000000000000 Type : ``` -Creates a new application with name "ServicePrincipalName" and certifcate "$cert" and creates the service principal based on the application just created. The end date is added to key credential. - ## 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. + +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. ```yaml Type: System.Guid @@ -263,6 +321,7 @@ Accept wildcard characters: False ``` ### -ApplicationObject + The object representing the application for which the service principal is created. ```yaml @@ -278,8 +337,8 @@ Accept wildcard characters: False ``` ### -CertValue -The value of the "asymmetric" credential type. -It represents the base 64 encoded certificate. + +The value of the asymmetric credential type. It represents the Base64 encoded certificate. ```yaml Type: System.String @@ -306,7 +365,8 @@ Accept wildcard characters: False ``` ### -DefaultProfile -The credentials, account, tenant, and subscription used for communication with azure + +The credentials, account, tenant, and subscription used for communication with Azure. ```yaml Type: Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer @@ -321,7 +381,10 @@ 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. + +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. ```yaml Type: System.String @@ -348,9 +411,10 @@ 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. + +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. ```yaml Type: System.DateTime @@ -377,6 +441,7 @@ Accept wildcard characters: False ``` ### -KeyCredential + The collection of key credentials associated with the application. ```yaml @@ -404,6 +469,7 @@ Accept wildcard characters: False ``` ### -PasswordCredential + The collection of password credentials associated with the application. ```yaml @@ -431,7 +497,9 @@ 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. + +The role that the service principal has over the scope. If no value is provided, **Role** defaults +to the **Contributor** role. ```yaml Type: System.String @@ -446,7 +514,9 @@ 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. + +The scope that the service principal has permissions for. If no value is provided, **Scope** +defaults to the current subscription. ```yaml Type: System.String @@ -461,7 +531,8 @@ Accept wildcard characters: False ``` ### -SkipAssignment -If set, will skip creating the default role assignment for the service principal. + +If set, skip creating the default role assignment for the service principal. ```yaml Type: System.Management.Automation.SwitchParameter @@ -476,9 +547,10 @@ 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. + +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. ```yaml Type: System.DateTime @@ -505,6 +577,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -520,8 +593,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -536,7 +609,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -559,6 +636,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### Microsoft.Azure.Commands.Resources.Models.Authorization.PSADServicePrincipalWrapper ## NOTES + Keywords: azure, azurerm, arm, resource, management, manager, resource, group, template, deployment ## RELATED LINKS @@ -576,4 +654,3 @@ Keywords: azure, azurerm, arm, resource, management, manager, resource, group, t [New-AzADSpCredential](./New-AzADSpCredential.md) [Remove-AzADSpCredential](./Remove-AzADSpCredential.md) -