New-MsolServicePrincipalCredential
Updated: July 30, 2015
Applies To: Azure, Office 365, Windows Intune
Note
- The cmdlets were previously known as the Microsoft Online Services Module for Windows PowerShell cmdlets.
The New-MsolServicePrincipalCredential cmdlet can be used to add a new credential to a service principal or to add or roll credential keys for an application. The service principal is identified by supplying one of the following: object ID, appPrincipalID, service principal name (SPN).
Syntax
New-MsolServicePrincipalCredential -ObjectId <Guid> [-EndDate <DateTime>] [-StartDate <DateTime>] [-TenantId <Guid>] [-Type <string>] [-Usage <ServicePrincipalCredentialUsage>] [-Value <string>] [<CommonParameters>]
New-MsolServicePrincipalCredential -AppPrincipalId <Guid> [-EndDate <DateTime>] [-StartDate <DateTime>] [-TenantId <Guid>] [-Type <string>] [-Usage <ServicePrincipalCredentialUsage>] [-Value <string>] [<CommonParameters>]
New-MsolServicePrincipalCredential -ServicePrincipalName <string> [-EndDate <DateTime>] [-StartDate <DateTime>] [-TenantId <Guid>] [-Type <string>] [-Usage <ServicePrincipalCredentialUsage>] [-Value <string>] [<CommonParameters>]
Parameters
-AppPrincipalId <Guid>
The application ID associated with the service principal to add the
credential to.
Required? true
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-EndDate <DateTime>
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 until, otherwise an OAuth token will not be issued for this
application.
Required? false
Position? named
Default value Today + 1 year
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-ObjectId <Guid>
The object ID of the service principal to add the credential to.
Required? true
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-ServicePrincipalName <string>
The unique name of the service principal to add the credential to.
An SPN must use one of the following formats "appName" or
"appName/hostname" or be a valid URL. AppName represents the name of
the application and hostname represents the URI authority for the
application.
Required? true
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-StartDate <DateTime>
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, otherwise an OAuth token will not be issued for this application.
Required? false
Position? named
Default value Today
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-TenantId <Guid>
The unique ID of the tenant to perform the operation on. If this is
not provided, then the value will default to the tenant of the current
user. This parameter is only applicable to partner users.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Type <string>
The type of credential used. The credential type can either be set to
"asymmetric", "symmetric" or "password". The default setting is
"symmetric".
Required? false
Position? named
Default value symmetric
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Usage <ServicePrincipalCredentialUsage>
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 the Windows Azure Active
Directory directory to verify that the request token was sent by your
application (represented by this service principal). Your application
may optionally require that Windows Azure Active Directory services
issue tokens to your application signed with your signing key rather
than the asymmetric public key identifying Windows Azure Active
Directory. In this case, provide a "sign" credential key for your
service principal.
Required? false
Position? named
Default value verify
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Value <string>
The value of the credential. If the credential type is set to
"asymmetric", it represents the base 64 encoded certificate. If the
credential type is set to "symmetric" and Value is not set, a 256 bit
AES key will be automatically created and valid for one year from
creation. If the credential type is set to "password", the Value
parameter must be supplied and it should not be base 64 encoded.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information,
see
about_CommonParameters
(https://go.microsoft.com/fwlink/?LinkID=113216).
Examples
The following examples illustrate how to use this cmdlet.
Example 1
This command adds a credential (or a key) object to an existing service principal. In this example, a symmetric key is generated for this credential and added to the service principal using the service principal name value of "MyApp/Contoso.com".
New-MsolServicePrincipalCredential -ServicePrincipalName "MyApp/Contoso.com"
Example 2
The following command adds a credential (or a key) object to an existing service principal. In this example, the supplied base64 encoded public X509 certificate ("myapp.cer") is added to the service principal using the service principal name value of "MyApp/Contoso.com".
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate $cer.Import("C:\myapp.cer")
$binCert = $cer.GetRawCertData()
$credValue = [System.Convert]::ToBase64String($binCert);
New-MsolServicePrincipalCredential -ServicePrincipalName "MyApp/Contoso.com" -Type asymmetric -Value $credValue -StartDate $cer.GetEffectiveDateString() -EndDate $cer.GetExpirationDateString()
Example 3
This command shows how to register an on-premises Exchange Server so that communications between the Exchange Server and services such as can occur. This example assumes that $credValue contains the base64 encoded public X509 certificate used to represent the on-premises Exchange server. The well-known Ids for servers are:
Exchange:
00000002-0000-0ff1-ce00-000000000000SharePoint:
00000003-0000-0ff1-ce00-000000000000Lync:
00000004-0000-0ff1-ce00-000000000000
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate $cer.Import("C:\myapp.cer")
$binCert = $cer.GetRawCertData()
$credValue = [System.Convert]::ToBase64String($binCert);
New-MsolServicePrincipalCredential -AppPrincipalId -Type asymmetric -Value $credValue
Additional Resources
There are several other places you can get more information and help. These include: