Azure AD Applications: Basic Configuration

Last updated: January 18, 2022

This basic configuration section covers the basic required elements which must be configured for an Azure AD application.

If you are integrating a web application with Azure AD, there are several key pieces of information that are required to get your web application to actually use UW Azure AD. Which information is needed depends on the protocol your web application uses, but there are some general pieces of information that are useful across all of them.

Azure AD Application Basic Configuration topics

 

What information a given application will need can vary, however, there are a couple pieces of information which are almost always useful.

Tenant ID

You may be asked to supply your tenant ID — this can sometimes be called the Azure AD tenant ID, Office 365 tenant ID, or Microsoft 365 tenant ID. All of these names mean the same thing. 

Tenant ID: f6b6dd5b-f02f-441a-99a0-162ac5060bd2

Endpoints

Modern web applications integrate via one or more endpoints that an identity provider supplies, each of which supports a specific protocol and has different expected authentication flows associated with it.

Microsoft identity provider endpoints generally have the following syntax:

  • https://login.microsoftonline.com/{tenant}/{protocol}

Where {tenant} specifies which accounts are allowed and can have one of 5 values:

  • common – any personal Microsoft account or Azure AD account can use your app
  • organizations – any Azure AD account can use your app 
  • consumers – any personal Microsoft account can use your app
  • uwnetid.onmicrosoft.com – only UW Azure AD accounts can use your app
  • f6b6dd5b-f02f-441a-99a0-162ac5060bd2 – This is the UW tenant ID – only UW Azure AD accounts can use your app

Where {protocol} specifies which protocol endpoint and may have additional specifics. The following are the most common:

  • saml2 – The SAML 2 protocol endpoint
  • oauth2/v2.0/authorize – The OIDC endpoint used to obtain an identity token
  • oauth2/v2.0/token – The OAuth2 endpoint used to obtain an access token

More information about Microsoft endpoint URLs can be found at https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-client-application-configuration.

For SAML, you’ll likely need:

  • Identifier or entityId: This is a globally unique identifier for your application, usually a URL. You supply this value on the Azure AD service principal.
  • Reply URL: This is the URL for your application, i.e. where a user is redirected to when they have successfully gotten an Azure AD token. You supply this value on the Azure AD service principal.
  • Sign on URL: This is also the URL for your application. SAML authentication can be initiated by your application or by the identity provider, and if initiated by the identity provider, then this is the URL used. If initiated by the application, then the Reply URL is used. Generally, these two values (and the entityID) are all identical.
  • Application identifier (AppId): This is a globally unique identifier, provided by Azure AD on the service principal object that is created. Your software may need you to supply this info to its configuration, but usually this is optional. This value is embedded in the Metadata URL (covered below)
  • Metadata URL: This URL contains most of the key information for your application to work properly with Azure AD and is specific to your application. In general, this is: https://login.microsoftonline.com/f6b6dd5b-f02f-441a-99a0-162ac5060bd2/federationmetadata/2007-06/federationmetadata.xml?appid={Your appId}

where you supply the appId specific to the Azure AD service principal.

For example: https://login.microsoftonline.com/f6b6dd5b-f02f-441a-99a0-162ac5060bd2/federationmetadata/2007-06/federationmetadata.xml?appid=dd67ec83-9784-44ca-b640-4efe95399fb8

NOTE: do not use this URL–you need the one specific to your application.

For OIDC and OAuth, the platform for your application alters the basic requirements. If you are using OIDC/OAuth with delegated permissions, you *must* have a Redirect URI–this is the only way a user can get to the code your application identity is using. If you are using OIDC/OAuth with application permissions, the Redirect URI may not be necessary because no human needs to interact with your application identity.

For Web and single-page applications (SPA) you’ll need:

  • Redirect URI: Sometimes also called the Reply URI (as it serves the same purpose as the SAML property by that name). This is the URL for your application, i.e. where a user is redirected to when they have successfully gotten an Azure AD token. You supply this value on the Azure AD service principal.

For iOS/MacOS, you will need:

  • Bundle ID: Your app’s Bundle ID can be found in XCode in the Info.plist or `Build Settings`.

For Android, you will need:

  • Package Name: Your app’s Package Name can be found in the Android Manifest.
  • Signature Hash: The Signature Hash can be generated via command line.

For mobile and native clients, you will need:

In all cases, the Azure AD service principal will need:

  • What type of tokens can be issued:
    • Access tokens (needed for OAuth)
    • ID tokens (needed for OIDC)
  • Supported account types:
    • Single tenant (UW AAD users only)
    • Multitenant (any AAD user)
  • Allow public client flows: This is needed for most mobile and native clients scenarios and may be needed in other scenarios.

In all cases, the software configuration will need:

  • Application identifier (AppId): This is a globally unique identifier, provided by Azure AD on the service principal object that is created. 
  • Token endpoints: Configured to use these 2 endpoints with the appropriate value of {tenant}:
  • Response_type: Must include “id_token” for OpenID Connect sign-in. It might also include other response_type values, such as code.
  • Scope: At a minimum, you’ll need to include “openid”. If additional OAuth scopes are needed, they will also need to be listed.
  • Nonce: The OpenID/OAuth software usually deals with this, but details included here to be complete. The value typically is a randomized, unique string that can be used to identify the origin of the request & mitigate token replay attacks.

See https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#send-the-sign-in-request for more details on what the OIDC software must send.

Note: OAuth2 supports a variety of access flows. Additional information may be required or recommended for those flows.

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols has a more complete explanation of the required configuration information so if you are confused, it may provide the answers you seek. If you are writing your own application, you may want to review the OIDC flow, OAuth2 flow and SAML flow depending on which protocols you are leveraging.

Once both the Azure AD application and your software has the required information configured, you can test that it works properly. 

For SAML applications, the Single sign-on page has a “Test” button. Click on it to initiate an IdP initiated authentication to your application.

For OIDC applications, there isn’t an automated way to test. You’ll need to verify basic authentication by having your software send a token request and seeing if it gets back a successful response.