Azure AD Application Integration Guide

Last updated: August 11, 2022

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.

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.

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

Azure AD Application Integration Guide topics

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



requires use of WS-Federation or WS-Trust protocols


requires the OAuth protocol


requires integration with Office 365 or other Azure AD apps


requires user provisioning via the SCIM protocol


has an Azure AD application gallery template


requires support team access to app sign in logs


requires custom terms of use


requires Research and Scholarship category support


requires custom IdP metadata


requires multilateral SAML federation


requires support for social identities such as Facebook


requires broadest possible set of identity providers


requires better user experience via sign in only when required


requires group claims for member-private groups


requires claims involving confidential data


requires simple conditional access controls such as:

-group membership
-IP address



requires advanced conditional access controls including:

-location (IP, GeoRegion, or GPS)

-device platform

-client application

-client device state

-sign in risk

-application specific restrictions


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


Gallery Web app w/ SAML Web app w/ OIDC Web app w/ OIDC + OAuth Native app w/ OIDC Native app w/ OIDC + OAuth App w/SCIM
Terminology (plus) (plus) (plus) (plus) (plus) (plus) (plus)
Concepts (plus) (plus) (plus) (plus) (plus) (plus) (plus)
Navigation (plus) (plus) (plus) (plus) (plus) (plus) (plus)
Creation (tick) (tick) (tick) (tick) (tick) (tick)
Config intro (plus) (plus) (plus) (plus) (plus) (plus) (plus)
Config: SAML (tick) (question)
Config: OIDC & OAuth (tick) (tick) (tick) (tick) (question)
Config: More details (question) (question) (question) (question) (question) (question)
Config: Assignment (plus) (plus) (plus) (plus) (tick)
Verify connectivity (question) (plus) (question) (question) (question) (question) (question)
Claims (question) (plus) (question) (question) (question) (question) (question)
Scopes (question) (question) (question) (question)
Consent (question) (question) (question) (question)
Provisioning (question) (question) (question) (question) (question) (question) (tick)
Conditional Access (question) (question) (question) (question) (question) (question) (question)

Symbols reference

(tick) Required
(plus) Recommended
(question) Optional depending on needs
Required, but UW-IT performs

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

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.

Most of the content here is also represented at 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. OAuth permission scopes are one of two kinds: application or delegated.
    1. Application permissions are those which are used solely by the application identity itself. You use these type of permissions for a non-interactive application that is doing work without a human interacting with that application. Application permissions require admin consent because there is no user consent experience by design.
    2. Delegated permissions are those which require a user to interactively sign into the application. The user consents to the permissions, which authorizes the application to act on behalf of the user with the permissions which that user has consented to. If an admin consents to delegated permissions then users don’t consent.
  5. 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
  6. If an Azure AD Application needs a credential, then it has two options–a password or a cert. See more here.
  7. An Azure AD application may define whether it is available to other tenants.
  8. 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
  9. An AAD application may define permission scopes that can be granted to other AAD applications. This is optional.
  10. 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.
  11. 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.

If your application is pre-integrated, it will be listed in the Azure AD application gallery. To proceed, contact UW-IT to get started via 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:

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.


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


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:


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
  • – 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

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:{Your appId}

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

For example:

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 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. 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.

To ensure that the desired end users have access to your Azure AD application, you need to assign the application to them.


  • You’ve already created an Azure AD application
  • You are at least an application owner for this application

There are many ways to assign applications, including by user, by group, and by access packages.

  • Assigning by user is the least desirable because:
    • the assignment will persist beyond most affiliation changes, meaning folks who no longer have a relationship with the UW may still be assigned the application
    • it requires you to add each individual user, a very time-consuming operation
  • Assigning by group is the simplest. This ensures that you are adding a set of users in one go. If the group is in the UW Groups service, you can use a dependency group to ensure users are automatically removed when they lose their relationship with the UW.
  • Assigning by access package is the most secure. This option requires all the users to have a Microsoft 365 A5 for faculty license. An access package has an automated review process, which can help to verify that users still need access. Ask UW-IT for help if you are interested in this option.
NOTE: Nested groups do not receive access to an Azure AD application.
NOTE: If you are provisioning users to your application via SCIM, then you must use group based assignment.

Because assigning by group is the simplest and most common option, we only cover it.

First, find the service principal under Enterprise Applications:

Follow these steps to find a service principal under Enterprise Applications:

  1. Sign in to the Azure portal.
  2. If you have access to multiple tenants, use the Directories + subscriptions filter  in the top menu to switch to the tenant in which you want to register the application.
  3. Search for and select Azure Active Directory.
  4. Under Manage, select Enterprise Applications.

    This will take you to the ‘All Applications’ page of Enterprise Applications, where you can browse or search for a specific service principal (i.e. the specific instance of an application in this tenant)
  5. Enter the name or application id of the service principal. There are also some limited filters you can use to try to find your service principal, if you don’t happen to know the name or app id. The search here tends to be pretty flexible, finding applications regardless of case sensitivity.
Tip: Unlike App Registrations there is no "Owned application" tab, which lets you find applications for which you are an owner quickly. You may find it quicker to use App Registrations > Owned applications > Your app and use the "Go to Enterprise applications" button to get to the right service principal object within Enterprise Applications.

Next, add the assignment(s):

  1. In the left navbar under “Manage”, select the “Users and groups” option
  2. Click “Add user/group” at the top of the screen
  3. Click on None Selected under Users and Groups
  4. In the picker on the right, enter the group id of the desired group, e.g. u_pottery
  5. Click on the right group which shows up in the pick list under where you typed. After clicking on it, note that it shows up below under “Selected items”
  6. Click on “Select” button at bottom
  7. Click on “Assign” button at bottom
  8. Note the group chosen listed on the Users and Groups screen

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.

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. documents the basic process of adding claims, including transformation and condition capabilities. 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 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. 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. provides detailed information relevant to configuring group claims.

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. covers the process of creating a hypothetical OAuth scope for an example application. covers the process of both setting up a scope and having a 2nd application leverage the scope of the 1st. is a comprehensive introduction to OAuth scopes which are sometimes called API permissions or OAuth 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.

The Azure AD application identity is a bridge between the software providing the application’s functionality and the Azure AD users who might use that software. Via User Assignment, you determine which user accounts are allowed to access the software via the identity integration, but via User Assignment you don’t actually make any configuration change to the software itself. Lots of software, especially Software as a Service (SaaS), include the idea of an instantiation of each user within the software’s configuration. This allows the software to customize the user experience by storing special information about the user, such as profile information, special access roles, and more. When the software has a local instantiation of each user, it tends to approach this one of three ways:

  1. An application administrator must create each local (to the software) instantiated user account (in addition to the Azure AD application user assignment). Likewise, removal of user accounts are the responsibility of the application administrator.
  2. The application creates each local instantiated user account “just in time” when an Azure AD user account shows up. The local user accounts tend not to be removed, unless the application administrator realizes this is a gap and fills it.
  3. SCIM provisioning is supported by the software. This requires that the software provides an API which can be called by the application integration platform, in this case, Azure AD.

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 an application supports SCIM provisioning, you use the Enterprise Applications, Provisioning section to configure it & the Enterprise Applications, Provisioning logs section to review activity and troubleshoot.

If your application is not pre-integrated, there are several possible paths depending on the scenario:

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

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:

Users and groups Include | Exclude
Cloud apps Include | Exclude
User actions
Register security information
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)
frequency
Persistent browser session

Conditional Access is an extensive topic, with more information available at Developers may find useful.