Add a connected organization in entitlement management

Article
03/16/2023
8 minutes to read

With entitlement management, you can collaborate with people outside your organization. If you frequently collaborate with users in an external Azure AD directory or domain, you can add them as a connected organization. This article describes how to add a connected organization so that you can allow users outside your organization to request resources in your directory.

What is a connected organization?

A connected organization is another organization that you have a relationship with. In order for the users in that organization to be able to access your resources, such as your SharePoint Online sites or apps, you'll need a representation of that organization's users in that directory. Because in most cases the users in that organization aren't already in your Azure AD directory, you can use entitlement management to bring them into your Azure AD directory as needed.

There are three ways that entitlement management lets you specify the users that form a connected organization. It could be

users in another Azure AD directory (from any Microsoft cloud),
users in another non-Azure AD directory that has been configured for direct federation, or
users in another non-Azure AD directory, whose email addresses all have the same domain name in common.

In addition, you can have a connected organization for users with a Microsoft Account, such as from the domain live.com.

For example, suppose you work at Woodgrove Bank and you want to collaborate with two external organizations. These two organizations have different configurations:

Graphic Design Institute uses Azure AD, and their users have a user principal name that ends with graphicdesigninstitute.com.
Contoso does not yet use Azure AD. Contoso users have a user principal name that ends with contoso.com.

In this case, you can configure two connected organizations. You create one connected organization for Graphic Design Institute and one for Contoso. If you then add the two connected organizations to a policy, users from each organization with a user principal name that matches the policy can request access packages. Users with a user principal name that has a domain of contoso.com would match the Contoso-connected organization and would also be allowed to request packages. Users with a user principal name that has a domain of graphicdesigninstitute.com would match the Graphic Design Institute-connected organization and be allowed to submit requests. And, because Graphic Design Institute uses Azure AD, any users with a principal name that matches a verified domain that's added to their tenant, such as graphicdesigninstitute.example, would also be able to request access packages by using the same policy. If you have email one-time passcode (OTP) authentication turned on, that includes users from those domains that aren't yet part of Azure AD directories who'll authenticate using email OTP when accessing your resources.

Connected organization example

How users from the Azure AD directory or domain authenticate depends on the authentication type. The authentication types for connected organizations are:

For a demonstration of how to add a connected organization, watch the following video:

Add a connected organization

To add an external Azure AD directory or domain as a connected organization, follow the instructions in this section.

Prerequisite role: Global administrator, Identity Governance administrator, or User administrator

In the Azure portal, select Azure Active Directory, and then select Identity Governance.
In the left pane, select Connected organizations, and then select Add connected organization.
Select the Basics tab, and then enter a display name and description for the organization.
The state will automatically be set to Configured when you create a new connected organization. For more information about state properties, see State properties of connected organizations
Select the Directory + domain tab, and then select Add directory + domain.

Then Select directories + domains pane opens.
In the search box, enter a domain name to search for the Azure AD directory or domain. You can also add domains that are not in Azure AD. Be sure to enter the entire domain name.
Confirm that the organization name(s) and authentication type(s) are correct. User sign in, prior to being able to access the MyAccess portal, depends on the authentication type for their organization. If the authentication type for a connected organization is Azure AD, all users with an account in any verified domain of that Azure AD directory will sign into their directory, and then can request access to access packages that allow that connected organization. If the authentication type is One-time passcode, this allows users with email addresses from just that domain to visit the MyAccess portal. After they authenticate with the passcode, the user can make a request.

Note

Access from some domains could be blocked by the Azure AD business to business (B2B) allow or deny list. For more information, see Allow or block invitations to B2B users from specific organizations.
Select Add to add the Azure AD directory or domain. You can add multiple Azure AD directories and domains.
After you've added the Azure AD directories or domains, select Select.

The organization(s) appears in the list.
Select the Sponsors tab, and then add optional sponsors for this connected organization.

Sponsors are internal or external users already in your directory that are the point of contact for the relationship with this connected organization. Internal sponsors are member users in your directory. External sponsors are guest users from the connected organization that were previously invited and are already in your directory. Sponsors can be utilized as approvers when users in this connected organization request access to this access package. For information about how to invite a guest user to your directory, see Add Azure Active Directory B2B collaboration users in the Azure portal.

When you select Add/Remove, a pane opens in which you can choose internal or external sponsors. The pane displays an unfiltered list of users and groups in your directory.
Select the Review + create tab, review your organization settings, and then select Create.

Update a connected organization

If the connected organization changes to a different domain, the organization's name changes, or you want to change the sponsors, you can update the connected organization by following the instructions in this section.

Prerequisite role: Global administrator or User administrator

In the Azure portal, select Azure Active Directory, and then select Identity Governance.
In the left pane, select Connected organizations, and then select the connected organization to open it.
In the connected organization's overview pane, select Edit to change the organization name, description, or state.
In the Directory + domain pane, select Update directory + domain to change to a different directory or domain.
In the Sponsors pane, select Add internal sponsors or Add external sponsors to add a user as a sponsor. To remove a sponsor, select the sponsor and, in the right pane, select Delete.

Delete a connected organization

If you no longer have a relationship with an external Azure AD directory or domain, you can delete the connected organization.

Prerequisite role: Global administrator or User administrator

In the Azure portal, select Azure Active Directory, and then select Identity Governance.
In the left pane, select Connected organizations, and then select the connected organization to open it.
In the connected organization's overview pane, select Delete to delete it.

Managing a connected organization programmatically

You can also create, list, update, and delete connected organizations using Microsoft Graph. A user in an appropriate role with an application that has the delegated EntitlementManagement.ReadWrite.All permission can call the API to manage connectedOrganization objects and set sponsors for them.

Manage connected organizations through Microsoft PowerShell

You can also manage connected organizations in PowerShell with the cmdlets from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 1.16.0 or later.

This script below illustrates using the v1.0 profile of Graph to retrieve all the connected organizations.

Connect-MgGraph -Scopes "EntitlementManagement.ReadWrite.All"
Select-MgProfile -Name "v1.0"

$co = Get-MgEntitlementManagementConnectedOrganization -all

State properties of connected organizations

There are two different types of state properties for connected organizations in entitlement management currently, configured and proposed:

A configured connected organization is a fully functional connected organization that allows users within that organization access to access packages. When an admin creates a new connected organization in the Azure portal, it will be in the configured state by default since the administrator created and wants to use this connected organization. Additionally, when a connected org is created programmatically via the API, the default state should be configured unless set to another state explicitly.

Configured connected organizations will show up in the pickers for connected organizations and will be in scope for any policies that target “all” connected organizations.
A proposed connected organization is a connected organization that has been automatically created, but hasn't had an administrator create or approve the organization. When a user signs up for an access package outside of a configured connected organization, any automatically created connected organizations will be in the proposed state since no administrator in the tenant set-up that partnership.

Proposed connected organizations are not in scope for the “all configured connected organizations” setting on any policies but can be used in policies only for policies targeting specific organizations.

Only users from configured connected organizations can request access packages that are available to users from all configured organizations. Users from proposed connected organizations have an experience as if there is no connected organization for that domain; can only see and request access packages scoped to their specific organization or scoped to any user.

Note

As part of rolling out this new feature, all connected organizations created before 09/09/20 were considered configured. If you had an access package that allowed users from any organization to sign up, you should review your list of connected organizations that were created before that date to ensure none are miscategorized as configured. An admin can update the State property as appropriate. For guidance, see Update a connected organization.