SSO with Azure AD OpenID Connect

This document describes the basic set of steps required to get started with onboarding your app to AAD
using OpenID Connect.

1 Signup for a Free Azure Subscription

To sign up, go to https://account.windowsazure.com/organization and follow the sign up steps.   This will
create a new AAD tenant and an organizational account for administering the tenant.  You will be asked
for a credit card, but the card will only be charged if you use resources in Azure that aren’t free.  Your
Azure AD tenant is free.

2 Register Your App

The instructions need a couple updates, so I’m going to provide the latest inline:
1. Click on the Active Directory Tab (from the tabs running down the left)
2. In the Directory top heading, and click on the name of your directory to manage it
3. Click on the Applications top heading
4. Click Add button in the bottom toolbar

5. A light box wizard will come up - choose the Add an app my organization is developing option

6. Name your app and choose Web application and/or Web API as the Type, and click the next
arrow
 7. Choose a sign-in URL and App ID URL for the app, and click the check button on the bottom right
to complete the creation

8. Go to the Configure heading and copy your clientID to use within the app for calling AAD

3 Develop Your App

We conform to the OpenID Connect core spec, and that’s a great place to start on how to integrate.  We
have detailed OAuth2 documentation and OpenID Connect overview documentation.  We’re still working
on our detailed OpenID Connect documentation on MSDN – in the meantime the overview calls out
notable parameters for AAD’s implementation.  All of the AAD specific endpoint / keys may be found
from our JSON metadata doc here: https://login.windows.net/common/.well-known/openid-
configuration.  For your first app, you can get started by including the following parameters to the
endpoint at https://login.windows.net/common/oauth2/authorize.

Authorize Example Notes

Parameter
response_type id_token Can be code, id_token, or code+id_token depending on
your preference for protocol flow. Details on these
flows may be found in the OpenID Connect core spec
here.
clientid 5D9EDFE5-6047-4A3F- This is the clientID from step 8 above in Register Your
B12F-E1C2F02227E9 App.
scope openid The openid value is required by the standard.
nonce 393B61FA-8CC3-4C52- This is a random GUID used for preventing some
A167-472AE18FE934 classes of attack. Correct processing is described here.
response_mode form_post This is used to receive an HTTP POST at your app. You
can also choose to receive a URI fragment response by
omitting the parameter or using the value fragment.
redirect_uri https%3a%2f%2fyourapp This is the URL to which you want the user to return
after signing in.

Here is an example OpenID Connect Authorize request for the Azure management portal:
https://login.windows.net/common/oauth2/authorize?
response_type=code+id_token&client_id=00000013-0000-0000-c000-
000000000000&scope=openid&nonce=7477cb26-7cc2-4f1a-a491-
d895eaad868f&response_mode=form_post&redirect_uri=https%3a%2f%2fmanage.windowsazure.com
%2f

The token endpoint requests / responses are described in detail in the existing AAD OAuth2
documentation.

4 Test Your App

You can do some initialize functional verification within your tenant without any further action.  To try to
sign-in to your app from a user in another tenant though, you will need to enable your app to be multi-
tenanted.  To do this, the app ID URL must contain a DNS name that you own.  To prove ownership of
your domain in your AAD tenant, follow the instructions here.  Once that is complete, go to the configure
tab of your app registration in AAD (from step 8 from Register Your App above) and enable your app for
multi-tenant usage.

5 Publish Your App in the AAD App Gallery

To get published in the Azure AD app gallery so admins can discover your app, contact
waadpartners@microsoft.com (the format for the mail is embedded in the link).  We’ll guide you through
the remaining steps.