New-MsolServicePrincipal
Adds a service principal to Azure Active Directory.
Syntax
New-MsolServicePrincipal
[-ServicePrincipalNames <String[]>]
[-AppPrincipalId <Guid>]
-DisplayName <String>
[-AccountEnabled <Boolean>]
[-Addresses <RedirectUri[]>]
[-Type <ServicePrincipalCredentialType>]
[-Value <String>]
[-StartDate <DateTime>]
[-EndDate <DateTime>]
[-Usage <ServicePrincipalCredentialUsage>]
[-TenantId <Guid>]
[<CommonParameters>] Description
The New-MsolServicePrincipal cmdlet creates a service principal that can be used to represent a Line Of Business (LOB) application or an on-premises server such as Microsoft Exchange, SharePoint or Lync in Microsoft Azure Active Directory as service principal objects. Adding a new application as a service principal allows that application to authenticate to other services such as Microsoft Office 365.
Examples
Example 1: Create a service principal
PS C:\> New-MsolServicePrincipal -ServicePrincipalNames @("MyApp/myApp.com") -DisplayName "My Application"This command creates a service principal. In this example, the service principal is created with the service principal name MyApp/myApp.com, the display name My Application, and will use an auto-generated 256 bit symmetric key to verify the application. This key will be valid for a year from today.
Example 2: Create a service principal that uses an X509 certificate
PS C:\> $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate
PS C:\> $cer.Import("C:\temp\myapp.cer")
PS C:\> $binCert = $cer.GetRawCertData()
PS C:\> $credValue = [System.Convert]::ToBase64String($binCert);
PS C:\> New-MsolServicePrincipal -ServicePrincipalNames @("MyApp/myApp.com") -DisplayName "My Application" -Type asymmetric -Value $credValueThis example creates a service principal. In this example, the service principal is created with the service principal name MyApp/myApp.com, the display name My Application, and uses the supplied X509 certificate myapp.cer that is configured with a base 64 encoded asymmetric key.
Parameters
-AccountEnabled
Specifies whether the account needs to be enabled. The default value is $True.
| Type: | Boolean |
| Position: | Named |
| Default value: | True |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Addresses
Specifies the of addresses used by the application. Use the New-MsolServicePrincipalAddresses cmdlet to help create the Addresses list object.
| Type: | RedirectUri[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-AppPrincipalId
Specifies the unique application ID for a service principal in a tenant. Once created, this property cannot be changed. If you do not specify this parameter, the application ID is generated.
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-DisplayName
Specifies a display name of the service principal.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-EndDate
Specifies the effective end date of the credential usage. The default end date value is one year from today.
| Type: | DateTime |
| Position: | Named |
| Default value: | Today + 1 year |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ServicePrincipalNames
A list of service principal names (SPNs) associated with the service principal.
An SPN must be unique per company tenant and is used by an application to uniquely identify itself. By default, the service principal AppID is always added as an SPN. An SPN must use one of the following formats:
appNameappName/hostname- a valid URL
AppName represents the name of the application and hostname represents the URI authority for the application. When the service principal represents a WS-Federation relying party, an SPN can be set to a URL that would be treated as the WS-Federation wtrealm parameter.
| Type: | String[] |
| Position: | Named |
| Default value: | AppId of the service principal |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-StartDate
Specifies the effective start date of the credential usage. The default start date value is today.
| Type: | DateTime |
| Position: | Named |
| Default value: | Today |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-TenantId
Specifies the unique ID of the tenant on which to perform the operation. The default value is the tenant of the current user. This parameter applies only to partner users.
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Type
Specifies the type of credential to use. Valid values are: asymmetric, symmetric, and password.
- If asymmetric, the Value parameter must be set to the public portion of a base 64 encoded X509 certificate.
- If symmetric, a 256 bit AES symmetric key will be generated if Value is not set.
- If password, the Value parameter must be specified and it should not be base 64 encoded.
The default setting is "symmetric".
| Type: | ServicePrincipalCredentialType |
| Position: | Named |
| Default value: | Symmetric |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Usage
Specifies the usage of the credential key. The credential key usage can either be set to sign or verify a token. The default setting is verify.
Sign is allowed ONLY for symmetric keys. Verify is allowed for all key types.
A verify credential key is required by Azure Active Directory to verify that the request token was sent by your application, represented by this service principal. Your application may optionally require that Azure Active Directory issue tokens to your application signed by using your signing key rather than the asymmetric public key identifying Azure Active Directory. In this case, provide a sign credential key for your service principal.
| Type: | ServicePrincipalCredentialUsage |
| Position: | Named |
| Default value: | Verify |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Value
Specifies the value of the credential.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Outputs
Microsoft.Online.Administration.ServicePrincipalExtended
This cmdlet returns the service principal that it added. This includes the following information:
- ObjectId. The unique identifier of the service principal.
- AppPrincipalId. The application identifier of the service principal.
- DisplayName. The friendly name of the service principal.
- ServicePrincipalName. The list of service principal names (SPNs) associated with the service principal.
- TrustedForDelegation. The value indicating if the service principal is allowed for delegation.
- AccountEnabled. The value indicating if the account is enabled.
It also retrieves the list of credentials that were added. Each credential object contains the following information:
- Type. The type of service principal credential (Asymmetric/Symmetric/Other).
- Value. The value of the credential. If the credential type is certificate, this represents the base 64 encoded certificate. If credential type is symmetric, it represents an AES key.
- KeyGroupId. The identifier reserved for internal use.
- KeyId. The unique identifier of the key.
- StartDate. The effective start date of the credential usage.
- EndDate. The effective end date of the credential usage.
- Usage. Specifies if the credential is used to sign or verify a token.