IT Connect
Your connection to information technology at the UW

Azure AD Application Integration Guide

This page is your starting place for integrating an application with the UW Azure AD. This page contains links to related pages which will assist you with the integration process, as well as guidelines to help you determine if integrating with Azure AD is the right choice.

NOTE: This page is incomplete. Content is expected to be finished by 1/18/2022.

Azure AD Application Integration Guide topics

Expected Complexity based on scenario

Integrating a web application with Azure AD can be very simple, slightly involved, or complex depending on the scenario. This guide covers most of the possibilities to to be comprehensive but for that reason it can appear very daunting. Here are some reasonable guidelines about the difficulty level, depending on your scenario:

I have… Expected difficulty level
Vendor provided web application which has an Azure AD application gallery template Easy
Web application which uses SAML Easy
Web application which uses OpenID Intermediate
Web application which uses OpenID & OAuth2 Complex
Native or mobile app which uses OpenID Intermediate
Native or mobile app which uses OpenID & OAuth2 Complex
Any scenario which involves SCIM based user provisioning Complex

As with all tasks, experience makes a difference, and what may be easy for one person may be difficult for another. In all cases, UW-IT is happy to assist, so feel free to reach out.

Picking the right identity provider integration solution

Web applications can be integrated with UW NetIDs and the UW Groups service via a variety of methods, including Azure AD. In the past, UW-IT has generally recommended using UW Shibboleth for web application integration. Azure AD is now also generally recommended. 

Guide to which UW Identity Provider your web application should prefer:

Web app … UW Azure AD UW Shibboleth
requires use of SAML or OIDC

X

X

requires use of WS-Federation or WS-Trust protocols

X

requires the OAuth protocol

X

requires integration with Office 365 or other Azure AD apps

X

requires user provisioning via the SCIM protocol

X

has an Azure AD application gallery template

X

requires support team access to app sign in logs

X

requires custom terms of use

X

requires Research and Scholarship category support

X

requires custom IdP metadata

X

requires multilateral SAML federation

X

requires support for social identities such as Facebook

X

requires broadest possible set of identity providers

X

requires better user experience via sign in only when required

X

requires group claims for member-private groups

X

requires claims involving confidential data

X

requires simple conditional access controls such as:

-group membership
-IP address

X

X

requires advanced conditional access controls including:

-location (IP, GeoRegion, or GPS)

-device platform

-client application

-client device state

-sign in risk

-application specific restrictions

X

requires stronger fraud protections such as:

-behavior analytics to flag risky signs in such as: atypical travel, unknown/suspect locations, patterns matching known compromised account signatures

-detection of publicly leaked credentials

-high volume of daily security signals

X

Overview of the process

The process of integrating a web application varies greatly depending on the specific application. There are two cases in general:

  • Vendor provided applications such as Software as a Service (SaaS) which advertise that they are pre-integrated with Azure AD. In this case, there should be an entry in the Azure AD application gallery templates, and the steps are documented in detail. You’ll need UW-IT assistance to get started, but you’ll be able to do most of the basic integration yourself.
  • Applications which you have written, applications which advertise that you can integrate them with Azure AD (i.e. not “pre-integrated”), or applications that generally support SAML, OIDC, or OAuth 2.0 protocols but which don’t make explicit mention of Azure AD. You usually can do the entire integration process yourself without UW-IT assistance, but in some cases you may need UW-IT assistance.

In general, these are the steps taken:

  1. Create Azure AD application (and possible service principal) object (may require UW-IT)
  2. Configure application basics & verify connectivity
    1. Client identifier
    2. Credentials
    3. Metadata
    4. Owners
  3. Add optional application configurations based on your specific requirements
    1. Optional: Configure SAML claims
    2. Optional: Configure OAuth scopes (requires UW-IT)
    3. Optional: Configure OAuth consent (may require UW-IT)
    4. Optional: Configure SCIM user provisioning (may require UW-IT)
    5. Optional: Configure Conditional Access (requires UW-IT)
  4. Verify desired functionality
  5. Assign users to the Azure AD application either via group (preferred) or by user
  6. Release

Azure AD Application Terminology

Microsoft has a few terms which can be a bit confusing if you don’t understand what they mean:

  • Azure AD Application: an identity intended to be used by an application with a bit of configuration about how that identity can be used. The fact that Azure is in the name does not designate where the software lives but that the application will only trust sign on tokens issued by Azure AD. The fact that application is in the name does not imply that this is a software platform for development or hosting.
  • Application object: This is the single, definitive object with configuration details, and is only present in one Azure AD tenant. Think of it as the template by which many instances of this application might be created from.
  • Service Principal object: This is a working instance of the application. This object will contain operational configuration information specific to this instance of the application and is linked to the application object.
  • Enterprise application: This is a location in the Azure Portal where you can manage service principals. It is also the only location from which pre-integrated 3rd party SaaS applications in the Azure AD application gallery can be created (the application object does not exist in the UW tenant). The creation of service principals from this location can only be done by UW-IT.
  • App registration: This is a location in the Azure Portal, where you can create and manage application objects (in the UW tenant). Anyone with a UW Microsoft account can create an application object, and a service principal is automatically created at the same time.

Azure AD Application Concepts

Most of the content here is also represented at https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-how-applications-are-added. Because everyone learns information slightly differently, you may find one or the other easier to understand.

  1. There are many meanings of the word “application.” When we talk about an Azure AD Application, we are talking about something very specific. An Azure AD Application is a digital identity and some associated configuration which informs Azure AD about how to treat software which uses that digital identity. The software itself may be running anywhere, on any platform, written in any language. To be more specific, if software needs to request Azure AD logon tokens or consume Azure AD logon tokens, then it must be an Azure AD application. The software might have other digital identities it uses, but that topic isn’t covered here.
  2. An Azure AD application is represented by two types of objects in Azure AD:
    1. An object of type application. This is the core digital identity with the basic required configuration details, and is only present in the AAD application’s home tenant.
    2. One or more objects of type service principal. This object will be present in each tenant which has an instantiation of the AAD application, except the AAD application’s home tenant. This object will have the specific role assignments and user consent permissions granted for that tenant.
      Note: An AAD application’s instantiation in a given tenant is the service principal object–but that service principal references the “primary” AAD object of type application that lives in one and only one tenant. You can read more about these AAD objects here.
  3. All Azure AD applications involve consent of some kind. There are generally two kinds of consent:
    1. User consent. The end user is presented with a list of permissions the AAD application would like, if you agree to grant them. If the user does not consent, then they can not use the application.
    2. Admin consent. The tenant admin is presented with a list of permissions the AAD application would like. Admin consent is required if the required application permissions are broader in scope than what an individual user can grant for themselves. If admin consent is required, then no user can use the application until admin consent. Optionally a tenant admin can provide the user consent decision on behalf of all users. In this case, the end user never sees the user consent dialog.
    3. An AAD application instance will record all consent permissions granted within that tenant related to itself (on the service principal object).
  4. Azure AD Applications come in two fundamental flavors–confidential clients and public clients. Confidential clients need to authenticate as themselves, so must have credentials–these are typically web apps or code used to programmatically leverage the API of another AAD application. Public clients do not need to authenticate as themselves and typically represent native clients broadly distributed on many devices. So the key differentiator here is whether the application needs to get a logon token for itself–and that is usually dependent on whether it needs to access another Azure AD application. Most Azure AD Apps will be confidential clients. Note: public clients do not have a service principal in each tenant–they are only ever present in the developer’s tenant. If you’d like to explore public clients further, you might review the ‘Native Application to Web API’ section of https://azure.microsoft.com/en-us/documentation/articles/active-directory-authentication-scenarios/.
  5. If an Azure AD Application needs a credential, then it has two options–a password or a cert. See more here.
  6. An Azure AD application may define whether it is available to other tenants.
  7. An Azure AD application must define what permissions to other AAD applications it needs. To only authenticate other users, you do not need any permission, but if you need to include name or other basic data in the user experience, then you will likely need User.Read, i.e. the ability to read the profile of an Azure AD user who has logged into your application. You can read more about permission scopes, including the permission scopes that Azure AD itself has available at https://msdn.microsoft.com/Library/Azure/Ad/Graph/howto/azure-ad-graph-api-permission-scopes.
  8. An AAD application may define permission scopes that can be granted to other AAD applications. This is optional.
  9. AAD application assignments
    1. Each app may define roles which users can be assigned to. This is optional. Each AAD application instance will record any role assignments.
    2. Each AAD application instance may require assignment of users or groups to be able to access to the app. This is optional. Note that if assignment is required, a basic role is created even if the application doesn’t define any roles.
    3. Each app can have owners defined, but they are not represented in the roles property. Application Owners have a broad set of permissions.
  10. An AAD application records the URIs that tokens it requests are issued to. A given AAD application may have many valid URIs. You might imagine using the same AAD application for a production, pre-production, and development instance of the code behind your AAD application, each with their own distinct URI. Or you can create a separate Azure AD application for production, pre-production, and development purposes.

Azure AD Applications: Azure Portal Navigation

Azure AD Application Creation

If your application pre-integrated, it will be listed in the Azure AD application gallery. To proceed, contact UW-IT to get started via help@uw.edu with a subject line of “Azure AD application: X” where X is the name of the application. The application object created via this process will be pre-configured to work correctly. You will supply key information and possibly take actions during the process to achieve the final configuration.

Otherwise, you should be able to create the application object yourself. Microsoft has a guide to this process here: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app.

Azure AD Application Configuration: Intro

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.

NOTE: This page is incomplete. Content is expected to be finished by 1/18/2022.

 

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.

Azure AD Application Configuration: SAML

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.

Azure AD Application Configuration: OIDC and OAuth

For OIDC and OAuth, the platform for your application alters the basic requirements. 

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.

Azure AD Application Configuration: More details

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.

Azure AD Application Configuration: Verify basic connectivity

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.

Azure AD Application Advanced Configuration: Claims

The default SAML claims provided by Azure AD are:

  • givenname
  • surname
  • emailaddress
  • name

If you need more claims, you’ll need to add them. Azure AD sources all data for claims from Azure AD itself. This means the possible claims you can add are restricted to data which is present in UW Azure AD. Azure AD supports a wide variety of data transformations and conditions for claims issuance. 

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization documents the basic process of adding claims, including transformation and condition capabilities.

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-enterprise-app-role-management covers application-specific role-based claims. This allows you to assign a role within your application based on claims data. If you have written your own application, see https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps for a more detailed description.

If you have written your own application, then you have an Azure AD application object, and you may want more control over what claims are provided. You can use the application manifest (e.g. via the Application Registration interface) to do that.  https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims discusses this topic. 

If you need claims which rely on group membership data, we have strong recommendations. When configuring your “Group Claim”, choose the ‘Groups assigned to the application’ option. This will ensure that users who are members of a lot of groups do not get an extremely large access token filled with groups which are not relevant to your application. To make this option work, you only need to assign the relevant groups to your application. See ‘User Assignment’. If you can’t assign all the relevant groups to your application, then use the Advanced options to filter which groups are included in claims for your application. https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims provides detailed information relevant to configuring group claims.

Azure AD Application Advanced Configuration: Scopes

Your application (usually an API) may need to define permissions for the purpose of allowing other applications the ability to leverage OAuth consent to take actions on behalf of another user. This is an advanced topic and we’d recommend you talk with UW-IT about your goals and how to best achieve them. 

https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis#add-a-scope covers the process of creating a hypothetical OAuth scope for an example application. https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-oauth2 covers the process of both setting up a scope and having a 2nd application leverage the scope of the 1st.

https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent is a comprehensive introduction to OAuth scopes which are sometimes called API permissions or OAuth consent.

Azure AD Application Advanced Configuration: Consent

Your application may need to take advantage of well-known OAuth scopes (permissions) that other applications have published as available for use with consent. These can only be added to applications whose application object lives in the UW Azure AD, i.e. application objects which you own. You can add these to the application manifest or via the App Registrations interface’s API permissions screen. Note that scopes which are of type ‘Admin’ will require UW-IT authorization, presuming a valid business need and adequate risk mitigations.

Azure AD Application Advanced Configuration: Provisioning (SCIM)

Azure AD application provisioning refers to automatically creating user identities and roles in the applications that users need access to. In addition to creating user identities, automatic provisioning includes the maintenance and removal of user identities as status or roles change. 

If your application is pre-integrated, it may also support SCIM provisioning. In that case, there will be instructions on how to get it setup. If your application supports SCIM, or you’ve built a SCIM gateway to connect to your legacy application, you can use the Azure AD Provisioning agent to directly connect with your application and automate provisioning and deprovisioning. If you have legacy applications that don’t support SCIM and rely on an LDAP user store or a SQL database, Azure AD can support those as well.

There are a few gotchas:

  • Do not *EVER* choose to provision all users and groups. If you do this, UW-IT will disable your application as soon as we detect this configuration. Choose ‘Sync only assigned users and groups’.
  • Provisioning leverages the assigned users and groups as its data source for what to provision. See ‘User Assignment’
  • Nested groups don’t work well with provisioning; any nested group will not be provisioned nor will any users within that nested group. You’ll need to use groups which do not have any groups as members.
  • If the users being provisioned already exist in the application prior to enabling provisioning, and exist in a different customer’s instance of that SaaS application, then you likely will experience errors which you will have to work with the SaaS vendor to resolve.
  • Only application owners can review the provisioning logs for troubleshooting purposes.

For more information about how to add SCIM support to your application to achieve provisioning, see https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/.

Azure AD Application Advanced Configuration: Conditional Access

Conditional Access (CA) is a powerful feature that allows security controls to be enforced at the time an access token is requested based on a variety of conditions. UW support for Conditional Access is limited at this time. If you feel you need a CA policy, send a request and we’ll consider it.

Conditional Access can lead to significant unexpected impacts, so we have to exercise judicious vetting and practices to prevent undesirable outcomes. Also note that many of the CA conditions possible may not be viable.

A summary of the options is represented in this grid:

Assignments
Users and groups Include | Exclude
Cloud apps Include | Exclude
User actions
Register security information
Conditions
Sign-in risk (AAD Identity Protection, via AAD P2) High | Medium | Low | No risk
Note: Typical risks are atypical travel, unusual login, malware linked ip, leaked creds, known attack pattern
Device platforms Include | Exclude
Locations Include | Exclude
Client apps Browser | Mobile apps and desktop clients | Modern authentication clients | Exchange ActiveSync clients | Other clients
Device State Include | Exclude, where {Device Hybrid Azure AD joined, Device marked as compliant}
Access controls
Block access
Grant access Require Multi-Factor Authentication
Require device to be marked as compliant
Require Hybrid Azure AD Joined device
Require approved client app
Require app protection policy
Terms of Use
Require one of the selected controls
Require all of the selected controls
Session Use app enforced restrictions
Use Conditional access app control (Cloud App Security, via M365 A5)
Sign-in frequency
Persistent browser session

Conditional Access is an extensive topic, with more information available at https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/overview. Developers may find https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-conditional-access-dev-guide useful.

Last reviewed January 4, 2022