Entra ID Application Integration Guide

Web applications can be integrated with UW NetIDs and the UW Groups service via a variety of methods, including Entra ID and UW Shibboleth. UW Shibboleth and Entra ID are both generally recommended.

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

	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
Concepts
Navigation
Creation
Config intro
Config: SAML
Config: OIDC & OAuth
Config: More details
Config: Assignment
Verify connectivity
Claims
Scopes
Consent
Provisioning
Conditional Access

Symbols reference

Symbol	Meaning
	Required
	Recommended
	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 Entra ID. In this case, there should be an entry in the Entra ID 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 Entra ID 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 Entra ID 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:

• Entra ID 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 Entra ID. 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 Entra ID 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 Entra ID 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 https://learn.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 Entra ID Application, we are talking about something very specific. An Entra ID Application is a digital identity and some associated configuration which informs Entra ID 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 Entra ID logon tokens or consume Entra ID logon tokens, then it must be an Entra ID application. The software might have other digital identities it uses, but that topic isn’t covered here.
2. An Entra ID application is represented by two types of objects in Entra ID:
   1. An object of type application. This is the core digital identity with the basic required configuration details, and is only present in the Entra ID 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 Entra ID application, except the Entra ID application’s home tenant. This object will have the specific role assignments and user consent permissions granted for that tenant.
      Note: An Entra ID application’s instantiation in a given tenant is the service principal object–but that service principal references the “primary” Entra ID object of type application that lives in one and only one tenant. You can read more about these Entra ID objects here.
3. All Entra ID 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 Entra ID 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 Entra ID 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 Entra ID 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. Entra ID 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 Entra ID 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 Entra ID application. Most Entra ID 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/.
6. If an Entra ID Application needs a credential, then it has two options–a password or a cert. See more here.
7. An Entra ID application may define whether it is available to other tenants.
8. An Entra ID application must define what permissions to other Entra ID 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 Entra ID user who has logged into your application. You can read more about permission scopes, including the permission scopes that Entra ID itself has available at https://msdn.microsoft.com/Library/Azure/Ad/Graph/howto/azure-ad-graph-api-permission-scopes.
9. An Entra ID application may define permission scopes that can be granted to other Entra ID applications. This is optional.
10. Entra ID application assignments
    1. Each app may define roles which users can be assigned to. This is optional. Each Entra ID application instance will record any role assignments.
    2. Each Entra ID 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 Entra ID application records the URIs that tokens it requests are issued to. A given Entra ID application may have many valid URIs. You might imagine using the same Entra ID application for a production, pre-production, and development instance of the code behind your Entra ID application, each with their own distinct URI. Or you can create a separate Entra ID application for production, pre-production, and development purposes.

This content is at Entra ID Applications: Azure Portal Navigation

If your application is pre-integrated, it will be listed in the Entra ID application gallery. To proceed, contact UW-IT to get started via help@uw.edu with a subject line of “Entra ID 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.

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

If you are integrating a web application with Entra ID, there are several key pieces of information that are required to get your web application to actually use UW Entra ID. 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 Entra ID 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 Entra ID account can use your app
• organizations – any Entra ID account can use your app
• consumers – any personal Microsoft account can use your app
• uwnetid.onmicrosoft.com – only UW Entra ID accounts can use your app
• f6b6dd5b-f02f-441a-99a0-162ac5060bd2 – This is the UW tenant ID – only UW Entra ID 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 Entra ID 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 Entra ID token. You supply this value on the Entra ID 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 Entra ID 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 Entra ID 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 Entra ID 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.

• SAML signing certificate: This ensures trust between your application and Entra ID . This is provided by Entra ID on the service principal that is created. Download a copy and add it to your software’s configuration. The Base64 version is typically used, but you may need the raw format.
• Login URL: https://login.microsoftonline.com/f6b6dd5b-f02f-441a-99a0-162ac5060bd2/saml2. This is the SAML Entra ID endpoint your application points users at when they need to sign in.
• Logout URL: https://login.microsoftonline.com/f6b6dd5b-f02f-441a-99a0-162ac5060bd2/saml2. This is the SAML Entra ID endpoint your application points users at when they need to sign out.
• Entra ID Identifier: https://sts.windows.net/f6b6dd5b-f02f-441a-99a0-162ac5060bd2/

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 Entra ID token. You supply this value on the Entra ID 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:

• Redirect URI: The redirect URI needs to match one of the following options:
  • https://login.microsoftonline.com/common/oauth2/nativeclient
  • https://login.live.com/oauth20_desktop.srf
  • msal08e6d498-3e20-4111-aed8-e88cac3c8a1d://auth

In all cases, the Entra ID 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 Entra ID users only)
  • Multitenant (any Entra ID 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 Entra ID on the service principal object that is created.
• Token endpoints: Configured to use these 2 endpoints with the appropriate value of {tenant}:
  • https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
  • https://login.microsoftonline.com/{tenant}/oauth2/v2.0/tokenWhere {tenant} can have one of 5 values noted in the General Configuration section.

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

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

Pre-requisites:

• You’ve already created an Entra ID 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 Entra ID 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:

 	
Sign in to the Azure portal.
 	
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.
 	
Search for and select Entra ID.
 	
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)

 	
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):

In the left navbar under “Manage”, select the “Users and groups” option
Click “Add user/group” at the top of the screen


Click on None Selected under Users and Groups


In the picker on the right, enter the group id of the desired group, e.g. u_pottery


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”


Click on “Select” button at bottom
Click on “Assign” button at bottom


Note the group chosen listed on the Users and Groups screen



 

Once both the Entra ID 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 Entra ID are:

• givenname
• surname
• emailaddress
• name

If you need more claims, you’ll need to add them. Entra ID sources all data for claims from Entra ID itself. This means the possible claims you can add are restricted to data which is present in UW Entra ID. Entra ID 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 Entra ID 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.

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.

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 Entra ID, 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 Entra ID application identity is a bridge between the software providing the application’s functionality and the Entra ID 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 Entra ID 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 Entra ID 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, Entra ID.

Entra ID 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:

• Vendor provided application which happens to support SCIM: Integrate your SCIM endpoint with the Entra ID SCIM client.
• You are developing your own application: Getting started with SCIM
• You have a legacy on-premises application: add a SCIM gateway to connect to your legacy application, you can use the Entra ID Provisioning agent to directly connect with your application and automate provisioning and deprovisioning.
• You have a legacy applications that doesn’t support SCIM and rely on an LDAP user store or a SQL database, Entra ID 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/.

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:

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.