Export (0) Print
Expand All
Expand Minimize

New-MsolServicePrincipalCredential

Published: April 18, 2013

Updated: January 21, 2014

Applies To: Office 365, Windows Azure, Windows Intune

noteNote
  • This topic provides online help content for cloud services, such as Windows Intune and Office 365, which rely on Windows Azure Active Directory for identity and directory services.

  • The Windows Azure Active Directory Module for Windows PowerShell 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).

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>]

    -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 
    (http://go.microsoft.com/fwlink/?LinkID=113216).

The following examples illustrate how to use this cmdlet.

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"

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()

This command shows how to register an on-premises Exchange Server so that communications between the Exchange Server and Windows Azure AD services such as Office 365can 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 Office 365 servers are:

  1. Exchange: 00000002-0000-0ff1-ce00-000000000000

  2. SharePoint: 00000003-0000-0ff1-ce00-000000000000

  3. Lync: 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

See Also

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft