Getting Started with Azure Active Directory

Article
10/23/2012

So you’ve heard the rumblings about Azure Active Directory and would like to find out more on what it’s all about. Let’s get you set up with some of the key pieces you’ll need and introduce a few concepts at the same time.

Updated 2/28/2013 to account for the updated AAD PowerShell module (https://aka.ms/aadposh).

Azure Active Directory provides the directory and access control service for Office 365, so if you have an O365 subscription of any sort you already have a corresponding AAD tenancy. If you don’t have one or prefer a different tenancy for testing, sign up for an AAD account here, or a new O365 Enterprise Preview account here.

You can access a Web UI for user management at https://activedirectory.windowsazure.com. Right now the only significant task you can accomplish via the UI is some user management. Managing service principals and identity and authentication configuration requires PowerShell.

Install and Prepare MSOL PowerShell

Azure Active Directory PowerShell was formerly known as Microsoft Online (MSOL) PowerShell, and most cmdlets still use the MSOL prefix. The module requires the Microsoft Online Sign-In Assistant (MSO SIA). You can download the Sign-In Assistant here and the 64-bit PowerShell module here (reference to 32-bit and 64-bit editions of the SIA and AAD module are here).

Note (Feb 28, 2013): The following workaround is no longer necessary with the release of the AAD PowerShell module. You can still delete the MSOnlineExtended folder if you want, but the CmdletsToExport line is now correct by default.

Before you get started with your new cmdlets, you’ll need to work around some problems. AAD PowerShell installs two modules into the PowerShell module directory at C:\windows\system32\windowspowershell\v1.0\modules. These are the MSOnline and MSOnlineExtended modules. At this point, both modules include the exact same DLL; as a result, PowerShell can’t load both modules in the same session at once. The best way to deal with this is as follows:

Throw out the entire MSOnlineExtended module. If it makes you nervous, just move it somewhere else. But I promise you won’t have any issues if you completely delete it. (Note: This is current as of Oct 23, 2012).

Next, open up the MSOnline module folder (in the $pshome\modules directory), and open MSOnline.psd1 somewhere you can edit it. One option is to run this command in the PowerShell ISE (running as Administrator):

PS C:\> psedit $pshome\modules\msonline\msonline.psd1

Find the line for CmdletsToExport and change it to this:

PS C:\> CmdletsToExport = ‘*’

What you’re doing here is specifying that all available cmdlets in MSOL PowerShell DLLs should be exported into your PowerShell sessions via the MSOnline module.

Once you’ve done this, re-open PowerShell and run:

PS C:\> Get-Command -Module MSOnline

If all is well, you’ll see a list of all the Azure AD cmdlets. Look for the MsolServicePrincipal ones in particular.

Connect to AAD

Now we’ll get acquainted with the service principals which initially populate your directory. First, you’ll need to establish the context for your session via the Connect-MsolService cmdlet. Just enter the cmdlet and put in your administrative credentials for your O365/AAD tenancy. In the background, a persistent connection is set up and cached for use with all the MSOL cmdlets you use in your session.

Curious what’s happening behind the scenes here? Open up a Web Proxy Debugger (e.g. Fiddler2), make sure you have set it to decrypt HTTPS connections, and then run the Connect-MsolService cmdlet. You’ll see that a special SOAP request is sent to the BEC Web Service. BEC, or Business Online Services Engineering Core, is Microsoft’s name for the gateway to Azure AD. You’ll occasionally see it turn up in contexts where a connection to AAD is needed, such as in SharePoint 2013 PowerShell (New-SPBecWebServiceApplicationProxy).

Service Principals and Domains

The first cmdlet to run once you’re all connected is Get-MsolServicePrincipal. If you have O365 set up, you’ll see principals for each of the online services, such as Exchange, SharePoint, and Lync. Here’s a list of the principals currently in my AAD domain.

PS C:\> Get-MsolServicePrincipal | ft DisplayName, AppPrincipalId -AutoSize

DisplayName AppPrincipalId
----------- --------------
Microsoft.Lync 00000004-0000-0ff1-ce00-000000000000
Microsoft.Office365Portal 00000006-0000-0ff1-ce00-000000000000
Microsoft.SharePoint 00000003-0000-0ff1-ce00-000000000000
Microsoft.Azure.Workflow 00000005-0000-0000-c000-000000000000
Microsoft.Azure.AnalysisServices 00000009-0000-0000-c000-000000000000
Microsoft.Exchange 00000002-0000-0ff1-ce00-000000000000
Microsoft.ExchangeOnlineProtection 00000007-0000-0ff1-ce00-000000000000
Microsoft.Azure.ActiveDirectory 00000002-0000-0000-c000-000000000000
“Napa” Office 365 Development Tools 48717084-a59c-4306-9dc4-3f618dbecdf9
OnPremApp1 52f3de70-2d75-4187-9c49-138d86e54244
rp.joshgav.com 66b3011d-892c-4cbe-a844-61d87ecdf8f8

Notice the last 3? Those are principals that I’ve added as relying OAuth and WS-Trust parties. The last one is a Relying Party Web Application of mine. I created the principal in AAD and then ran the Identity and Access tool in Visual Studio to federate with Azure AD for single-sign on. More on that another time.

If Service Principals are approximately equivalent to Relying Parties (WS-Federation) and Service Providers (SAML), then Domains are Identity Providers (WS-Fed) and Authentication Authorities (SAML). Run Get-MsolDomain to see all of your AAD domains. If you’ve federated your O365 directory with an On-Prem ADFS STS, you’ll see it listed as a Federated domain here. I’ve federated ‘gavant.org.’

PS C:\> Get-MsolDomain | ft -AutoSize

Name Status Authentication
---- ------ --------------
gavant.org Verified Federated
joshgav1.onmicrosoft.com Verified Managed

If you have a federated domain, run Get-MsolDomainFederationSettings to see how AAD routes authentication requests back to your OnPrem ADFS instance. Here’s my configuration:

PS C:\> Get-MsolDomainFederationSettings -DomainName gavant.org

ActiveLogOnUri : https://fs.joshgav.com/adfs/services/trust/2005/usernamemixed
FederationBrandName : JoshGav ADFS
IssuerUri : https://fs.joshgav.com/adfs/services/trust/
LogOffUri : https://fs.joshgav.com/adfs/ls/
MetadataExchangeUri : https://fs.joshgav.com/adfs/services/trust/mex
NextSigningCertificate :
PassiveLogOnUri : https://fs.joshgav.com/adfs/ls/
SigningCertificate : MIIC2DCCAcCgAwIBAgIQf2RJ+RmnbqhMANBCDJz6ojANBgkqhkiG9w0BAQsFADAoMSYwJAYDVQQDEx1BREZTIFNpZ25pbmcgLSBmcy5qb3NoZ2F2LmNvbTAeFw0xMjEwMDExMzI4MjhaFw0xMzEwMDExMzI4MjhaMCgxJjAkBgNVBAMTHUFERlMgU2lnbmluZyAtIGZzLmpvc2hnYXYuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuZ6zVYGdqKk04lCxbqjZjd+Nhu7GlFhnz1RBWKNevxWPP9bsMR5B/...

More Metadata

We’ve briefly seen Service Principals and Identity Providers. What we’re missing is information about the AAD STS itself. The best way to see more about this is to retrieve the Federation Metadata document and the JSON Metadata document for your AAD realm. Assuming {0} to be a placeholder for your AAD domain name or realm ID, the following URLs will get you the information you need.

WS-Federation	https://accounts.accesscontrol.windows.net/{0}/FederationMetadata/2007-06/FederationMetadata.xml
JSON	https://accounts.accesscontrol.windows.net/{0}/metadata/json/1

I have no idea what standard the JSON information adheres to, but Microsoft uses it here and in other products.

For example, you can retrieve the metadata for my AAD tenant at https://accounts.accesscontrol.windows.net/joshgav1.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml. Go ahead, click it.

Personally, I prefer to use PowerShell:

PS:> $AADDomain = ‘joshgav1.onmicrosoft.com’
PS:> [xml] $Output = (
Invoke-RestMethod `
-Uri (‘https://accounts.accesscontrol.windows.net/{0}/FederationMetadata/2007-06/FederationMetadata.xml’ -f $AADDomain)).SubString(1)

PS:> Invoke-RestMethod -Uri (‘https://accounts.accesscontrol.windows.net/{0}/metadata/json/1’ -f $AADDomain)

The metadata document returned in the first command has an extra character at the beginning, which is why we have the extra SubString(1) method tacked on. Invoke-RestMethod is a very helpful PowerShell cmdlet which converts JSON objects into PowerShell objects automatically, as you can in the last command above.

The metadata you receive is all about the Azure AD Access Control Service. You’ll notice it has a Principal ID of 00000001-0000-0000-c000-000000000000 (which was missing in the list above). The perceptive amongst you will notice that its main endpoint is https://accounts.accesscontrol.windows.net/RealmID, which may remind you of the ACS 2.0 domains. In ACS 2.0, domains are named https://<namespace>.accesscontrol.windows.net. In AAD ACS, the root domain accounts.accesscontrol.windows.net is shared by all tenants.

Summary

In this post we’ve gotten you set up with an AAD account, installed and fixed MSOL PowerShell, and taken a brief tour of AAD service principals, domains, and the AAD Access Control Service itself. Use this knowledge to begin composing and federating domains and identity providers with your AAD tenancy.