Dışarıya aktar (0) Yazdır
Tümünü Genişlet
EN
Bu içerik dilinizde bulunmamaktadır ancak İngilizce sürümüne buradan bakabilirsiniz.

Windows Azure AD Graph Authentication

Updated: January 8, 2013

This topic outlines authentication approaches when consuming Windows Azure AD Graph.

To access Windows Azure AD Graph, clients are required to successfully authenticate to Windows Azure AD Access Control first. Windows Azure AD Access Control issues tokens upon successful authentication. The token is presented by your application to Windows Azure AD Graph.

Windows Azure AD Graph supports two authentication methods: Shared symmetric key, and X.509 client certificates. The method of the authentication is determined when the service principal is created using Office 365 Windows PowerShell cmdlets or scripts.

Service Principal

Service principals are created by using Office 365 Windows PowerShell cmdlets or scripts. Use the New-MsolServicePrincipal cmdlet to create a new service principal. A service principal can be used to represent a Line of Business (LOB) application or an on-premise server in the Microsoft Online directory. For example, Microsoft Exchange, SharePoint and Lync are all represented as service principals in the Microsoft Online directory. Adding a service principal to represent a new application allows that application to authenticate to other services such as Microsoft Office 365. To authenticate with Windows Azure AD Graph, a service principal can use one of two types of authentication: shared Symmetric Key or X.509 Client Certificates. Use the Type parameter of the New-MsolServicePrincipal cmdlet to specify the authentication type of the service principal.

ImportantImportant
To use the New-MsolServicePrincipal command, you must first have the MsOnlineExtended module loaded into your Windows PowerShell workspace. To do this, enter the following command at the Windows PowerShell command prompt: import-module msonlineextended -force

The following command creates a service principal that uses a symmetric key credential.

New-MsolServicePrincipal - -displayname "myapp1" -serviceprincipalnames @("appClass/MyApp9.com") -Type symmetric   -Usage Verify -StartDate 5/17/2012 -EndDate 5/17/2014

You should receive output similar to the following.


The following symmetric key was created as one was not supplied TVk03LrDn+E......VCoJa9Uo=

DisplayName : myapp1
ServicePrincipalNames : {appClass/MyApp9.com}
ObjectId : f459b468.......4972d93ef587
AppPrincipalId : 780ccf0.......69112adadf0
TrustedForDelegation : False
AccountEnabled : True
Addresses : {}
KeyType : Symmetric
KeyId : e5d29102.......06db95e8
StartDate : 4/3/2012 20:57:37
EndDate : 4/3/2013 20:57:37
Usage : Verify

The following commands are taken from a script and create a service principal that uses an X.509 client certificate (asymmetric key credential). An existing X.509 certificate file at c:\temp\contoso.cer is assumed.

import-module MsonlineExtended -force
# this section is used to create a service principal credential using a private certificate (Asymmetric key)
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate
$cer.Import(“C:\temp\contoso.cer”)
$binCert = $cer.GetRawCertData()
$credValue = [System.Convert]::ToBase64String($binCert);
 
# create the service principal using the certificate
New-MsolServicePrincipal -ServicePrincipalNames @("SampleApp/localhost") -DisplayName "Graph Sample App" -Type "Asymmetric" -Value $credValue

For an end-to-end example of how to create a service principal and use it to obtain a token from Windows Azure AD Access Control, see How-To: Authenticate To Windows Azure AD Graph Using Windows Azure AD Access Control.

Symmetric Key vs. X.509 Client Certificates

The credential type of a service principal can be set either to asymmetric or symmetric in the Type parameter of the New-MsolServicePrincipal cmdlet. The default setting is symmetric. If the setting is asymmetric, the Value parameter must be set to the public portion of a Base64 encoded X.509 certificate. If the setting is symmetric, a 256-bit AES symmetric key will be generated if the Value parameter is not set.

noteNote
Be sure to note the symmetric key credential that is created for you as output of the cmdlet if you do not supply a value. Once the service principal has been created, you cannot retrieve the symmetric key credential. You will need to use it in your code when authenticating to Windows Azure AD Access Control.

ImportantImportant
Remember, both symmetric key and client certificate credentials should be adequately protected. Failure to protect these credentials can lead to potential unauthorized access to the tenant’s directory information.

Revoking Access for a Service Principal

Use either of the following methods to revoke directory access from Service Principal:

  • Method 1: Remove the service principal.

    remove-MsolServicePrincipal -AppPrincipalId 700ab80d...c90eb
    
  • Method 2: Disable the service principal.

    Set-MsolServicePrincipal -AccountEnabled $false -ObjectId 700ab80d...c90eb
    
    

Adding a Service Principal to a Role

To access and perform operations on Windows Azure AD entities, the service principal must be a member of an appropriate Windows Azure AD tenant administrator role. To learn more about these roles and how they control access to directory entities, see Windows Azure AD Graph and Role-Based Access Control. For step-by-step instructions on managing tenant roles for a service principal, see How-To: Manage Role-Based Access Control When Using Windows Azure AD Graph.

See Also

Show:
© 2014 Microsoft