Tell us about y our PDF experience. Multit enant or ganizations documentation A multitenant organization is an organization that has more than one instance of Microsoft Entra ID. Describes ways that users can have a seamless experience accessing resources and collaborating across multiple tenants. About multit enant or ganizations ｅOVERVIE W Multitenant organization capabilities Compare multitenant capabilities Configur e a multit enant or ganization ｅOVERVIE W What is a multitenant organization? ｃHOW-T O GUIDE Microsoft 365 admin center PowerShell or Microsoft Graph API Configur e cross-t enant synchr onization ｅOVERVIE W What is cross-tenant synchronization? ｃHOW-T O GUIDE Microsoft Entra admin center PowerShell or Microsoft Graph API
Collaborat e in Micr osoft 365 ｐCONCEPT Identity provisioning for Microsoft 365 Microsoft 365 multitenant people search Plan for multitenant organizations in Microsoft 365
Multitenant organization capabilities in Microsoft Entra ID Article •04/23/2024 This article provides an overview of the multitenant organization scenario and the related capabilities in Microsoft Entra ID. A tenant is an instance of Microsoft Entra ID in which information about a single organization resides including organizational objects such as users, groups, and devices and also application registrations, such as Microsoft 365 and third-party applications. A tenant also contains access and compliance policies for resources, such as applications registered in the directory. The primary functions served by a tenant include identity authentication as well as resource access management. From a Microsoft Entra perspective, a tenant forms an identity and access management scope. For example, a tenant administrator makes an application available to some or all the users in the tenant and enforces access policies on that application for users in that tenant. In addition, a tenant contains organizational branding data that drives end-user experiences, such as the organizations email domains and ShareP oint URLs used by employees in that organization. From a Microsoft 365 perspective, a tenant forms the default collaboration and licensing boundary. For example, users in Microsoft T eams or Microsoft Outlook can easily find and collaborate with other users in their tenant, but don't have the ability to find or see users in other tenants. Tenants contain privileged organizational data and are securely isolated from other tenants. In addition, tenants can be configured to have data persisted and processed in a specific region or cloud, which enables organizations to use tenants as a mechanism to meet data residency and handling compliance requirements. A multit enant or ganization is an organization that has more than one instance of Microsoft Entra ID. Here are the primary reasons why an organization might have multiple tenants: Conglomerat es: Organizations with multiple subsidiaries or business units that operate independently.What is a tenant? What is a multitenant organization?
Mergers and acquisitions: Organizations that merge or acquire companies. Divestitur e activity: In a divestiture, one organization splits off part of its business to form a new organization or sell it to an existing organization. Multiple clouds: Organizations that have compliance or regulatory needs to exist in multiple cloud environments. Multiple geographical boundaries: Organizations that operate in multiple geographic locations with various residency regulations. Test or staging t enants: Organizations that need multiple tenants for testing or staging purposes before deploying more broadly to primary tenants. Department or employ ee-cr eated tenants: Organizations where departments or employees have created tenants for development, testing, or separate control. Your organization may have recently acquired a new company, merged with another company, or restructured based on newly formed business units. If you have disparate identity management systems, it might be challenging for users in different tenants to access resources and collaborate. The following diagram shows how users in other tenants might not be able to access applications across tenants in your organization. As your organization evolves, your IT team must adapt to meet the changing needs. This often includes integrating with an existing tenant or forming a new one. R egardless of how the identity infrastructure is managed, it's critical that users have a seamless experience accessing resources and collaborating. T oday, you may be using custom scripts or on-premises solutions to bring the tenants together to provide a seamless experience across tenants. To enable users across tenants to collaborate in Teams Connect shared channels , you can use Microsoft Entra B2B direct connect . B2B direct connect is a feature of External Identities that lets you set up a mutual trust relationship with another Microsoft Entra organization for seamless collaboration in T eams. When the trust is established, the B2B direct connect user has single sign-on access using credentials from their home tenant.Multitenant challenges B2B direct connect
Here's the primary constraint with using B2B direct connect across multiple tenants: Currently, B2B direct connect works only with T eams Connect shared channels. For more information, see B2B direct connect overview . To enable users across tenants to collaborate, you can use Microsoft Entra B2B collaboration . B2B collaboration is a feature within External Identities that lets you invite guest users to collaborate with your organization. Once the external user has redeemed their invitation or completed sign-up, they're represented in your tenant as a user object. With B2B collaboration, you can securely share your company's applications and services with external users, while maintaining control over your own corporate data. Here are the primary constraints with using B2B collaboration across multiple tenants: Administrators must invite users using the B2B invitation process or build an onboarding experience using the B2B collaboration invitation manager . Administrators might have to synchronize users using custom scripts. Depending on automatic redemption settings, users might need to accept a consent prompt and follow a redemption process in each tenant. By default, users are of type external guest, which has different permissions than external member and might not be the desired user experience. B2B collaboration
For more information, see B2B collaboration overview . If you want users to have a more seamless collaboration experience across tenants, you can use cross-tenant synchronization . Cross-tenant synchronization is a one-way synchronization service in Microsoft Entra ID that automates creating, updating, and deleting B2B collaboration users across tenants in an organization. Cross-tenant synchronization builds on the B2B collaboration functionality and utilizes existing B2B cross-tenant access settings. Users are represented in the target tenant as a B2B collaboration user object. Here are the primary benefits with using cross-tenant synchronization: Automatically create B2B collaboration users within your organization and provide them access to the applications they need, without creating and maintaining custom scripts. Improve the user experience and ensure that users can access resources, without receiving an invitation email and having to accept a consent prompt in each tenant. Automatically update users and remove them when they leave the organization. Here are the primary constraints with using cross-tenant synchronization across multiple tenants: Doesn't enhance the current T eams or Microsoft 365 experiences. S ynchronized users will have the same cross-tenant T eams and Microsoft 365 experiences available to any other B2B collaboration user. Doesn't synchronize groups, devices, or contacts. For more information, see What is cross-tenant synchronization? .Cross-tenant synchronization
Multitenant organization is a feature in Microsoft Entra ID and Microsoft 365 that enables you to form a tenant group within your organization. Each pair of tenants in the group is governed by cross-tenant access settings that you can use to configure B2B or cross-tenant synchronization. Here are the primary benefits of a multitenant organization: Differentiate in-organization and out-of-organization external users Improved collaborative experience in new Microsoft T eams Improved people search experience across tenants For more information, see What is a multitenant organization in Microsoft Entra ID? . Depending on the needs of your organization, you can use any combination of B2B direct connect, B2B collaboration, cross-tenant synchronization, and multitenant organization capabilities. B2B direct connect and B2B collaboration are independent capabilities, while cross-tenant synchronization and multitenant organization capabilities are independent of each other, though both rely on underlying B2B collaboration. The following table compares the capabilities of each feature. For more information about different external identity scenarios, see Comparing External Identities feature sets.Multitenant organization Compare multitenant capabilities ﾉExpand table
B2B dir ect connect (Org-to-org external or internal)B2B collaboration (Org-to-org external or internal)Cross-t enant synchr onization (Org int ernal)Multit enant organization (Org int ernal) Purpose Users can access T eams Connect shared channels hosted in external tenants.Users can access apps/resources hosted in external tenants, usually with limited guest privileges. Depending on automatic redemption settings, users might need to accept a consent prompt in each tenant.Users can seamlessly access apps/resources across the same organization, even if they're hosted in different tenants.Users can more seamlessly collaborate across a multitenant organization in new T eams and people search. Value Enables external collaboration within T eams Connect shared channels only. More convenient for administrators because they don't have to manage B2B users.Enables external collaboration. More control and monitoring for administrators by managing the B2B collaboration users. Administrators can limit the access that these external users have to their apps/resources.Enables collaboration across organizational tenants. Administrators don't have to manually invite and synchronize users between tenants to ensure continuous access to apps/resources within the organization.Enables collaboration across organizational tenants. Administrators continue to have full configuration ability via cross- tenant access settings. Optional cross-tenant access templates allow pre- configuration of cross-tenant access settings. Primar y administrat or workflowConfigure cross-tenant access to provide external users inbound access to tenant the credentials for their home tenant.Add external users to resource tenant by using the B2B invitation process or build your own onboarding experience using the B2B collaborationConfigure the cross-tenant synchronization engine to synchronize users between multiple tenants as B2B collaboration users.Create a multitenant organization, add (invite) tenants, join a multitenant organization. Leverage existing B2B collaboration users or use cross- tenant synchronization to
B2B dir ect connect (Org-to-org external or internal)B2B collaboration (Org-to-org external or internal)Cross-t enant synchr onization (Org int ernal)Multit enant organization (Org int ernal) invitation manager .provision B2B collaboration users. Trust lev el Mid trust. B2B direct connect users are less easy to track, mandating a certain level of trust with the external organization.Low to mid trust. User objects can be tracked easily and managed with granular controls.High trust. All tenants are part of the same organization, and users are typically granted member access to all apps/resources.High trust. All tenants are part of the same organization, and users are typically granted member access to all apps/resources. Effect on usersUsers access the resource tenant using the credentials for their home tenant. User objects aren't created in the resource tenant.External users are added to a tenant as B2B collaboration users.Within the same organization, users are synchronized from their home tenant to the resource tenant as B2B collaboration users.Within the same multitenant organization, B2B collaboration users, particularly member users, benefit from enhanced, seamless collaboration across Microsoft 365. User type B2B direct connect user
- N/AB2B collaboration user
- External member
- External guest (default)B2B collaboration user
- External member (default)
- External guestB2B collaboration user
- External member (default)
- External guest The following diagram shows how B2B direct connect, B2B collaboration, and cross- tenant synchronization capabilities could be used together.
To better understand multitenant organization scenario related Microsoft Entra capabilities, you can refer back to the following list of terms. Term Definition tenant An instance of Microsoft Entra ID. organization The top level of a business hierarchy. multitenant organizationAn organization that has more than one instance of Microsoft Entra ID, as well as a capability to group those instances in Microsoft Entra ID. creator tenant The tenant that created the multitenant organization. owner tenant A tenant with the owner role. Initially, the creator tenant. added tenant A tenant that was added by an owner tenant. joiner tenant A tenant that is joining the multitenant organization. join request A joiner or added tenant submits a join request to join the multitenant organization. pending tenant A tenant that was added by an owner but that hasn't yet joined. active tenant A tenant that created or joined the multitenant organization. Terminology ﾉExpand table
Term Definition member tenant A tenant with the member role. Most joiner tenants start as members. multitenant organization tenantAn active tenant of the multitenant organization, not pending. cross-tenant synchronizationA one-way synchronization service in Microsoft Entra ID that automates creating, updating, and deleting B2B collaboration users across tenants in an organization. cross-tenant access settingsSettings to manage collaboration for specific Microsoft Entra organizations. cross-tenant access settings templateAn optional template to preconfigure cross-tenant access settings that are applied to any partner tenant newly joining the multitenant organization. organizational settingsCross-tenant access settings for specific Microsoft Entra organizations. configuration An application and underlying service principal in Microsoft Entra ID that includes the settings (such as target tenant, user scope, and attribute mappings) needed for cross-tenant synchronization. provisioning The process of automatically creating or synchronizing objects across a boundary. automatic redemption A B2B setting to automatically redeem invitations so newly created users don't receive an invitation email or have to accept a consent prompt when added to a target tenant. What is a multitenant organization in Microsoft Entra ID? What is cross-tenant synchronization?Next steps
What is a multitenant organization in Microsoft Entra ID? Article •04/24/2024 Multitenant organization is a feature in Microsoft Entra ID and Microsoft 365 that enables you to form a tenant group within your organization. Each pair of tenants in the group is governed by cross-tenant access settings that you can use to configure B2B or cross-tenant synchronization. Here are the primary goals of multitenant organization: Define a group of tenants belonging to your organization Collaborate across your tenants in new Microsoft T eams Enable search and discovery of user profiles across your tenants through Microsoft 365 people search Organizations that own multiple Microsoft Entra tenants and want to streamline intra- organization cross-tenant collaboration in Microsoft 365. The multitenant organization capability is built on the assumption of reciprocal provisioning of B2B member users across multitenant organization tenants. As such, the multitenant organization capability assumes the simultaneous use of Microsoft Entra cross-tenant synchronization or an alternative bulk provisioning engine for external identities . Here are the primary benefits of a multitenant organization: Differentiate in-organization and out-of-organization external users In Microsoft Entra ID, external users originating from within a multitenant organization can be differentiated from external users originating from outside the multitenant organization. This differentiation facilitates the application of different policies for in-organization and out-of-organization external users.Why use multitenant organization? Who should use it? Benefits
Improved collaborative experience in Microsoft T eams In new Microsoft T eams, multitenant organization users can expect an improved collaborative experience across tenants with chat, calling, and meeting start notifications from all connected tenants across the multitenant organization. Tenant switching is more seamless and faster. For more information, see Announcing more seamless collaboration in Microsoft T eams for multitenant organizations and Microsoft T eams: Advantages of the new architecture . Improved people search experience across tenants Across Microsoft 365 services, the multitenant organization people search experience is a collaboration feature that enables search and discovery of people across multiple tenants. Once enabled, users are able to search and discover synced user profiles in a tenant's global address list and view their corresponding people cards. For more information, see Microsoft 365 multitenant organization people search . The multitenant organization capability enables you to form a tenant group within your organization. The following list describes the basic lifecycle of a multitenant organization. Define a multitenant organization One tenant administrator defines a multitenant organization as a grouping of tenants. The grouping of tenants isn't reciprocal until each listed tenant takes action to join the multitenant organization. The objective is a reciprocal agreement between all listed tenants. Join a multitenant organization Tenant administrators of listed tenants take action to join the multitenant organization. After joining, the multitenant organization relationship is reciprocal between each and every tenant that joined the multitenant organization. Leave a multitenant organization Tenant administrators of listed tenants can leave a multitenant organization at any time. While a tenant administrator who defined the multitenant organization can add and remove listed tenants they don't control the other tenants. How does a multitenant organization work?
A multitenant organization is established as a collaboration of equals. Each tenant administrator stays in control of their tenant and their membership in the multitenant organization. Administrators staying in control of their resources is a guiding principle for multitenant organization collaboration. Cross-tenant access settings are required for each tenant-to- tenant relationship. T enant administrators explicitly configure, as needed, the following policies: Cross-tenant access partner configurations For more information, see Configure cross-tenant access settings for B2B collaboration and crossT enantAccessP olicyConfigurationP artner resource type . Cross-tenant access identity synchronization For more information, see Configure cross-tenant synchronization and crossT enantIdentityS yncPolicyP artner resource type . The following diagram shows three tenants A, B, and C that form a multitenant organization.Cross-tenant access setting s Multitenant organization example ﾉExpand table
Tenant Descr iption A Administrators see a multitenant organization consisting of A, B, C. They also see cross-tenant access settings for B and C. B Administrators see a multitenant organization consisting of A, B, C. They also see cross-tenant access settings for A and C. C Administrators see a multitenant organization consisting of A, B, C. They also see cross-tenant access settings for A and B. To ease the setup of homogenous cross-tenant access settings applied to partner tenants in the multitenant organization, the administrator of each multitenant organization tenant can configure optional cross-tenant access settings templates dedicated to the multitenant organization. These templates can be used to preconfigure cross-tenant access settings that are applied to any partner tenant newly joining the multitenant organization. To facilitate the management of a multitenant organization, any given multitenant organization tenant has an associated role and state. Tenant roleDescr iption Owner One tenant creates the multitenant organization. The multitenant organization creating tenant receives the role of owner. The privilege of the owner tenant is to add tenants into a pending state as well as to remove tenants from the multitenant organization. Also, an owner tenant can change the role of other multitenant organization tenants. Member Following the addition of pending tenants to the multitenant organization, pending tenants need to join the multitenant organization to turn their state from pending to active. Joined tenants typically start in the member role. Any member tenant has the privilege to leave the multitenant organization.Templates for cross-tenant access setting s Tenant role and state ﾉExpand table ﾉExpand table
Tenant stateDescr iption Pending A pending tenant has yet to join a multitenant organization. While listed in an administrator’s view of the multitenant organization, a pending tenant isn't yet part of the multitenant organization, and as such is hidden from an end user’s view of a multitenant organization. Active Following the addition of pending tenants to the multitenant organization, pending tenants need to join the multitenant organization to turn their state from pending to active. Joined tenants typically start in the member role. Any member tenant has the privilege to leave the multitenant organization. The multitenant organization capability has been designed with the following constraints: Any given tenant can only create or join a single multitenant organization. Any multitenant organization must have at least one active owner tenant. Each active tenant must have cross-tenant access settings for all active tenants. Any active tenant may leave a multitenant organization by removing themselves from it. A multitenant organization is deleted when the only remaining active (owner) tenant leaves. Resour ce Limit Notes Maximum number of active tenants, including the owner tenant100 The owner tenant can add more than 100 pending tenants, but they won't be able to join the multitenant organization if the limit is exceeded. This limit is applied at the time a pending tenant joins a multitenant organization. This limit is specific to the number of tenants in a multitenant organization. It does not apply to cross-tenant synchronization by itself. T o increase this limit, submit a support request in the Microsoft Entra or Microsoft 365 admin center. In the Microsoft Graph APIs, the default limit of 100 tenants is only enforced at the time of joining. In Microsoft 365 admin center, the default limit is enforced at multitenant organization creation time and at time of joining.Constraints Limits ﾉExpand table
By defining a multitenant organization, as well as pivoting on the Microsoft Entra user property of userT ype, external identities are segmented as follows: External members originating from within a multitenant organization External guests originating from within a multitenant organization External members originating from outside of your organization External guests originating from outside of your organization This segmentation of external users, due to the definition of a multitenant organization, enables administrators to better differentiate in-organization from out-of-organization external users. External members originating from within a multitenant organization are called multitenant organization members. Multitenant collaboration capabilities in Microsoft 365 aim to provide a seamless collaboration experience across tenant boundaries when collaborating with multitenant organization member users. If you haven't previously used Microsoft Entra cross-tenant synchronization, and you intend to establish a collaborating user set topology where the same set of users is shared to all multitenant organization tenants, you might want to use the Microsoft 365 admin center share users functionality. If you're already using Microsoft Entra cross-tenant synchronization, for various multi-hub multi-spoke topologies , you don't need to use the Microsoft 365 admin center share users functionality. Instead, you might want to continue using your existing Microsoft Entra cross-tenant synchronization jobs. Here are the basic steps to get started using multitenant organization. For more information, see Plan for multitenant organizations in Microsoft 365 .External user segmentation Choosing between Microsoft 365 admin center and cross-tenant synchronization Get started Step 1: Plan your deployment
Create your multitenant organization using Microsoft 365 admin center , Microsoft Graph P owerShell , or Microsoft Graph API : First tenant, soon-to-be owner tenant, creates a multitenant organization. Owner tenant adds one or more joiner tenants. Join a multitenant organization using Microsoft 365 admin center or Microsoft Graph PowerShell , or Microsoft Graph API : Joiner tenants submit a join request to join the multitenant organization of owner tenant. To allow for asynchronous processing, wait up to 2 hour s. Your multitenant organization is formed. Depending on your use case, you may want to synchronize users using one of the following methods: Synchronize users in multitenant organizations in Microsoft 365 Configure cross-tenant synchronization Configure cross-tenant synchronization using P owerShell or Microsoft Graph API Your alternative bulk provisioning engine The multitenant organization capability requires Microsoft Entra ID P1 licenses. Only one Microsoft Entra ID P1 license is required per employee per multitenant organization. Also, you must have at least one Microsoft Entra ID P1 license per tenant. T o find the right license for your requirements, see Compare generally available features of Microsoft Entra ID . Plan for multitenant organizations in Microsoft 365 What is cross-tenant synchronization?Step 2: Create your multitenant organization Step 3: Join a multitenant organization Step 4: Synchronize users License requirements Next steps
What is cross-tenant synchronization? Article •01/03/2024 Cross-tenant s ynchr onization automates creating, updating, and deleting Microsoft Entra B2B collaboration users across tenants in an organization. It enables users to access applications and collaborate across tenants, while still allowing the organization to evolve. Here are the primary goals of cross-tenant synchronization: Seamless collaboration for a multitenant organization Automate lifecycle management of B2B collaboration users in a multitenant organization Automatically remove B2B accounts when a user leaves the organization Cross-tenant synchronization automates creating, updating, and deleting B2B collaboration users. Users created with cross-tenant synchronization are able to access both Microsoft applications (such as T eams and ShareP oint) and non-Microsoft applications (such as ServiceNow , Adobe , and many more), regardless of which tenant the apps are integrated with. These users continue to benefit from the security capabilities in Microsoft Entra ID, such as Microsoft Entra Conditional Access and cross- tenant access settings , and can be governed through features such as Microsoft Entra entitlement management . The following diagram shows how you can use cross-tenant synchronization to enable users to access applications across tenants in your organization.https://www.youtube-nocookie.com/embed/7B-PQwNfGBc Why use cross-tenant synchronization?
Organizations that own multiple Microsoft Entra tenants and want to streamline intra-organization cross-tenant application access. Cross-tenant synchronization is not currently suitable for use across organizational boundaries. With cross-tenant synchronization, you can do the following: Automatically create B2B collaboration users within your organization and provide them access to the applications they need, without creating and maintaining custom scripts. Improve the user experience and ensure that users can access resources, without receiving an invitation email and having to accept a consent prompt in each tenant. Automatically update users and remove them when they leave the organization. Users created by cross-tenant synchronization will have the same experience when accessing Microsoft T eams and other Microsoft 365 services as B2B collaboration users created through a manual invitation. If your organization uses shared channels, please see the known issues document for additional details. Over time, the member userT ype will be used by the various Microsoft 365 services to provide differentiated end user experiences for users in a multitenant organization. Who should use? Benefits Teams and Microsoft 365
When you configure cross-tenant synchronization, you define a trust relationship between a source tenant and a target tenant. Cross-tenant synchronization has the following properties: Based on the Microsoft Entra provisioning engine. Is a push process from the source tenant, not a pull process from the target tenant. Supports pushing only internal members from the source tenant. It doesn't support syncing external users from the source tenant. Users in scope for synchronization are configured in the source tenant. Attribute mapping is configured in the source tenant. Extension attributes are supported. Target tenant administrators can stop a synchronization at any time. The following table shows the parts of cross-tenant synchronization and which tenant they're configured. Tenant Cross-t enant access settingsAutomatic r edemption Sync settings configurationUser s in scope Source tenant✔ ✔ ✔ Target tenant✔ ✔ The cross-tenant synchronization setting is an inbound only organizational setting to allow the administrator of a source tenant to synchronize users into a target tenant. This setting is a check box with the name Allow user s sync int o this t enant that is specified in the target tenant. This setting doesn't impact B2B invitations created through other processes such as manual invitation or Microsoft Entra entitlement management .Properties ﾉExpand table Cross-tenant synchronization setting
To configure this setting using Microsoft Graph, see the Update
crossT enantIdentityS yncPolicyP artner API. For more information, see Configure cross-
tenant synchronization .
The automatic redemption setting is an inbound and outbound organizational trust
setting to automatically redeem invitations so users don't have to accept the consent
prompt the first time they access the resource/target tenant. This setting is a check box
with the following name:
Automatically r edeem invitations with the t enant
When users are created in a target tenant using cross-tenant synchronization.
When users are added to a resource tenant using B2B collaboration.
When users access resources in a resource tenant using B2B direct connect.
The following table shows how this setting compares when enabled for these scenarios:
Item Cross-t enant
synchr onizationB2B
collaborationB2B dir ect
connect
Automatic redemption setting Required Optional Optional
Users receive a B2B collaboration
invitation emailNo No N/A
Users must accept a consent
promptNo No No
Users receive a B2B collaboration
notification emailNo Yes N/A
This setting doesn't impact application consent experiences. For more information, see
Consent experience for applications in Microsoft Entra ID . This setting isn't supported
for organizations across different Microsoft cloud environments, such as Azure
commercial and Azure Government.
The automatic redemption setting will only suppress the consent prompt and invitation
email if both the home/source tenant (outbound) and resource/target tenant (inbound)
checks this setting.
The following table shows the consent prompt behavior for source tenant users when
the automatic redemption setting is checked for different cross-tenant access setting
combinations.ﾉExpand table
When is consent prompt suppressed? Home/sour ce tenant Resour ce/tar get t enant Consent pr ompt behavior
for sour ce tenant user s
Outbound Inbound
Suppressed
Not suppressed
Not suppressed
Not suppressed
Inbound Outbound
Not suppressed
Not suppressed
Not suppressed
Not suppressed
To configure this setting using Microsoft Graph, see the Update
crossT enantAccessP olicyConfigurationP artner API. For more information, see Configure
cross-tenant synchronization .
For cross-tenant synchronization, users don't receive an email or have to accept a
consent prompt. If users want to see what tenants they belong to, they can open their
My Account page and select Organizations . In the Microsoft Entra admin center, users
can open their Portal settings , view their Directories + subscriptions , and switch
directories.
For more information, including privacy information, see Leave an organization as an
external user .
Here are the basic steps to get started using cross-tenant synchronization.ﾉExpand table
How do users know what tenants they belong to?
Get started Cross-tenant synchronization provides a flexible solution to enable collaboration, but
every organization is different. For example, you might have a central tenant, satellite
tenants, or sort of a mesh of tenants. Cross-tenant synchronization supports any of
these topologies. For more information, see Topologies for cross-tenant
synchronization .
In the target tenant where users are created, navigate to the Cross-t enant access
settings page. Here you enable cross-tenant synchronization and the B2B automatic
redemption settings by selecting the respective check boxes. For more information, see
Configure cross-tenant synchronization .
In any source tenant, navigate to the Cross-t enant access settings page and enable the
B2B automatic redemption feature. Next, you use the Cross-t enant synchr onization
page to set up a cross-tenant synchronization job and specify:
Which users you want to synchronize
What attributes you want to include
Any transformations
For anyone that has used Microsoft Entra ID to provision identities into a SaaS
application , this experience will be familiar. Once you have synchronization configured,Step 1: Define how to structure the tenants in your organization
Step 2: Enable cross-tenant synchronization in the target tenants
Step 3: Enable cross-tenant synchronization in the source tenants you can start testing with a few users and make sure they're created with all the
attributes that you need. When testing is complete, you can quickly add additional users
to synchronize and roll out across your organization. For more information, see
Configure cross-tenant synchronization .
In the source tenant: Using this feature requires Microsoft Entra ID P1 licenses. Each user
who is synchronized with cross-tenant synchronization must have a P1 license in their
home/source tenant. T o find the right license for your requirements, see Compare
generally available features of Microsoft Entra ID .
In the target tenant: Cross-tenant sync relies on the Microsoft Entra External ID billing
model. T o understand the external identities licensing model, see MAU billing model for
Microsoft Entra External ID . You will also need at least one Microsoft Entra ID P1 license
in the target tenant to enable auto-redemption.
Which clouds can cross-tenant synchronization be used in?
Cross-tenant synchronization is supported within the commercial cloud and Azure
Government.
Cross-tenant synchronization isn't supported within the Microsoft Azure operated
by 21Vianet cloud.
Synchronization is only supported between two tenants in the same cloud.
Cross-cloud (such as public cloud to Azure Government) isn't currently supported.
Will cross-tenant synchronization manage existing B2B users?License requirements
Frequently asked questions
Clouds
Existing B2B users Yes. Cross-tenant synchronization uses an internal attribute called the
alternativeSecurityIdentifier to uniquely match an internal user in the source tenant
with an external / B2B user in the target tenant. Cross-tenant synchronization can
update existing B2B users, ensuring that each user has only one account.
Cross-tenant synchronization cannot match an internal user in the source tenant
with an internal user in the target tenant (both type member and type guest).
How often does cross-tenant synchronization run?
The sync interval is currently fixed to start at 40-minute intervals. S ync duration
varies based on the number of in-scope users. The initial sync cycle is likely to take
significantly longer than the following incremental sync cycles.
How do I control what is synchronized into the target tenant?
In the source tenant, you can control which users are provisioned with the
configuration or attribute-based filters. Y ou can also control what attributes on the
user object are synchronized. For more information, see Scoping users or groups
to be provisioned with scoping filters .
If a user is removed from the scope of sync in a source tenant, will cross-tenant
synchronization soft delete them in the target?
Yes. If a user is removed from the scope of sync in a source tenant, cross-tenant
synchronization will soft delete them in the target tenant.
What object types can be synchronized?
Microsoft Entra users can be synchronized between tenants. (Groups, devices, and
contacts aren't currently supported.)
What user types can be synchronized?
Internal members can be synchronized from source tenants. Internal guests can't
be synchronized from source tenants.
Users can be synchronized to target tenants as external members (default) or
external guests.Synchronization frequency
Scope
Object types For more information about the UserT ype definitions, see Properties of a Microsoft
Entra B2B collaboration user .
I have existing B2B collaboration users. What will happen to them?
Cross-tenant synchronization will match the user and make any necessary updates
to the user, such as update the display name. By default, the UserT ype won't be
updated from guest to member, but you can configure this in the attribute
mappings.
What user attributes can be synchronized?
Cross-tenant synchronization will sync commonly used attributes on the user
object in Microsoft Entra ID, including (but not limited to) displayName,
userPrincipalName, and directory extension attributes.
Cross-tenant synchronization supports provisioning the manager attribute. Both
the user and their manager must be in scope for provisioning.
For cross-tenant synchronization configurations created before January 2024
with the default schema / attribute mappings:
The manager attribute will automatically be added to the mappings.
This does not trigger an initial sync cycle.
Manager updates will apply on the incremental cycle for users that are
undergoing changes (e.g. manager change). The sync engine doesn’t
automatically update all existing users that were provisioned previously.
To update the manager for existing users that are in scope for provisioning,
you can use on-demand provisioning for specific users or do a restart to
provision the manager for all users.
For cross-tenant synchronization configurations created before January 2024
with a custom schema / attribute mappings (e.g. you added an attribute to the
mappings or changed the default mappings):
You need to manually add the manager attribute to your attribute mappings.
This will trigger a restart and update all users that are in scope for
provisioning. This should be a direct mapping of the manager attribute in the
source tenant to the manager in the target tenant.
If the manager of a user is removed in the source tenant and no new manager is
assigned in the source tenant, the manager attribute will not be updated in the
target tenant.
What attributes can't be synchronized?Attributes Attributes including (but not limited to) photos, custom security attributes, and
user attributes outside of the directory can't be synchronized by cross-tenant
synchronization.
Can I control where user attributes are sourced/managed?
Cross-tenant synchronization doesn't offer direct control over source of authority.
The user and its attributes are deemed authoritative at the source tenant. There are
parallel sources of authority workstreams that will evolve source of authority
controls for users down to the attribute level and a user object at the source may
ultimately reflect multiple underlying sources. For the tenant-to-tenant process,
this is still treated as the source tenant's values being authoritative for the sync
process (even if pieces actually originate elsewhere) into the target tenant.
Currently, there's no support for reversing the sync process's source of authority.
Cross-tenant synchronization only supports source of authority at the object level.
That means all attributes of a user must come from the same source, including
credentials. It isn't possible to reverse the source of authority or federation
direction of a synchronized object.
What happens if attributes for a synced user are changed in the target tenant?
Cross-tenant synchronization doesn't query for changes in the target. If no
changes are made to the synced user in the source tenant, then user attribute
changes made in the target tenant will persist. However, if changes are made to
the user in the source tenant, then during the next synchronization cycle, the user
in the target tenant will be updated to match the user in the source tenant.
Can the target tenant manually block sign-in for a specific home/source tenant user that
is synced?
If no changes are made to the synced user in the source tenant, then the block
sign-in setting in the target tenant will persist. If a change is detected for the user
in the source tenant, cross-tenant synchronization will re-enable that user blocked
from sign-in in the target tenant.
Can I sync a mesh between multiple tenants?
Cross-tenant synchronization is configured as a single-direction peer-to-peer sync,
meaning sync is configured between one source and one target tenant. Multiple
instances of cross-tenant synchronization can be configured to sync from a singleStructure source to multiple targets and from multiple sources into a single target. But only
one sync instance can exist between a source and a target.
Cross-tenant synchronization only synchronizes users that are internal to the
home/source tenant, ensuring that you can't end up with a loop where a user is
written back to the same tenant.
Multiple topologies are supported. For more information, see Topologies for cross-
tenant synchronization .
Can I use cross-tenant synchronization across organizations (outside my multitenant
organization)?
For privacy reasons, cross-tenant synchronization is intended for use within an
organization. W e recommend using entitlement management for inviting B2B
collaboration users across organizations.
Can cross-tenant synchronization be used to migrate users from one tenant to another
tenant?
No. Cross-tenant synchronization isn't a migration tool because the source tenant
is required for synchronized users to authenticate. In addition, tenant migrations
would require migrating user data such as ShareP oint and OneDrive.
Does cross-tenant synchronization resolve any present B2B collaboration limitations?
Since cross-tenant synchronization is built on existing B2B collaboration
technology, existing limitations apply. Examples include (but aren't limited to):
App or
serviceLimitations
Power BI - Support for UserT ype Member in P ower BI is currently in preview. For
more information, see Distribute P ower BI content to external guest users
with Microsoft Entra B2B .
Azure Virtual
Desktop- External member and external guest aren't supported in Azure Virtual
Desktop.
How does cross-tenant synchronization relate to B2B direct connect ?B2B collaboration
ﾉExpand table
B2B direct connect B2B direct connect is the underlying identity technology required for Teams
Connect shared channels .
We recommend B2B collaboration for all other cross-tenant application access
scenarios, including both Microsoft and non-Microsoft applications.
B2B direct connect and cross-tenant synchronization are designed to co-exist, and
you can enable them both for broad coverage of cross-tenant scenarios.
We're trying to determine the extent to which we'll need to utilize cross-tenant
synchronization in our multitenant organization. Do you plan to extend support for B2B
direct connect beyond T eams Connect?
There's no plan to extend support for B2B direct connect beyond T eams Connect
shared channels.
Does cross-tenant synchronization enhance any cross-tenant Microsoft 365 app access
user experiences?
Cross-tenant synchronization utilizes a feature that improves the user experience
by suppressing the first-time B2B consent prompt and redemption process in each
tenant.
Synchronized users will have the same cross-tenant Microsoft 365 experiences
available to any other B2B collaboration user.
Can cross-tenant synchronization enable people search scenarios where synchronized
users appear in the global address list of the target tenant?
Yes, but you must set the value for the showInAddr essList attribute of
synchronized users to True, which is not set by default. If you want to create a
unified address list, you'll need to set up a mesh peer-to-peer topology . For more
information, see Step 9: R eview attribute mappings .
Cross-tenant synchronization creates B2B collaboration users and doesn't create
contacts.
Does cross-tenant synchronization enhance any current T eams experiences?
Synchronized users will have the same cross-tenant Microsoft 365 experiences
available to any other B2B collaboration user.Microsoft 365
Teams What federation options are supported for users in the target tenant back to the source
tenant?
For each internal user in the source tenant, cross-tenant synchronization creates a
federated external user (commonly used in B2B) in the target. It supports syncing
internal users. This includes internal users federated to other identity systems using
domain federation (such as Active Directory Federation Services ). It doesn't
support syncing external users.
Does cross-tenant synchronization use S ystem for Cross-Domain Identity Management
(SCIM)?
No. Currently, Microsoft Entra ID supports a SCIM client, but not a SCIM server. For
more information, see SCIM synchronization with Microsoft Entra ID .
Does cross-tenant synchronization support deprovisioning users?
Yes, when the below actions occur in the source tenant, the user will be soft
deleted in the target tenant.
Delete the user in the source tenant
Unassign the user from the cross-tenant synchronization configuration
Remove the user from a group that is assigned to the cross-tenant
synchronization configuration
An attribute on the user changes such that they do not meet the scoping filter
conditions defined on the cross-tenant synchronization configuration anymore
If the user is blocked from sign-in in the source tenant (accountEnabled = false)
they will be blocked from sign-in in the target. This is not a deletion, but an
updated to the accountEnabled property.
Users are not soft deleted from the target tenant in this scenario: Does cross-tenant synchronization support restoring users?
If the user in the source tenant is restored, reassigned to the app, meets the
scoping condition again within 30 days of soft deletion, it will be restored in the
target tenant.
IT admins can also manually restore the user directly in the target tenant.
How can I deprovision all the users that are currently in scope of cross-tenant
synchronization?
Unassign all users and / or groups from the cross-tenant synchronization
configuration. This will trigger all the users that were unassigned, either directly or
through group membership, to be deprovisioned in subsequent sync cycles. Please
note that the target tenant will need to keep the inbound policy for sync enabled
until deprovisioning is complete. If the scope is set to Sync all user s and gr oups ,
you will also need to change it to Sync only assigned user s and gr oups . The users
will be automatically soft deleted by cross-tenant synchronization. The users will be
automatically hard deleted after 30 days or you can choose to hard delete the
users directly from the target tenant. Y ou can choose to hard delete the users
directly in the target tenant or wait 30 days for the users to be automatically hard
deleted.
If the sync relationship is severed, are external users previously managed by cross-
tenant synchronization deleted in the target tenant?
No. No changes are made to the external users previously managed by cross-
tenant synchronization if the relationship is severed (for example, if the cross-
tenant synchronization policy is deleted).
Topologies for cross-tenant synchronization
Configure cross-tenant synchronizationNext steps Multitenant organization identity
provisioning for Microsoft 365
Article •04/24/2024
The multitenant organization capability is designed for organizations that own multiple
Microsoft Entra tenants and want to streamline intra-organization cross-tenant
collaboration in Microsoft 365. It's built on the premise of reciprocal provisioning of B2B
member users across multitenant organization tenants.
Teams external access and Teams shared channels excluded, Microsoft 365 people
search is typically scoped to within local tenant boundaries. In multitenant organizations
with increased need for cross-tenant coworker collaboration, it's recommended to
reciprocally provision users from their home tenants into the resource tenants of
collaborating coworkers.
The new Microsoft T eams experience improves upon Microsoft 365 people search and
Teams external access for a unified seamless collaboration experience. For this improved
experience to light up, the multitenant organization representation in Microsoft Entra ID
is required and collaborating users shall be provisioned as B2B members. For more
information, see Announcing more seamless collaboration in Microsoft T eams for
multitenant organizations .
Collaboration in Microsoft 365 is built on the premise of reciprocal provisioning of B2B
identities across multitenant organization tenants.
For example, say Annie in tenant A, Bob and Barbara in tenant B, and Charlie in tenant C
want to collaborate. Conceptually, these four users represent a collaborating user set of
four internal identities across three tenants.Microsoft 365 people search
New Microsoft Teams
Collaborating user set For people search to succeed, while scoped to local tenant boundaries, the entire
collaborating user set must be represented within the scope of each multitenant
organization tenant A, B, and C, in the form of either internal or B2B identities.
Depending on your organization’s needs, the collaborating user set may contain a
subset of collaborating employees, or eventually all employees.
One of the simpler ways to achieve a collaborating user set in each multitenant
organization tenant is for each tenant administrator to define their user contribution
and synchronization them outbound. T enant administrators on the receiving end should
accept the shared users inbound.
Administrator A contributes or shares Annie
Administrator B contributes or shares Bob and Barbara
Administrator C contributes or shares Charles
Sharing your users Microsoft 365 admin center facilitates orchestration of such a collaborating user set
across multitenant organization tenants. For more information, see Synchronize users in
multitenant organizations in Microsoft 365 .
Alternatively, pair-wise configuration of inbound and outbound cross-tenant
synchronization can be used to orchestrate such collating user set across multitenant
organization tenants. For more information, see What is a cross-tenant synchronization .
To ensure a seamless collaboration experience across the multitenant organization in
new Microsoft T eams, B2B identities are provisioned as B2B users of Member userT ype.
User synchr onization method Default userT ype pr oper ty
Synchronize users in multitenant organizations in
Microsoft 365Member
Remains Guest, if the B2B identity already
existed as Guest
Cross-tenant synchronization in Microsoft Entra ID Member
Remains Guest, if the B2B identity already
existed as Guest
B2B member users
ﾉExpand table From a security perspective, you should review the default permissions granted to B2B
member users. For more information, see Compare member and guest default
permissions .
To change the userT ype from Guest to Member (or vice versa), a source tenant
administrator can amend the attribute mappings , or a target tenant administrator can
change the userT ype if the property is not recurringly synchronized.
To unshare users, you deprovision users by using the user deprovisioning capabilities
available in Microsoft Entra cross-tenant synchronization. By default, when provisioning
scope is reduced while a synchronization job is running, users fall out of scope and are
soft deleted, unless T arget Object Actions for Delete is disabled. For more information,
see Deprovisioning and Define who is in scope for provisioning .
Plan for multitenant organizations in Microsoft 365
Set up a multitenant org in Microsoft 365Unsharing your users
Next steps Multitenant organization optional policy
templates
Article •04/23/2024
Administrators staying in control of their resources is a guiding principle for multitenant
organization collaboration. Cross-tenant access settings are required for each tenant-to-
tenant relationship. T enant administrators explicitly configure cross-tenant access
partner configurations and identity synchronization settings for partner tenants inside
the multitenant organization.
To help apply homogenous cross-tenant access settings to partner tenants in the
multitenant organization, the administrator of each tenant can configure optional cross-
tenant access settings templates dedicated to the multitenant organization. This article
describes how to use templates to preconfigure cross-tenant access settings that are
applied to any partner tenant newly joining the multitenant organization.
Within a multitenant organization, each pair of tenants must have bi-directional cross-
tenant access settings , for both, partner configuration and identity synchronization.
These settings provide the underlying policy framework for enabling trust and for
sharing users and applications.
When your tenant joins a new multitenant organization, or when a partner tenant joins
your existing multitenant organization, cross-tenant access settings to other partner
tenants in the enlarged multitenant organization, if they don't already exist, are
automatically generated in an unconfigured state. In an unconfigured state, these cross-
tenant access settings pass through the default settings .
Default cross-tenant access settings apply to all external tenants for which you haven't
created organization-specific customized settings. T ypically, these settings are
configured to be nontrusting. For example, cross-tenant trusts for multifactor
authentication and compliant device claims might be disabled and user and group
sharing in B2B direct connect or B2B collaboration might be disallowed.
In multitenant organizations, on the other hand, cross-tenant access settings are
typically expected to be trusting. For example, cross-tenant trusts for multifactor
authentication and compliant device claims might be enabled and user and group
sharing in B2B direct connect or B2B collaboration might be allowed.Autogeneration of cross-tenant access setting s While the autogeneration of cross-tenant access settings for multitenant organization
partner tenants in and of itself doesn't change any authentication or authorization policy
behavior, it allows your organization to easily customize the cross-tenant access settings
for partner tenants in the multitenant organization on a per-tenant basis.
As previously described, in multitenant organizations, cross-tenant access settings are
typically expected to be trusting. For example, cross-tenant trusts for multifactor
authentication and compliant device claims might be enabled and user and group
sharing in B2B direct connect or B2B collaboration might be allowed.
While autogeneration of cross-tenant access settings, per previous section, guarantees
the existence of cross-tenant access settings for every multitenant organization partner
tenant, further maintenance of the cross-tenant access settings for multitenant
organization partner tenants is conducted individually, on a per-tenant basis.
To reduce the workload for administrators at the time of multitenant organization
formation, you can optionally use policy templates for preemptive configuration of
cross-tenant access settings. These template settings are applied at the time of your
tenant joins a multitenant organization to all external multitenant organization partner
tenants as well as at the time of any partner tenant joins your existing multitenant
organization to such new partner tenant.
Enablement or configuration of the optional policy templates , at the time of a partner
tenant joins a multitenant organization, preemptively amend the corresponding cross-
tenant access settings , for both partner configuration and identity synchronization.
As an example, consider the actions of the administrators for an anticipated multitenant
organization with three tenants, A, B, and C.
The administrators of all three tenants enable and configure their respective
optional policy templates to enable cross-tenant trusts for multifactor
authentication and compliant device claims and to allow user and group sharing in
B2B direct connect and B2B collaboration.
Administrator A creates the multitenant organization and adds tenants B and C as
pending tenants to the multitenant organization.
Administrator B joins the multitenant organization. Cross-tenant access settings in
tenant A for partner tenant B are amended, according to tenant A policy template
settings. Vice versa, cross-tenant access settings in tenant B for partner tenant A
are amended, according to tenant B policy template settings.Policy templates at multitenant organization
formation Administrator C joins the multitenant organization. Cross-tenant access settings in
tenants A (and B) for partner tenant C are amended, according to tenant A (and B)
policy template settings. Similarly, cross-tenant access settings in tenant C for
partner tenants A and B are amended, according to tenant C policy template
settings.
Following the formation of this multitenant organization of three tenants, the
cross-tenant access settings of all tenant pairs in the multitenant organization have
preemptively been configured.
In summary, configuration of the optional policy templates enable you to
homogeneously initialize cross-tenant access settings across your multitenant
organization, while maintaining maximum flexibility to customize your cross-tenant
access settings as needed on a per-tenant basis.
To stop using the policy templates, you can reset them to their default state. For more
information, see Configure multitenant organization templates .
To provide administrators with further configurability, you can choose when cross-
tenant access settings are to be amended according to the policy templates. For
example, you can choose to apply the policy templates for the following tenants when a
tenant joins a multitenant organization:
Tenant Descr iption
Only new partner tenants Tenants whose cross-tenant access settings are autogenerated
Only existing partner tenants Tenants who already have cross-tenant access settings
All partner tenants Both new partner tenants and existing partner tenants
No partner tenants Policy templates are effectively disabled
In this context, new partners refer to tenants for which you haven't yet configured cross-
tenant access settings, while existing partners refer to tenants for which you have
already configured cross-tenant access settings. This scoping is specified with the
templateApplicationLevel property on the cross-tenant access partner configuration
template and the templateApplicationLevel property on the cross-tenant access
identity synchronization template .Policy template scoping and additional
properties
ﾉExpand table Finally, in terms of interpretation of template property values, any template property
value of null has no effect on the corresponding property value in the targeted cross-
tenant access settings, while a defined template property value causes the
corresponding property value in the targeted cross-tenant access settings to be
amended in accordance with the template. The following table illustrates how template
property values are being applied to corresponding cross-tenant access setting values.
Templat e Value Initial P artner Settings V alue
(Befor e joining multit enant or g)Final P artner Settings V alue
(After joining multit enant or g)
null
The partner tenant that left the multitenant organization must re-examine and amend
accordingly the cross-tenant access settings for all former multitenant organization
partner tenants as well as consider resetting the two policy templates for cross-tenant
access settings.
Configure multitenant organization templates using the Microsoft Graph APINext steps Limitations in multitenant organizations
Article •04/24/2024
This article describes limitations to be aware of when you work with multitenant
organization functionality across Microsoft Entra ID and Microsoft 365. T o provide
feedback about the multitenant organization functionality on UserV oice, see Microsoft
Entra UserV oice . We watch UserV oice closely so that we can improve the service.
The limitations described in this article have the following scope.
Scope Descr iption
In scope - Microsoft Entra administrator limitations related to multitenant organizations
to support seamless collaboration experiences in new T eams, with reciprocally
provisioned B2B members
Related scope - Microsoft 365 admin center limitations related to multitenant organizations Synchronization jobs created with Microsoft Entra ID will not appear in the
Microsoft 365 admin center.
If you created your synchronization job in the Microsoft 365 admin center, do
not modify the synchronization job name using Microsoft Entra ID, otherwise it
will no longer appear in the admin center.
You might adjust the attribute mappings to match your organizations' needs.
By default, new B2B users are provisioned as B2B members, while existing B2B
guests remain B2B guests.
You can opt to convert B2B guests into B2B members by setting Apply this
mapping to Always .
If you're using Microsoft Entra cross-tenant synchronization to provision your
users, rather than the Microsoft 365 admin center share users functionality,
Microsoft 365 admin center indicates an Outbound sync status of Not configur ed.
This is expected behavior. Currently, Microsoft 365 admin center only shows the
status of Microsoft Entra cross-tenant synchronization jobs created and managed
by Microsoft 365 admin center and doesn't display Microsoft Entra cross-tenant
synchronizations created and managed in Microsoft Entra ID.
If you view Microsoft Entra cross-tenant synchronization in Microsoft Entra admin
center, after adding tenants to or after joining a multitenant organization in
Microsoft 365 admin center, you'll see a cross-tenant synchronization
configuration with the name MTO_Sync_
If you followed the correct sequence to create a multitenant organization and add
a tenant to the multitenant organization, and the added tenant's join request
keeps failing, submit a support request in the Microsoft Entra or Microsoft 365
admin center.
In ShareP oint OneDrive , the promotion of B2B guests to B2B members might not
happen automatically. If faced with a user type mismatch between Microsoft Entra
ID and ShareP oint OneDrive, try Set-SPUser [-S yncFromAD] .
In ShareP oint OneDrive user interfaces, when sharing a file with People in F abrikam,
the current user interfaces might be counterintuitive, because B2B members in
Fabrikam from Contoso count towards People in F abrikam.
In Microsoft Forms , B2B member users might not be able to access forms.
In Microsoft P ower BI , B2B member users are not yet supported. B2B guest users
can continue to access P ower BI dashboards.
In Microsoft P ower Apps , Microsoft Dynamics 365 , and related workloads, B2B
member users may have restricted functionality. For more information, see Invite
users with Microsoft Entra B2B collaboration .
The promotion of B2B guests to B2B members represents a strategic decision by
multitenant organizations to consider B2B members as trusted users of the
organization. R eview the default permissions for B2B members.
To promote B2B guests to B2B members, a source tenant administrator can amend
the attribute mappings , or a target tenant administrator can change the userT ype if
the property is not recurringly synchronized.
As your organization rolls out the multitenant organization functionality including
provisioning of B2B users across multitenant organization tenants, you might want
to provision some users as B2B guests, while provision others users as B2B
members. T o achieve this, you might want to establish two Microsoft Entra cross-
tenant synchronization configurations in the source tenant, one with userT ype
attribute mappings configured to B2B guest, and another with userT ype attribute
mappings configured to B2B member, each with Apply this mapping set toMicrosoft apps
B2B users or B2B members Always . By moving a user from one configuration's scope to the other, you can
easily control who will be a B2B guest or a B2B member in the target tenant.
As part of a multitenant organization, reset redemption for an already redeemed
B2B user is currently disabled.
The at-scale provisioning of B2B users might collide with contact objects. The
handling or conversion of contact objects is currently not supported.
Using Microsoft Entra cross-tenant synchronization to target hybrid identities that
have been converted to B2B users has not been tested in source of authority
conflicts and is not supported.
By default, when provisioning scope is reduced while a synchronization job is
running, users fall out of scope and are soft deleted, unless Target Object Actions
for Delete is disabled. For more information, see Deprovisioning and Define who is
in scope for provisioning .
Currently, SkipOutOfScopeDeletions works for application provisioning jobs, but
not for Microsoft Entra cross-tenant synchronization. T o avoid soft deletion of
users taken out of scope of cross-tenant synchronization, set Target Object Actions
for Delete to disabled.
Known issues for provisioning in Microsoft Entra IDCross-tenant synchronization deprovisioning
Next steps Topologies for cross-tenant
collaboration
Article •11/03/2023
Organizations often find themselves managing multiple tenants due to mergers and
acquisitions, regulatory requirements, or administrative boundaries. R egardless of your
scenario, Microsoft Entra offers a flexible and ready-to-use solution for provisioning
accounts across tenants and facilitating seamless collaboration. Microsoft Entra
accommodates the following three models and can adapt to your evolving
organizational needs.
The hub and spoke topology presents two common patterns:
Option 1 (application hub): In this option, you can integrate commonly used
applications into a central hub tenant that users from across the organization can
access.
Option 2 (user hub): Alternatively, option 2 centralizes all your users in a single
tenant and provisions them into spoke tenants where resources are managed.
Let's examine a few real-world scenarios and see how they align with each of these
models.
During mergers and acquisitions, the ability to quickly enable collaboration is crucial,
allowing businesses to function cohesively while complex IT decisions are being made.
For instance, when a newly acquired company's employees need immediate access to
applications such as the internal help desk ticketing system or benefits application,
cross-tenant synchronization proves invaluable. This synchronization process allows
users from the acquired company to be provisioned into the application hub from day
one, granting them access to SaaS apps, on-premises applications, and other cloud
resources. Within the target tenant, admins can set up access packages to grant time
limited access to additional applications such as Salesforce and Amazon W eb ServicesHub and spoke＂
Mesh＂
Just-in-time＂
Hub and spoke
Mergers and acquisitions (application hub) that contain business critical data. The following diagram shows recently acquired
tenants on the left and their users being provisioned into the parent company's tenant,
which grants users access to the necessary resources.
As organizations scale their usage of Azure, they often create dedicated tenants for
managing critical Azure resources. Meanwhile, they rely on a central hub tenant for user
provisioning. This model empowers administrators in the hub tenant to establish central
security and governance policies while granting development teams greater autonomy
and agility to deploy required Azure resources. Cross-tenant synchronization supports
this topology by enabling administrators to provision a subset of users into the spoke
tenants and manage the lifecycle of those users.Separate collaboration and resource tenants
(user hub) While some companies centralize their users within a single tenant, others have a more
decentralized structure with applications, HR systems, and Active Directory domains
integrated into each tenant. Cross-tenant synchronization offers the flexibility to choose
which users are provisioned into each tenant.
In this scenario, each tenant represents a different company within the same parent
organization. Administrators in each tenant choose a subset of users to provision into
the target tenant. This solution provides flexibility for each tenant to operate
independently, while facilitating collaboration when users need access to critical
resources.Mesh
Collaborate within a portfolio company (partial-mesh) Cross-tenant synchronization is one way. An internal member user can be synchronized
into multiple tenants as an external user. When the topology shows a synchronization
going in both directions, it's a distinct set of users in each direction and each arrow is a
separate configuration.
In this scenario, the organization has designated different tenants for each business unit.
The business units work closely together, in particular using Microsoft T eams. As a result,
each tenant has chosen to provision all users across the four tenants in the organization.
As new users join the company or leave, the provisioning service takes care of creating
and deleting users. The organization has also configured a multitenant organization that
includes all four tenants. Now when users need to collaborate in T eams, they're able to
easily find users across the company and start chats and meetings with those users.Collaborate across business units (full-mesh) While the scenarios discussed so far cover collaboration within an organization, there
are cases where cross-organization collaboration is vital. This could be in the context of
joint ventures or organizations of independent legal entities. By employing connected
organizations and entitlement management, you can define policies for accessing
resources across connected organizations and enable users to request access to the
resources they need.
Consider Contoso and Litware, separate organizations engaged in a multi-year joint
venture. They need to collaborate closely. Administrators at Contoso have defined
access packages containing the resources required by Litware users. When a new
Litware employee needs access to Contoso's resources, they can request access to the
access package. Upon approval, they are provisioned with the necessary resources.
Access can be time-limited and subject to periodic review to ensure compliance with
Contoso's governance requirements.
The following diagram shows how two organizations can just-in-time collaborate by
using connected organizations and entitlement management.Just-in-time
Joint ventures Feedb ack
Was this p age help ful?
Provide product feedback |Get help at Microsoft Q&A
What is cross-tenant synchronization?
Configure cross-tenant synchronizationNext steps
YesNo Governance and cross-tenant
synchronization
Article •03/21/2024
Cross-tenant synchronization is a flexible and ready-to-use solution to provision
accounts and facilitate seamless collaboration across tenants in an organization. Cross-
tenant synchronization automatically manages user identity lifecycle across tenants. It
provisions, synchronizes, and deprovisions users in the scope of synchronization from
source tenants.
This article describes how Microsoft Entra ID Governance customers can use cross-
tenant synchronization to manage identity and access lifecycles across multitenant
organizations.
In this example, Contoso is a multitenant organization with three production Microsoft
Entra tenants. Contoso is deploying cross-tenant synchronization and Microsoft Entra ID
Governance features to address the following scenarios:
Manage employee identity lifecycles across multiple tenants
Use workflows to automate lifecycle processes for employees that originate in
other tenants
Assign resource access automatically to employees that originate in other tenants
Allow employees to request access to resources in multiple tenants
Review the access of synchronized users
From a cross-tenant synchronization perspective, Contoso Europe, Middle East, and
Africa (Contoso EMEA) and Contoso United S tates (Contoso US) are source tenants and
Contoso is a target tenant. The following diagram illustrates the topology.Deployment example This supported topology for cross-tenant synchronization is one of many in Microsoft
Entra ID. T enants can be a source tenant, a target tenant, or both. In the following
sections, learn how cross-tenant synchronization and Microsoft Entra ID Governance
features address several scenarios.
Cross-tenant synchronization in Microsoft Entra ID automates creating, updating, and
deleting B2B collaboration users.
When organizations create, or provision, a B2B collaboration user in a tenant, user
access depends partly on how the organization provisioned them: Guest or Member
user type. When you select user type, consider the various properties of a Microsoft
Entra B2B collaboration user . The Member user type is suitable if users are part of the
larger multitenant organization and need member-level access to resources in the
organizational tenants. Microsoft T eams requires the Member user type in multitenant
organizations .
By default, cross-tenant synchronization includes commonly used attributes on the user
object in Microsoft Entra ID. The following diagram illustrates this scenario.Manage employee lifecycles across tenants Organizations use the attributes to help create dynamic membership of groups and
access packages in the source and target tenant. Some Microsoft Entra ID features have
user attributes to target, such as lifecycle workflow user scoping.
To remove, or deprovision, a B2B collaboration user from a tenant automatically stops
access to resources in that tenant. This configuration is relevant when employees leave
an organization.
Microsoft Entra ID lifecycle workflows are an identity governance feature to manage
Microsoft Entra users. Organizations can automate joiner, mover, and leaver processes.
With cross-tenant synchronization, multitenant organizations can configure lifecycle
workflows to run automatically for B2B collaboration users it manages. For example,
configure a user onboarding workflow, triggered by the createdDateTime event user
attribute, to request access package assignment for new B2B collaboration users. Use
attributes such as userType and userPrincipalName to scope lifecycle workflows for
users homed in other tenants the organization owns.
Multitenant organizations can ensure B2B collaboration users have access to shared
resources in a target tenant. Users can request access, where needed. In the following
scenarios, see how the identity governance feature, entitlement management access
packages govern resource access.Automate lifecycle processes with workflows
Govern synchronized user access with access
packages
Automatically assign access in target tenants to
employees from source tenants The term birthright assignment refers to automatically granting resource access based
on one or more user properties. T o configure birthright assignment, create automatic
assignment policies for access packages in entitlement management and configure
resource roles to grant shared resource access.
Organizations manage cross-tenant synchronization configuration in the source tenant.
Therefore, organizations can delegate resource access management to other source
tenant administrators for synchronized B2B collaboration users:
In the source tenant, administrators configure cross-tenant synchronization
attribute mappings for the users that require cross-tenant resource access
In the target tenant, administrators use attributes in automatic assignment policies
to determine access package membership for synchronized B2B collaboration
users
To drive automatic assignment policies in the target tenant, synchronize default
attribute mappings, such as department or map directory extensions, in the source
tenant.
With identity governance access package policies, multitenant organizations can allow
B2B collaboration users, created by cross-tenant synchronization, to request access to
shared resources in a target tenant. This process is useful if employees need just-in-time
(JIT) access to a resource that another tenant owns.
Access reviews in Microsoft Entra ID enable organizations to manage group
memberships, access to enterprise applications, and role assignments. R egularly review
user access to ensure the right people have access.
When resource access configuration doesn’t automatically assign access, such as with
dynamic groups or access packages, configure access reviews to apply the results to
resources upon completion. The following sections describe how multitenant
organizations can configure access reviews for users across tenants in source and target
tenants.Enable source-tenant employees to request access to
target-tenant shared resources
Review synchronized-user access
Review source-tenant user access Multitenant organizations can include internal users in access reviews. This action
enables access recertification in source tenants that synchronizes users. Use this
approach for regular review of security groups assigned to cross-tenant synchronization.
Therefore, ongoing B2B collaboration access to other tenants has approval in the user
home tenant.
Use access reviews of users in source tenants to avoid potential conflicts between cross-
tenant synchronization and access reviews that remove denied users upon completion.
Organizations can include B2B collaboration users in access reviews, including users
provisioned by cross-tenant synchronization in target tenants. This option enables
access recertification of resources in target tenants. Although organizations can target
all users in access reviews, guest users can be explicitly targeted if necessary.
For organizations that synchronize B2B collaboration users, typically Microsoft doesn’t
recommend removing denied guest users automatically from access reviews. Cross-
tenant synchronization reprovisions the users if they're in the synchronization scope.
Multitenant organizations and Microsoft 365
Multitenant organization templates
Topologies for cross-tenant synchronizationReview target-tenant user access
Next steps Govern access for security operations
center (SOC) teams in a multitenant
environment
Article •05/02/2024
Managing multitenant environments can add another layer of complexity when it comes
to keeping up with the ever-evolving security threats facing your enterprise. Navigating
across multiple tenants can be time consuming and reduce the overall efficiency of
security operation center (SOC) teams. Multitenant management in Microsoft Defender
XDR provides security operation teams with a single, unified view of all the tenants they
manage. This view enables teams to quickly investigate incidents and perform advanced
hunting across data from multiple tenants, improving their security operations.
Microsoft Entra ID Governance enables you to govern the access and lifecycle of the
users who are members of the SOC teams and threat hunter teams. This document
explores:
The controls you can put in place for SOC teams to securely access resources
across tenants.
Example topologies for how you can implement your lifecycle and access controls.
Deployment considerations (roles, monitoring, APIs).
Microsoft Entra provides the controls needed to govern the lifecycle of a SOC user and
to securely provide access to the resources they need. In this document, the term source
tenant refers to where the SOC users originate and authenticate against. T arget tenant
refers to the tenant that they're investigating when there's an incident. Organizations
have multiple target tenants due to mergers and acquisitions, aligning tenants with
business units, and aligning tenants with geos.
Entitlement management, thr ough access p ackages and connect ed or ganizations
allows the target tenant administrator to define collections of resources (ex: app roles,
directory roles, and groups) that users from the source tenant can request access to. If
the user is approved for the resources they need, but don’t yet have a B2B account,
entitlement management will automatically create a B2B account for the user in theManage the lifecycle and access of a SOC user
Lifecycle control target tenant. When they don't have any remaining entitlements in the target tenant,
their B2B account will automatically be removed.
Learn more
Cross-t enant synchr onization allows the source tenant to automate creating, updating,
and deleting B2B users across tenants in an organization.
Learn more
Comp aring entitlement management and cr oss-t enant synchr onization
Capability Entitlement management Cross-t enant
synchr onization
Create users in the target tenant ● ●
Update users in the target tenant when
their attributes change in the source
tenant●
Delete users ● ●
Assign users to groups, directory roles,
app roles●
Attributes of the user in the target
tenantMinimal, supplied by user
themself at request timeSynchronized from the
source tenant
You can use entitlement management and cross-tenant access policies to control access
to resources across tenants. Entitlement management will assign the right users to the
right resources, while cross-tenant access policies and conditional access together
perform the necessary run-time checks to ensure the right users are accessing the right
resources.
Entitlement management
Assigning Microsoft Entra roles through entitlement management access packages
helps to efficiently manage role assignments at scale and improves the role assignment
lifecycle. It provides a flexible request and approval process for gaining access to
directory roles, app roles, and groups while also enabling automatic assignment to
resources based on user attributes.ﾉExpand table
Access control Learn more
Cross-t enant access policies
External identities cross-tenant access settings manage how you collaborate with other
Microsoft Entra organizations through B2B collaboration. These settings determine both
the level of inbound access users in external Microsoft Entra organizations have to your
resources, and the level of outbound access your users have to external organizations.
Learn more
This section describes how you can use tools such as cross-tenant synchronization,
entitlement management, cross-tenant access policies, and conditional access together.
In both topologies, the target tenant admin has full control over access to resources in
the target tenant. They differ in who initiates provisioning and deprovisioning.
In topology 1, the source tenant configures entitlement management and cross-tenant
synchronization to provision users into the target tenant. Then, the administrator of the
target tenant configures access packages to provide access to the necessary directory
roles, group, and app roles in the target tenant.
Steps t o configur e topology 1Deployment topologies
Topology 1
Steps t o configur e topology 2 provisioned into their tenant and perform the necessary approvals in their tenant,
topology 2 will best meet their needs.
Monit oring
Actions performed by a SOC analyst in Microsoft Entra are audited in the Microsoft
Entra tenant that they're working in. Organizations can maintain an audit trail of actions
performed, generate alerts when specific actions are performed, and analyze actions
performed by pushing audit logs into Azure Monitor.
Learn more
Actions performed by a SOC analyst in Microsoft Defender are also audited.
Learn more
Scaling deployment with P owerShell / APIs
Every step that is configured through the user interface in Microsoft Entra has
accompanying Microsoft Graph APIs and P owerShell commandlets, enabling you to
deploy your desired policies/configuration across the tenants in your organization.
Capability Micr osoft Graph API PowerShell
Cross-tenant synchronization Link Link
Entitlement management Link Link
Cross-tenant access policies Link Link
Role-b ased access contr ol
Configuring the capabilities described in topology 1 and topology 2 require the
following roles:
Configuring cross-tenant access settings - Security Administrator
Configuring cross-tenant synchronization - Hybrid Identity Administrator
Configuring entitlement management - Identity Governance Administrator
Microsoft Defender supports both built-in roles such as Security R eader, Security
Administrator, and Security Operator and custom roles.Deployment considerations
ﾉExpand table What is cross-tenant synchronization?
What is entitlement management?
Multitenant management in Defender XDRNext steps Known issues for provisioning in
Microsoft Entra ID
Article •02/14/2024
This article discusses known issues to be aware of when you work with app provisioning
or cross-tenant synchronization. T o provide feedback about the application provisioning
service on UserV oice, see Microsoft Entra application provision UserV oice . We watch
UserV oice closely so that we can improve the service.
After you've configured provisioning for the first time, you'll notice that the provisioning
mode has switched from manual to automatic. Y ou can't change it back to manual. But
you can turn off provisioning through the UI. Turning off provisioning in the UI
effectively does the same as setting the dropdown to manual.
The attributes SamAccountName and userT ype aren't available as a source attribute by
default. Extend your schema to add the attributes. Y ou can add the attributes to the list
of available source attributes by extending your schema. T o learn more, see Missing
source attribute .
Extensions to your schema can sometimes be missing from the source attribute
dropdown in the UI. Go into the advanced settings of your attribute mappings and
７ Note
This article isn't a comprehensive list of known issues. If you know of an issue that
isn't listed, provide feedback at the bottom of the page.
Auth orization
Unable to change provisioning mode back to manual
Attribute mappings
Attribute SamAccountName or userType not available as a source
attribute
Source attribute dropdown missing for schema extension manually add the attributes. T o learn more, see Customize attribute mappings .
Microsoft Entra ID currently can't provision null attributes. If an attribute is null on the
user object, it will be skipped.
Attribute-mapping expressions can have a maximum of 10,000 characters.
The appR oleAssignments , userT ype, and accountExpir es attributes aren't supported as
scoping filters.
Multivalue directory extensions can't be used in attribute mappings or scoping filters.
Provisioning passwords isn't supported.
Provisioning nested groups isn't supported.
Provisioning to B2C tenants isn't supported because of the size of the tenants.
Not all provisioning apps are available in all clouds. For example, Atlassian isn't yet
available in the Government cloud. W e're working with app developers to onboard
their apps to all clouds.
If you create an app registration, the corresponding service principal in enterprise apps
won't be enabled for automatic user provisioning. Y ou'll need to either request the app
be added to the gallery, if intended for use by multiple organizations, or create a second
non-gallery app for provisioning.Null attribute can't be provisioned
Maximum characters for attribute-mapping expressions
Unsupported scoping filters
Multivalue directory extensions
Service issues
Unsupported scenarios
Automatic provisioning isn't available on my OIDC-based
application If a user and their manager are both in scope for provisioning, the service provisions the
user and then updates the manager. If on day one the user is in scope and the manager
is out of scope, we'll provision the user without the manager reference. When the
manager comes into scope, the manager reference won't be updated until you restart
provisioning and cause the service to reevaluate all the users again.
The time between provisioning cycles is currently not configurable.
The app provisioning service isn't aware of changes made in external apps. So, no action
is taken to roll back. The app provisioning service relies on changes made in Microsoft
Entra ID.
After you change scope from Sync All to Sync Assigned , make sure to also perform a
restart to ensure that the change takes effect. Y ou can do the restart from the UI.
When you set provisioning to enabled = off or select Stop, the current provisioning
cycle continues running until completion. The service stops executing any future cycles
until you turn provisioning on again.
When a group is in scope and a member is out of scope, the group will be provisioned.
The out-of-scope user won't be provisioned. If the member comes back into scope, the
service won't immediately detect the change. R estarting provisioning addresses the
issue. P eriodically restart the service to ensure that all users are properly provisioned.
The Global R eader role is unable to read the provisioning configuration. Create a custom
role with the microsoft.directory/applications/synchronization/standard/readManager isn't provisioned
The provisioning interval is fixed
Changes not moving from target app to Microsoft Entra ID
Switching from Sync All to Sync Assigned not working
Provisioning cycle continues until completion
Member of group not provisioned
Global Reader permission in order to read the provisioning configuration from the Microsoft Entra
admin center.
Credentials, including the secret token, notification email, and SSO certificate
notification emails together have a 1KB limit in the Microsoft Azure Government Cloud.
The following information is a current list of known limitations with the Microsoft Entra
ECMA Connector Host and on-premises application provisioning.
The following applications and directories aren't yet supported.
When a user is managed by Microsoft Entra Connect, the source of authority is on-
premises Active Directory Domain Services. So, user attributes can't be changed in
Microsoft Entra ID. This preview doesn't change the source of authority for users
managed by Microsoft Entra Connect.
Attempting to use Microsoft Entra Connect and the on-premises provisioning to
provision groups or users into Active Directory Domain Services can lead to
creation of a loop, where Microsoft Entra Connect can overwrite a change that was
made by the provisioning service in the cloud. Microsoft is working on a dedicated
capability for group or user writeback. Upvote the UserV oice feedback on this
website to track the status of the preview. Alternatively, you can use Microsoft
Identity Manager for user or group writeback from Microsoft Entra ID to Active
Directory.
By using on-premises provisioning, you can take a user already in Microsoft Entra ID and
provision them into a third-party application. You can 't bring a us er int o the dir ectory
from a thir d-party application. Customers will need to rely on our native HR integrations,
Microsoft Entra Connect, Microsoft Identity Manager, or Microsoft Graph, to bring users
into the directory.Microsoft Azure Government Cloud
On-premises application provisioning
Application and directories
Active Directory Domain Services (user or group writeback from
Microsoft Entra ID by using the on-premises provisioning preview)
Microsoft Entra ID The following attributes and objects aren't supported:
Multivalued attributes.
Reference attributes (for example, manager).
Groups.
Complex anchors (for example, ObjectT ypeName+UserName).
Attributes that have characters such as "." or "["
Binary attributes.
On-premises applications are sometimes not federated with Microsoft Entra ID and
require local passwords. The on-premises provisioning preview doesn't support
password synchronization. Provisioning initial one-time passwords is supported.
Ensure that you're using the Redact function to redact the passwords from the
logs. In the SQL and LD AP connectors, the passwords aren't exported on the initial
call to the application, but rather a second call with set password.
The Microsoft Entra ECMA Connector Host currently requires either an SSL certificate to
be trusted by Azure or the provisioning agent to be used. The certificate subject must
match the host name the Microsoft Entra ECMA Connector Host is installed on.
The Microsoft Entra ECMA Connector Host currently doesn't support anchor attribute
changes (renames) or target systems, which require multiple attributes to form an
anchor.
The attributes that the target application supports are discovered and surfaced in the
Microsoft Entra admin center in Attribut e Mappings . Newly added attributes will
continue to be discovered. If an attribute type has changed, for example, string to
Boolean, and the attribute is part of the mappings, the type won't change automatically
in the Microsoft Entra admin center. Customers will need to go into advanced settings in
mappings and manually update the attribute type.Attributes and objects
SSL certificates
Anchor attributes
Attribute discovery and mapping
Provisioning agent The agent doesn't currently support auto update for the on-premises application
provisioning scenario. W e're actively working to close this gap and ensure that
auto update is enabled by default and required for all customers.
The same provisioning agent can't be used for on-premises app provisioning and
cloud sync / HR- driven provisioning.
How provisioning worksNext steps Configure a multitenant organization
using PowerShell or Microsoft Graph
API
Article •04/24/2024
This article describes the key steps to configure a multitenant organization using
Microsoft Graph P owerShell or Microsoft Graph API. This article uses an example owner
tenant named Cairo and two member tenants named Berlin and Athens .
If you instead want to use the Microsoft 365 admin center to configure a multitenant
organization, see Set up a multitenant org in Microsoft 365 and Join or leave a
multitenant organization in Microsoft 365 . To learn how to configure Microsoft T eams
for your multitenant organization, see The new Microsoft T eams desktop client .
Owner t enant
For license information, see License requirements .
Security Administrator role to configure cross-tenant access settings and templates
for the multitenant organization.
Global Administrator role to consent to required permissions.
Prerequisites Member t enant
For license information, see License requirements .
Security Administrator role to configure cross-tenant access settings and templates
for the multitenant organization.
Global Administrator role to consent to required permissions.
Owner t enant Owner t enant Owner t enant Owner t enant
By default, tenants added to the multitenant organization are member tenants.
Optionally, you can change them to owner tenants, which allow them to add other
tenants to the multitenant organization. Y ou can also change an owner tenant to a
member tenant. In the owner tenant, use the Update-
MgBetaT enantR elationshipMultiT enantOrganizationT enant command to
change a member tenant to an owner tenant.
PowerShellAddedByTenantId :
Use the Get-MgBetaT enantR elationshipMultiT enantOrganizationT enant
command to verify the change.
PowerShell
Output
Owner t enant
You can remove any member tenant, including your own. Y ou can't remove owner
tenants. Also, you can't remove the original creator tenant, even if it has been changed
from owner to member.Update-MgBetaTenantRelationshipMultiTenantOrganizationTenant -
MultiTenantOrganizationMemberId $MemberTenantIdB -Role "Owner" |
Format-List
Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant -
MultiTenantOrganizationMemberId $MemberTenantIdB | Format-List
AddedByTenantId :
In the owner tenant, use the Remove-
MgBetaT enantR elationshipMultiT enantOrganizationT enant command to
remove any member tenant. This operation takes a few minutes.
PowerShell Use the Get-MgBetaT enantR elationshipMultiT enantOrganizationT enant
command to verify the change.
PowerShell
After the remove command completes, the output is similar to the following.
This is an expected error message. It indicates that the tenant has been
removed from the multitenant organization.
Output
Member t enant
The Cairo tenant created a multitenant organization and added the Berlin and Athens
tenants. In these steps, you sign in to the Berlin tenant and join the multitenant
organization created by Cairo.Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -
MultiTenantOrganizationMemberId
Start P owerShell. PowerShell
Output Use the Get-MgBetaT enantR elationshipMultiT enantOrganizationT enant
command to check the multitenant organization itself. It should reflect the
join operation.
PowerShell
OutputGet-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest |
Format-List
AddedByTenantId :
To allow for asynchronous processing, wait up to 2 hour s before joining a
multitenant organization is completed.
Member t enant
You can leave a multitenant organization that you have joined. The process for removing
your own tenant from the multitenant organization is the same as the process for
removing another tenant from the multitenant organization.
If your tenant is the only multitenant organization owner, you must designate a new
tenant to be the multitenant organization owner. For steps, see Step 4: (Optional)
Change the role of a tenant .
In the tenant, use the Remove-
MgBetaT enantR elationshipMultiT enantOrganizationT enant command to
remove the tenant. This operation takes a few minutes.
PowerShellRole : owner
State : active
TenantId :
Owner t enant
You delete a multitenant organization by removing all tenants. The process for removing
the final owner tenant is the same as the process for removing all other member
tenants.
In the final owner tenant, use the Remove-
MgBetaT enantR elationshipMultiT enantOrganizationT enant command to
remove the tenant. This operation takes a few minutes.
PowerShell
Set up a multitenant org in Microsoft 365
Synchronize users in multitenant organizations in Microsoft 365
The new Microsoft T eams desktop client
Configure multitenant organization templates using the Microsoft Graph APIPowerShell
Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -
MultiTenantOrganizationMemberId $OwnerTenantId
Next steps Configure mu ltitenant organization
policy templates using the Microsoft
Graph API
Article •04/24/2024
This article describes how to configure a policy template for your multitenant
organization.
For license information, see License requirements .
Security Administrator role to configure cross-tenant access settings and templates
for the multitenant organization.
Global Administrator role to consent to required permissions.
The cross-tenant access partner configuration handles trust settings and automatic user
consent settings between partner tenants. For example, you can use these settings to
trust multifactor authentication claims for inbound users from the target partner tenant.
With the template in an unconfigured state, partner configurations for partner tenants in
the multitenant organization won't be amended, with all trust settings passed through
from default settings. However, if you configure the template, then partner
configurations will be amended corresponding to the policy template.
To specify which trust settings and automatic user consent settings to apply to your
policy template, use the Update multiT enantOrganizationP artnerConfigurationT emplate
API. If you create or join a multitenant organization using the Microsoft 365 admin
center, this configuration is handled automatically.
Request
HTTPPrerequisites
Cross-tenant access policy partner template
Configure inbound and outbound automatic redemption
PATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationPartnerConfiguration To apply this template only to new multitenant organization members and exclude
existing partners, set the templateApplicationLevel parameter to new partners only.
Request
HTTP
To disable the template completely, set the templateApplicationLevel parameter to null.
Request
HTTP{
"inboundTrust" : {
"isMfaAccepted" : true,
"isCompliantDeviceAccepted" : true,
"isHybridAzureADJoinedDeviceAccepted" : true
},
"automaticUserConsentSettings" : {
"inboundAllowed" : true,
"outboundAllowed" : true
},
"templateApplicationLevel" : "newPartners,existingPartners"
}
Disable the template for existing partners
PATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationPartnerConfiguration
{
"inboundTrust" : {
"isMfaAccepted" : true,
"isCompliantDeviceAccepted" : true,
"isHybridAzureADJoinedDeviceAccepted" : true
},
"automaticUserConsentSettings" : {
"inboundAllowed" : true,
"outboundAllowed" : true
},
"templateApplicationLevel" : "newPartners"
}
Disable the template completely To reset the template to its default state (decline all trust and automatic user consent),
use the multiT enantOrganizationP artnerConfigurationT emplate: resetT oDefaultSettings
API.
HTTP
The identity synchronization policy governs cross-tenant synchronization , which allows
you to share users and groups across tenants in your organization. Y ou can use these
settings to allow inbound user synchronization. With the template in an unconfigured
state, the identity synchronization policy for partner tenants in the multitenant
organization won't be amended. However, if you configure the template, then the
identity synchronization policy will be amended corresponding to the policy template.
To allow inbound user synchronization in the policy template, use the Update
multiT enantOrganizationIdentityS yncPolicyT emplate API. If you create or join aPATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationPartnerConfiguration
{
"inboundTrust" : {
"isMfaAccepted" : true,
"isCompliantDeviceAccepted" : true,
"isHybridAzureADJoinedDeviceAccepted" : true
},
"automaticUserConsentSettings" : {
"inboundAllowed" : true,
"outboundAllowed" : true
},
"templateApplicationLevel" : ""
}
Reset the template
POST
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationPartnerConfiguration/resetToDefaultSettings
Cross-tenant synchronization template
Configure inbound user synchronization multitenant organization using the Microsoft 365 admin center, this configuration is
handled automatically.
Request
HTTP
To apply this template only to new multitenant organization members and exclude
existing partners, set the templateApplicationLevel parameter to new partners only.
Request
HTTP
To disable the template completely, set the templateApplicationLevel parameter to null.
Request
HTTPPATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationIdentitySynchronization
{
"userSyncInbound" : {
"isSyncAllowed" : true
},
"templateApplicationLevel" : "newPartners,existingPartners"
}
Disable the template for existing partners
PATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationIdentitySynchronization
{
"userSyncInbound" : {
"isSyncAllowed" : true
},
"templateApplicationLevel" : "newPartners"
}
Disable the template completely To reset the template to its default state (decline inbound synchronization), use the
multiT enantOrganizationIdentityS yncPolicyT emplate: resetT oDefaultSettings API.
Request
HTTP
Configure cross-tenant synchronizationPATCH
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationIdentitySynchronization
{
"userSyncInbound" : {
"isSyncAllowed" : true
},
"templateApplicationLevel" : ""
}
Reset the template
POST
https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/templates/
multiTenantOrganizationIdentitySynchronization/resetToDefaultSettings
Next steps Configure cross-tenant synchronization
Article •03/11/2024
This article describes the steps to configure cross-tenant synchronization using the
Microsoft Entra admin center. When configured, Microsoft Entra ID automatically
provisions and de-provisions B2B users in your target tenant. For important details on
what this service does, how it works, and frequently asked questions, see Automate user
provisioning and deprovisioning to SaaS applications with Microsoft Entra ID .
By the end of this article, you'll be able to:
Create B2B users in your target tenant
Remove B2B users in your target tenant
Keep user attributes synchronized between your source and target tenants
Sour ce tenant
Learning objectives
Prerequisites Microsoft Entra ID P1 or P2 license. For more information, see License
requirements .
Security Administrator role to configure cross-tenant access settings.
Hybrid Identity Administrator role to configure cross-tenant synchronization.
Cloud Application Administrator or Application Administrator role to assign users
to a configuration and to delete a configuration.
Target t enant
Microsoft Entra ID P1 or P2 license. For more information, see License
requirements .
Security Administrator role to configure cross-tenant access settings. Add the source tenant by typing the tenant ID or domain name and selecting Add.Step 1: Plan your provisioning deployment
Step 2: Enable user synchronization in the
target tenant
Tip
Steps in this article might vary slightly based on the portal you start from. Under Inbound access of the added organization, select Inherit ed fr om default . Target t enant
In this step, you automatically redeem invitations so users from the source tenant don't
have to accept the consent prompt. This setting must be checked in both the source
tenant (outbound) and target tenant (inbound). For more information, see Automatic
redemption setting . Sour ce tenant
In this step, you automatically redeem invitations in the source tenant. Check the Automatically r edeem invitations with the t enant
Select Save.
Sour ce tenant In the source tenant, you should see your new configuration. If not, in the
configuration list, select your configuration.
Step 5: Create a configuration in the source
tenant
Step 6: Test the connection to the target tenant Select Get star ted. Under the Admin Cr edentials section, change the Authentication Method to
Cross T enant S ynchr onization P olicy .
In the Tenant Id box, enter the tenant ID of the target tenant. In the source tenant, select Provisioning and expand the Settings section.
Step 7: Define who is in scope for provisioning In the Scope list, select whether to synchronize all users in the source tenant or
only users assigned to the configuration.
It's recommended that you select Sync only assigned user s and gr oups instead of
Sync all user s and gr oups . Reducing the number of users in scope improves
performance. Select Select .
Select Assign .
For more information, see Assign users and groups to an application .
Sour ce tenant
Regardless of the value you selected for Scope in the previous step, you can further limit
which users are synchronized by creating attribute-based scoping filters. In the source tenant, select Provisioning and expand the Mappings section.
Step 8: (Optional) Define who is in scope for
provisioning with scoping filters Select Provision Micr osoft Entra ID User s to open the Attribut e Mapping page. To configure scoping filters, refer to the instructions provided in Scoping users or
groups to be provisioned with scoping filters . The first attribute, alternativeSecurityIdentifier, is an internal attribute used to
uniquely identify the user across tenants, match users in the source tenant with
existing users in the target tenant, and ensure that each user only has one account.
The matching attribute cannot be changed. Attempting to change the matching
attribute or adding additional matching attributes will result in a schemaInvalid
error. The user type you choose has the following limitations for apps or services (but
aren't limited to):
App or
serviceLimitations
Power BI - Support for UserT ype Member in P ower BI is currently in preview. For
more information, see Distribute P ower BI content to external guest users
with Microsoft Entra B2B .
Azure Virtual
Desktop- External member and external guest aren't supported in Azure Virtual
Desktop. If you want to define any transformations, on the Attribut e Mapping page, select
the attribute you want to transform, such as displayName .７ Note
If the B2B user already exists in the target tenant then Member (userT ype) will
not changed to Member , unless the Apply this mapping setting is set to
Always .
ﾉExpand table
Set the Mapping type to Expression . In the Expression box, enter the transformation expression. For example with the
display name, you can do the following:
Flip the first name and last name and add a comma in between.
Add the domain name in parentheses at the end of the display name.
For examples, see Reference for writing expressions for attribute mappings in
Microsoft Entra ID .
Sour ce tenant
Tip
You can map directory extensions by updating the schema of the cross-tenant
synchronization. For more information, see Map dir ectory ext ensions in cr oss-
tenant synchr onization .
Step 10: Specify additional provisioning
setting s In the source tenant, select Provisioning and expand the Settings section. Now that you have a configuration, you can test on-demand provisioning with one of
your users. If the user isn't in scope, you'll see a page with information about why test user
was skipped.
On the Provision on demand page, you can view details about the provision and
have the option to retry.
Sour ce tenant
The provisioning job starts the initial synchronization cycle of all users defined in Scope
of the Settings section. The initial cycle takes longer to perform than subsequent cycles,
which occur approximately every 40 minutes as long as the Microsoft Entra provisioning
service is running. Sour ce and tar get t enants
Once you've started a provisioning job, you can monitor the status. If provisioning seems to be in an unhealthy state, the configuration will go into
quarantine. For more information, see Application provisioning in quarantine
status . You can also view audit logs in the target tenant. This setting also applies to B2B collaboration and B2B direct connect, so if you set
External user leav e settings to No, B2B collaboration users and B2B direct connect users
can't leave your organization themselves. For more information, see Leave an
organization as an external user .
Follows these steps to delete a configuration on the Configurations page. Cause
This error indicates the policy to automatically redeem invitations in both the source and
target tenants wasn't set up.
Solution
Follow the steps in Step 3: Automatically redeem invitations in the target tenant and
Step 4: Automatically redeem invitations in the source tenant .
When configuring cross-tenant synchronization, the Automatic r edemption check box
is disabled.Error code: AzureDirectoryB2BManagementPolicyCheckFailure
Details: Policy permitting auto-redemption of invitations not configured.
Symptom - Automatic redemption check box is disabled Cause
Your tenant doesn't have a Microsoft Entra ID P1 or P2 license.
Solution
You must have Microsoft Entra ID P1 or P2 to configure trust settings.
After soft deleting a synchronized user in the target tenant, the user isn't restored
during the next synchronization cycle. If you try to soft delete a user with on-demand
provisioning and then restore the user, it can result in duplicate users.
Cause
Restoring a previously soft-deleted user in the target tenant isn't supported.
Solution
Manually restore the soft-deleted user in the target tenant. For more information, see
Restore or remove a recently deleted user using Microsoft Entra ID .
Symptom - Recently deleted user in the target tenant is not
restored
Symptom - Users are skipped because SMS sign-in is enabled on
the user Users are skipped from synchronization. The scoping step includes the following filter
with status false: "Filter external users.alternativeSecurityIds EQU ALS 'None'"
Cause
If SMS sign-in is enabled for a user, they will be skipped by the provisioning service.
Solution
Disable SMS Sign-in for the users. The script below shows how you can disable SMS
Sign-in using P owerShell.
PowerShell Install-Module Microsoft.Graph.Users.Actions
Install-Module Microsoft.Graph.Identity.SignIns
Import-Module Microsoft.Graph.Users.Actions
Connect-MgGraph -Scopes "User.Read.All" , "Group.ReadWrite.All" ,
"UserAuthenticationMethod.Read.All" ,"UserAuthenticationMethod.ReadWrite" ,"Us
erAuthenticationMethod.ReadWrite.All" 87b9720928f7
$phoneAuthenticationMethodId = "3179e48a-750b-4051-897c-87b9720928f7" $userId = "objectid_of_the_user_in_Azure_AD" $smssignin = Get-MgUserAuthenticationPhoneMethod -UserId $userId
{
if($smssignin .SmsSignInState -eq "ready"){ PhoneAuthenticationMethodId $phoneAuthenticationMethodId
Write-Host "SMS sign-in disabled for the user" -ForegroundColor Green
}
else{
Write-Host "SMS sign-in status not set or found for the user " -
ForegroundColor Yellow
}
} Users in scope fail to provision. The provisioning logs details include the following error
message:
Cause
This error indicates the Guest invite settings in the target tenant are configured with the
most restrictive setting: "No one in the organization can invite guest users including
admins (most restrictive)".
Solution
Change the Guest invite settings in the target tenant to a less restrictive setting. For
more information, see Configure external collaboration settings .
Tutorial: R eporting on automatic user account provisioning
Managing user account provisioning for enterprise apps in the Azure portal
What is single sign-on in Microsoft Entra ID?##### End the script
Symptom - Users fail to provision with error
"AzureActiveDirectoryForbidden"
Guest invitations not allowed for your company. Contact your company Configure cross-tenant synchronization
using PowerShell or Microsoft Graph
API
Article •04/23/2024
This article describes the key steps to configure cross-tenant synchronization using
Microsoft Graph P owerShell or Microsoft Graph API. When configured, Microsoft Entra
ID automatically provisions and de-provisions B2B users in your target tenant. For
detailed steps using the Microsoft Entra admin center, see Configure cross-tenant
synchronization .
Sour ce tenant
Microsoft Entra ID P1 or P2 license. For more information, see License
requirements .
Security Administrator role to configure cross-tenant access settings.
Hybrid Identity Administrator role to configure cross-tenant synchronization.
Prerequisites Cloud Application Administrator or Application Administrator role to assign users
to a configuration and to delete a configuration.
Global Administrator role to consent to required permissions.
Target t enant
Microsoft Entra ID P1 or P2 license. For more information, see License
requirements .
Security Administrator role to configure cross-tenant access settings.
Global Administrator role to consent to required permissions.
Target t enant Target t enant In the target tenant, use the New-MgP olicyCrossT enantAccessP olicyP artner
command to create a new partner configuration in a cross-tenant access
policy between the target tenant and the source tenant. Use the source tenant
ID in the request.
If you get the error New-MgPolicyCrossTenantAccessPolicyPartner_Create:
Another object with the same value for property tenantId already exists,
you might already have an existing configuration. For more information, see
Symptom - New-MgP olicyCrossT enantAccessP olicyP artner_Create error .
PowerShell
OutputStep 2: Enable user synchronization in the
target tenant
PowerShell
$Params = @{
TenantId = $SourceTenantId
}
New-MgPolicyCrossTenantAccessPolicyPartner -BodyParameter $Params |
Format-List
AutomaticUserConsentSettings : Use the Invoke-MgGraphR equest command to enable user synchronization in
the target tenant.
If you get an Request_MultipleObjectsWithSameKeyValue error, you might
already have an existing policy. For more information, see Symptom -
Request_MultipleObjectsWithSameK eyValue error .
PowerShell System.Collections.Generic.Dictionary`2[System.String,System.Object
]], [protectedContentSharing, System.Collections.Generic.Dictionary`2[System.String,System.Object
]]}
$Params = @{
userSyncInbound = @{
isSyncAllowed = $true
}
}
Invoke-MgGraphRequest -Method PUT -Uri
"https://graph.microsoft.com/v1.0/policies/crossTenantAccessPolicy/
partners/ $SourceTenantId /identitySynchronization" -Body $Params
(Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization Target t enant True
Step 3: Automatically redeem invitations in the
target tenant
PowerShell
$AutomaticUserConsentSettings = @{
"InboundAllowed" ="True"
}
Update-MgPolicyCrossTenantAccessPolicyPartner -
CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId PowerShell Output System.Collections.Generic.Dictionary`2[System.String,System.Object
]], [protectedContentSharing, System.Collections.Generic.Dictionary`2[System.String,System.Object
]]} PowerShell
Sour ce tenant Use the Get-MgServicePrincipal command to get the service principal ID and
app role ID.
PowerShell
Output$AutomaticUserConsentSettings = @{
"OutboundAllowed" ="True"
}
Update-MgPolicyCrossTenantAccessPolicyPartner -
CrossTenantAccessPolicyConfigurationPartnerTenantId $TargetTenantId Initialize a variable for the service principal ID.
Be sure to use the service principal ID instead of the application ID.
PowerShell Sour ce tenant A template has pre-configured synchronization settings. Initialize a variable for the job ID.
PowerShell
Sour ce tenantNew-MgServicePrincipalSynchronizationJob -ServicePrincipalId
In the source tenant, use the Invoke-MgGraphR equest command to save your
credentials.
PowerShell
Sour ce tenant
For cross-tenant synchronization to work, at least one internal user must be assigned to
the configuration. Output
Sour ce tenant
Now that you have a configuration, you can test on-demand provisioning with one of
your users. In the source tenant, use the Get-
MgServicePrincipalS ynchronizationJobSchema command to get the schema
rule ID.
PowerShell
OutputNew-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId
Initialize a variable for the rule ID.
PowerShell Sour ce tenant PowerShell
Output ResultReason : User 'user2@fabrikam.com' was created in
When you try to perform an action, you receive an error message similar to the
following:
Cause
Either the signed-in user doesn't have sufficient privileges, or you need to consent
to one of the required permissions.
Solution Verify your syntax and that you are using the correct tenant ID.Symptom - Insufficient privileges error
code: Authorization_RequestDenied
message: Insufficient privileges to complete the operation.
Symptom - New-
MgPolicyCrossTenantAccessPolicyPartner_Create error
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with Use the Get-MgP olicyCrossT enantAccessP olicyP artner command to list the
existing object. PowerShell
Microsoft Entra synchronization API overview
Tutorial: Develop and plan provisioning for a SCIM endpoint in Microsoft Entra ID$Params = @{
userSyncInbound = @{
isSyncAllowed = $true
}
}
Set-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization -
CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId Scoping users or groups to be
provisioned with scoping filters
Article •01/18/2024
Learn how to use scoping filters in the Microsoft Entra provisioning service to define
attribute based rules. The rules are used to determine which users or groups are
provisioned.
You use scoping filters to prevent objects in applications that support automated user
provisioning from being provisioned if an object doesn't satisfy your business
requirements. A scoping filter allows you to include or exclude any users who have an
attribute that matches a specific value. For example, when provisioning users from
Microsoft Entra ID to a SaaS application used by a sales team, you can specify that only
users with a "Department" attribute of "Sales" should be in scope for provisioning.
Scoping filters can be used differently depending on the type of provisioning connector:
Outbound pr ovisioning fr om Micr osoft Entra ID t o SaaS applications . When
Microsoft Entra ID is the source system, user and group assignments are the most
common method for determining which users are in scope for provisioning. These
assignments also are used for enabling single sign-on and provide a single method
to manage access and provisioning. Scoping filters can be used optionally, in
addition to assignments or instead of them, to filter users based on attribute
values.
Inbound pr ovisioning fr om HCM applications t o Micr osoft Entra ID and Activ e
Directory. When an HCM application such as W orkday is the source system,
scoping filters are the primary method for determining which users should be
provisioned from the HCM application to Active Directory or Microsoft Entra ID.Scoping filter use cases
Tip
The more users and groups in scope for provisioning, the longer the
synchronization process can take. Setting the scope to sync assigned users
and groups, limiting the number of groups assigned to the app, and limiting
the size of the groups will reduce the time it takes to synchronize everyone
that is in scope. By default, Microsoft Entra provisioning connectors don't have any attribute-based
scoping filters configured.
A scoping filter consists of one or more claus es. Clauses determine which users are
allowed to pass through the scoping filter by evaluating each user's attributes. For
example, you might have one clause that requires that a user's "S tate" attribute equals
"New Y ork", so only New Y ork users are provisioned into the application.
A single clause defines a single condition for a single attribute value. If multiple clauses
are created in a single scoping filter, they're evaluated together using "AND" logic. The
"AND" logic means all clauses must evaluate to "true" in order for a user to be
provisioned.
Finally, multiple scoping filters can be created for a single application. If multiple
scoping filters are present, they're evaluated together by using "OR" logic. The "OR"
logic means that if all the clauses in any of the configured scoping filters evaluate to
"true", the user is provisioned.
Each user or group processed by the Microsoft Entra provisioning service is always
evaluated individually against each scoping filter.
As an example, consider the following scoping filter:
According to this scoping filter, users must satisfy the following criteria to be
provisioned:
They must be in New Y ork.Scoping filter construction They must work in the Engineering department.
Their company employee ID must be between 1,000,000 and 2,000,000.
Their job title must not be null or empty.
Scoping filters are configured as part of the attribute mappings for each Microsoft Entra
user provisioning connector. The following procedure assumes that you already set up
automatic provisioning for one of the supported applications and are adding a scoping
filter to it. c. ENDS_WITH . Clause returns "true" if the evaluated attribute ends with the input
string value.
d. EQUALS. Clause returns "true" if the evaluated attribute matches the input string
value exactly (case sensitive).
e. Greater_Than. Clause returns "true" if the evaluated attribute is greater than the
value. The value specified on the scoping filter must be an integer and the
attribute on the user must be an integer [0,1,2,...].
f. Greater_Than_OR_EQU ALS. Clause returns "true" if the evaluated attribute is
greater than or equal to the value. The value specified on the scoping filter must
be an integer and the attribute on the user must be an integer [0,1,2,...].
g. Includes. Clause returns "true" if the evaluated attribute contains the string
value (case sensitive) as described here.
h. IS FALSE . Clause returns "true" if the evaluated attribute contains a Boolean
value of false.
i. IS NO T NULL . Clause returns "true" if the evaluated attribute isn't empty.
j. IS NULL . Clause returns "true" if the evaluated attribute is empty.
k. IS TRUE . Clause returns "true" if the evaluated attribute contains a Boolean value
of true.
l. NOT EQU ALS. Clause returns "true" if the evaluated attribute doesn't match the
input string value (case sensitive).
m. NOT REGE X MA TCH. Clause returns "true" if the evaluated attribute doesn't
match a regular expression pattern. It returns "false" if the attribute is null / empty.
n. REGE X MA TCH. Clause returns "true" if the evaluated attribute matches a regular
expression pattern. For example: ([1-9][0-9]) matches any number between 10
and 99 (case sensitive).
） Impor tant
The IsMemberOf filter is not supported currently.
The members attribute on a group is not supported currently.
Filtering is not supported for multi-valued attributes.
Scoping filters will return "false" if the value is null / empty. Customize attribute mappings for user provisioning
Write expressions for attribute mappings
Account provisioning notifications
Use SCIM to enable automatic provisioning of users and groups from Microsoft
Entra ID to applications
List of tutorials on how to integrate SaaS apps Enable accidental deletions prevention
in the Microsoft Entra provisioning
service
Article •10/23/2023
The Microsoft Entra provisioning service includes a feature to help avoid accidental
deletions. This feature ensures that users aren't disabled or deleted in an application
unexpectedly.
You use accidental deletions to specify a deletion threshold. Anything above the
threshold that you set requires an admin to explicitly allow the processing of the
deletions.
To enable accidental deletion prevention: You can click either Allow delet es or View pr ovisioning logs .
The Allow delet es action deletes the objects that triggered the accidental delete
threshold. Use the procedure to accept the deletions. Feedb ack
Was this p age help ful?Remove a user from a group that's provides them access to the application (or
configuration).
To learn more about deprovisioning scenarios, see How Application Provisioning W orks.
When a user is set for removal from the target application (or target tenant), it's counted
against the deletion threshold. Scenarios that could lead to a user being removed from
the target application (or target tenant) could include: unassigning the user from the
application (or configuration) and soft / hard deleting a user in the directory. Groups
evaluated for deletion count towards the deletion threshold. In addition to deletions, the
same functionality also works for disables.
It's evaluated each cycle. If the number of deletions doesn't exceed the threshold during
a single cycle, the “circuit breaker” isn't triggered. If multiple cycles are needed to reach
a steady state, the deletion threshold is evaluated per cycle.
You can find users that should be disabled / deleted but haven’t due to the deletion
threshold. Navigation to Provisioning logs and then filter Action with StagedAction or
StagedDelet e.
How application provisioning works
Plan an application provisioning deploymentFrequently Asked Questions
What scenarios count toward the deletion threshold?
What is the interval that the deletion threshold is
evaluated on?
How are these deletion events logged?
Next steps
Yes No Provide product feedback |Get help at Microsoft Q&A On-demand provisioning in Microsoft
Entra ID
Article •10/23/2023
Use on-demand provisioning to provision a user or group in seconds. Among other
things, you can use this capability to:
Troubleshoot configuration issues quickly.
Validate expressions that you've defined.
Test scoping filters. The on-demand provisioning process attempts to show the steps that the provisioning
service takes when provisioning a user. There are typically five steps to provision a user.
One or more of those steps, explained in the following sections, are shown during the
on-demand provisioning experience.
The provisioning service attempts to authorize access to the target system by making a
request for a "test user". The provisioning service expects a response that indicates that
the service authorized to continue with the provisioning steps. This step is shown only
when it fails. It's not shown during the on-demand provisioning experience when the
step is successful.
Ensure that you've provided valid credentials, such as the secret token and tenant
URL, to the target system. The required credentials vary by application. For detailed
configuration tutorials, see the tutorial list .
Make sure that the target system supports filtering on the matching attributes
defined in the Attribut e mappings pane. Y ou might need to check the API
documentation provided by the application developer to understand the
supported filters.
For S ystem for Cross-domain Identity Management (SCIM) applications, you can
use a tool like P ostman. Such tools help you ensure that the application responds
Understand the provisioning steps
Step 1: Test connection
Troubleshooting tips to authorization requests in the way that the Microsoft Entra provisioning service
expects. Have a look at an example request .
Next, the provisioning service retrieves the user from the source system. The user
attributes that the service retrieves are used later to:
Evaluate whether the user is in scope for provisioning.
Check the target system for an existing user.
Determine what user attributes to export to the target system.
The View details section shows the properties of the user that were imported from the
source system (for example, Microsoft Entra ID).
Importing the user can fail when the matching attribute is missing on the user
object in the source system. T o resolve this failure, try one of these approaches:
Update the user object with a value for the matching attribute.
Change the matching attribute in your provisioning configuration.
If an attribute that you expected is missing from the imported list, ensure that the
attribute has a value on the user object in the source system. The provisioning
service currently doesn't support provisioning null attributes.
Make sure that the Attribut e mapping page of your provisioning configuration
contains the attribute that you expect.
Next, the provisioning service determines whether the user is in scope for provisioning.
The service considers aspects such as:
Whether the user is assigned to the application.
Whether scope is set to Sync assigned or Sync all .
The scoping filters defined in your provisioning configuration.Step 2: Import user
View details
Troubleshooting tips
Step 3: Determine if user is in scope
View details The View details section shows the scoping conditions that were evaluated. Y ou might
see one or more of the following properties:
Activ e in sour ce syst em indicates that the user has the property IsActive set to
true in Microsoft Entra ID.
Assigned t o application indicates that the user is assigned to the application in
Microsoft Entra ID.
Scope sync all indicates that the scope setting allows all users and groups in the
tenant.
User has r equir ed role indicates that the user has the necessary roles to be
provisioned into the application.
Scoping filt ers are also shown if you have defined scoping filters for your
application. The filter is displayed with the following format: {scoping filter title}
{scoping filter attribute} {scoping filter operator} {scoping filter value}.
Make sure that you've defined a valid scoping role. For example, avoid using the
Greater_Than operator with a noninteger value.
If the user doesn't have the necessary role, review the tips for provisioning users
assigned to the default access role .
In this step, the service attempts to match the user that was retrieved in the import step
with a user in the target system.
The View details page shows the properties of the users that were matched in the target
system. The context pane changes as follows:
If no users are matched in the target system, no properties are shown.
If one user matches in the target system, the properties of that user are shown.
If multiple users match, the properties of both users are shown.
If multiple matching attributes are part of your attribute mappings, each matching
attribute is evaluated sequentially and the matched users for that attribute are
shown.Troubleshooting tips
Step 4: Match user between source and target
View details
Troubleshooting tips The provisioning service might not be able to match a user in the source system
uniquely with a user in the target. R esolve this problem by ensuring that the
matching attribute is unique.
Make sure that the target system supports filtering on the attribute that's defined
as the matching attribute.
Finally, the provisioning service takes an action, such as creating, updating, deleting, or
skipping the user.
Here's an example of what you might see after the successful on-demand provisioning
of a user:
The View details section displays the attributes that were modified in the target system.
This display represents the final output of the provisioning service activity and the
attributes that were exported. If this step fails, the attributes displayed represent the
attributes that the provisioning service attempted to modify.
Failures for exporting changes can vary greatly. Check the documentation for
provisioning logs for common failures.
On-demand provisioning says the group or user can't be provisioned because
they're not assigned to the application. There's a replication delay of up to a fewStep 5: Perform action
View details
Troubleshooting tips minutes between when an object is assigned to an application and when that
assignment is honored in on-demand provisioning. Y ou may need to wait a few
minutes and try again.
Do y ou need t o turn pr ovisioning o ff to use on-demand pr ovisioning? For
applications that use a long-lived bearer token or a user name and password for
authorization, no more steps are required. Applications that use O Auth for
authorization currently require the provisioning job to be stopped before using
on-demand provisioning. Applications such as G Suite, Box, W orkplace by
Facebook, and Slack fall into this category. W ork is in progress to support on-
demand provisioning for all applications without having to stop provisioning jobs.
How long does on-demand pr ovisioning tak e? On-demand provisioning typically
takes less than 30 seconds.
There are currently a few known limitations to on-demand provisioning. P ost your
suggestions and feedback so we can better determine what improvements to make
next.
On-demand provisioning of groups supports updating up to five members at a
time. Connectors for cross-tenant synchronization, W orkday, etc. do not support
group provisioning and as a result do not support on-demand provisioning of
groups.
On-demand provisioning supports provisioning one user at a time through the
Microsoft Entra admin center.
Restoring a previously soft-deleted user in the target tenant with on-demand
provisioning isn't supported. If you try to soft-delete a user with on-demand
provisioning and then restore the user, it can result in duplicate users.
On-demand provisioning of roles isn't supported.Frequently asked questions
Known limitations
７ Note
The following limitations are specific to the on-demand provisioning capability. For
information about whether an application supports provisioning groups, deletions,
or other capabilities, check the tutorial for that application. Feedb ack
Was this p age help ful?
Provide product feedback |Get help at Microsoft Q&AOn-demand provisioning supports disabling users that have been unassigned from
the application. However, it doesn't support disabling or deleting users that have
been disabled or deleted from Microsoft Entra ID. Those users don't appear when
you search for a user.
On-demand provisioning doesn't support nested groups that aren't directly
assigned to the application.
The on-demand provisioning request API can only accept a single group with up to
5 members at a time.
Troubleshooting provisioningNext steps
Yes No What are the Microsoft Entra user
provisioning logs?
Article •01/25/2024
Microsoft Entra ID integrates with several third party services to provision users into
your tenant. If you need to troubleshoot an issue with a provisioned user, you can use
the information captured in the Microsoft Entra provisioning logs to help find a solution.
Two other activity logs are also available to help monitor the health of your tenant:
Sign-ins – Information about sign-ins and how your resources are used by your
users.
Audit – Information about changes applied to your tenant such as users and group
management or updates applied to your tenant’s resources.
This article gives you an overview of the user provisioning logs.
The required roles and licenses might vary based on the report. Global Administrator
can access all reports, but we recommend using a role with least privilege access to
align with the Zero T rust guidance .
Log / R epor t Roles Licenses
Audit Report R eader
Security R eader
Security Administrator
Global R eader
A custom role with AuditLogsRead or
CustomSecAuditLogsRead permissionAll editions of
Microsoft Entra ID
Sign-ins Report R eader
Security R eader
Security Administrator
Global R eader
A custom role with SignInLogsRead permissionAll editions of
Microsoft Entra ID
Provisioning Same as audit and sign-ins, plus
Security Operator
Application Administrator
Cloud App AdministratorMicrosoft Entra ID
P1/P2License and role requirements
ﾉExpand table Log / R epor t Roles Licenses
A custom role with ProvisioningLogsRead
permission
Usage and insights Security R eader
Reports R eader
Security AdministratorMicrosoft Entra ID
P1/P2
Identity Protection* Security Administrator
Security Operator
Security R eader
Global R eader
A custom role with IdentityRiskEventReadWrite
permissionMicrosoft Entra ID
Free
Microsoft 365 Apps
Microsoft Entra ID
P1/P2
Microsoft Graph
activity logsSecurity Administrator
A custom role with ListKeys permissionMicrosoft Entra ID
P1/P2
*The level of access and capabilities for Identity Protection varies with the role and
license. For more information, see the license requirements for Identity Protection .
You can use the provisioning logs to find answers to questions like:
What groups were successfully created in ServiceNow?
What users were successfully removed from Adobe?
What users from W orkday were successfully created in Active Directory?
When you select an item in the provisioning list view, you get more details about this
item, such as the steps taken to provision the user and tips for troubleshooting issues.
The details are grouped into four tabs.
Steps: This tab outlines the steps taken to provision an object. Provisioning an
object can include the following steps, but not all steps are applicable to all
provisioning events.What can you do with the provisioning logs?
７ Note
Entries in the provisioning logs are system generated and can't be changed or
deleted.
What do the logs show? Import the object.
Match the object between source and target.
Determine if the object is in scope.
Evaluate the object before synchronization.
Provision the object (create, update, delete, or disable).
Troubleshooting & R ecommendations : If there was an error, this tab provides the
error code and reason.
Modified Pr oper ties: If there were changes, this tab shows the old value and the
new value.
Summar y: Provides an overview of what happened and identifiers for the object in
the source and target systems. Map directory extensions in cross-
tenant synchronization
Article •01/30/2024
Directory extensions enable you to extend the schema in Microsoft Entra ID with your
own attributes. Y ou can map these directory extensions when provisioning users in
cross-tenant synchronization. Custom security attributes are different and aren't
supported in cross-tenant synchronization.
This article describes how to map directory extensions in cross-tenant synchronization.
Hybrid Identity Administrator role to configure cross-tenant synchronization.
Cloud Application Administrator or Application Administrator role to assign users
to a configuration and to delete a configuration.
If you don't already have directory extensions, you must create one or more directory
extensions in the source or target tenant. Y ou can create extensions using Microsoft
Entra Connect or Microsoft Graph API. For information on how to create directory
extensions, see Syncing extension attributes for Microsoft Entra Application
Provisioning .
Sour ce tenant
Once you have one or more directory extensions, you can use them when mapping
attributes in cross-tenant synchronization. Select Provisioning and expand the Mappings section.Prerequisites
Create directory extensions
Map directory extensions Select Provision Micr osoft Entra ID User s to open the Attribut e Mapping page. If the directory extension isn't listed, make sure that the directory extension was
created successfully. Y ou can also try to manually add the directory extension to
the attribute list as described in the next section. https://entra.microsoft.com/?
Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true Add the directory extension and select the appropriate options.
Tip
If you don't see the Edit attribut e list links, be sure that you are signed in to
the Microsoft Entra admin center using the link in S tep 1. Select Save. Select Provision Micr osoft Entra ID User s to open the Attribut e Mapping page.
Manually add directory extensions by editing
the schema Scroll to the bottom and select the Show adv anced settings check box. Select Save.
Refresh the browser. Reference for writing expressions for
attribute ma ppings in Microsoft Entra ID
Article •01/26/2024
When you configure provisioning to a SaaS application, one of the types of attribute
mappings that you can specify is an expression mapping. For these mappings, you must
write a script-like expression that allows you to transform your users' data into formats
that are more acceptable for the SaaS application.
The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic for
Applications (VBA) functions.
The entire expression must be defined in terms of functions, which consist of a
name followed by arguments in parentheses: FunctionName( <<argument 1>>,
<
Append AppR oleAssignmentsComplex BitAnd CBool CDate Coalesce Description: Used to configure multiple roles for a user. For detailed usage, see Tutorial Description: CBool returns a boolean based on the evaluated expression. If the
expression evaluates to a non-zero value, then CBool returns True, else it returns False.
Paramet ers:
Name Requir ed/ R epeating Type Notes
Expression Required expression Any valid expression
Example: CBool([attribute1] = [attribute2])
Returns T rue if both attributes have the same value.
Function:
CDate(expression)
Description:
The CDate function returns a UT C DateTime from a string. DateTime isn't a native
attribute type but it can be used within date functions such as FormatDateTime and
DateAdd .
Paramet ers:
Name Requir ed/
RepeatingType Notes
Expression Required Expression Any valid string that represents a date/time. For
supported formats, refer to .NET custom date and
time format strings .
Remarks:
The returned string is always in UT C and follows the format M/d/yyyy h:mm:ss tt .
Example 1:
CDate([StatusHireDate])
Sample input/output:
INPUT (StatusHireDate): "2020-03-16-07:00"ﾉExpand table
CDate
ﾉExpand table OUTPUT : "3/16/2020 7:00:00 AM" <-- Note the UT C equiv alent o f the abo ve
DateTime is r eturned
Example 2:
CDate("2021-06-30+08:00")
Sample input/output:
INPUT : "2021-06-30+08:00"
OUTPUT : "6/29/2021 4:00:00 PM" <-- Note the UT C equiv alent o f the abo ve
DateTime is r eturned
Example 3:
CDate("2009-06-15T01:45:30-07:00")
Sample input/output:
INPUT : "2009-06-15T01:45:30-07:00"
OUTPUT : "6/15/2009 8:45:30 AM" <-- Note the UT C equiv alent o f the abo ve
DateTime is r eturned
Function: Coalesce(source1, source2, ..., defaultV alue)
Description: Returns the first source value that isn't NULL. If all arguments are NULL and
defaultV alue is present, the defaultV alue is returned. If all arguments are NULL and
defaultV alue isn't present, Coalesce returns NULL.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source1 …
sourceNRequired String Required, variable-number of times. Usually name
of the attribute from the source object.
defaultV alue Optional String Default value to be used when all source values are
NULL. Can be empty string ("").Coalesce
ﾉExpand table
Flow mail value if not NULL, otherwise flow userPrincipalName Example: Y ou wish to flow the mail attribute if it is present. If it isn't, you wish to flow the
value of userPrincipalName instead.
Expression: Coalesce([mail],[userPrincipalName])
Sample input/output:
INPUT (mail): NULL
INPUT (userPrincipalName): "John.Doe@contoso.com"
OUTPUT : "John.Doe@contoso.com"
Function: ConvertT oBase64(source)
Description: The ConvertT oBase64 function converts a string to a Unicode base64 string.
Paramet ers:
Name Requir ed/ R epeating Type Notes
source Required String String to be converted to base 64
Example: ConvertToBase64("Hello world!")
Returns "SABlA GwAbABvA CAAdwBvAHIAbABkA CEA"
Function: ConvertT oUTF8Hex(source)
Description: The ConvertT oUTF8Hex function converts a string to a UTF8 Hex encoded
value.
Paramet ers:
Name Requir ed/ R epeating Type Notes
source Required String String to be converted to UTF8 HexConvertToBase64
ﾉExpand table
ConvertToUTF8Hex
ﾉExpand table Example: ConvertToUTF8Hex("Hello world!")
Returns 48656C6C6F20776F726C6421
Function: Count(attribute)
Description: The Count function returns the number of elements in a multi-valued
attribute
Paramet ers:
Name Requir ed/
RepeatingType Notes
attribut eRequired attribute Multi-valued attribute that will have elements
counted
Function: CStr(value)
Description: The CS tr function converts a value to a string data type.
Paramet ers:
Name Requir ed/
RepeatingType Notes
value Required numeric, reference, or
booleanCan be a numeric value, reference
attribute, or Boolean.
Example: CStr([dn])
Returns "cn=Joe,dc=contoso,dc=com"Count
ﾉExpand table
CStr
ﾉExpand table
DateAdd Function:
DateAdd(interval, value, dateTime)
Description:
Returns a date/time string representing a date to which a specified time interval has
been added. The returned date is in the format: M/d/yyyy h:mm:ss tt .
Paramet ers:
Name Requir ed/
RepeatingType Notes
interval Required String Interval of time you want to add. See accepted values
below this table.
value Required Number The number of units you want to add. It can be positive
(to get dates in the future) or negative (to get dates in
the past).
dateTime Required DateTime DateTime representing date to which the interval is
added.
When passing a date string as input, use CDate function to wrap the datetime string. T o
get system time in UT C, use the Now function.
The interval string must have one of the following values:
yyyy Y ear
m Month
d Day
ww W eek
h Hour
n Minute
s Second
Example 1: Generat e a dat e value b ased on incoming S tatusHir eDat e from W orkday
DateAdd("d", 7, CDate([StatusHireDate]))ﾉExpand table
ﾉExpand table Example intervalvalue dateTime (v alue o f variable
StatusHir eDat e)output
Add 7 days to hire date "d" 7 2012-03-16-07:00 3/23/2012
7:00:00 AM
Get a date ten days
prior to hire date"d" -10 2012-03-16-07:00 3/6/2012
7:00:00 AM
Add two weeks to hire
date"ww" 2 2012-03-16-07:00 3/30/2012
7:00:00 AM
Add ten months to hire
date"m" 10 2012-03-16-07:00 1/16/2013
7:00:00 AM
Add two years to hire
date"yyyy" 2 2012-03-16-07:00 3/16/2014
7:00:00 AM
Function:
DateDiff(interval, date1, date2)
Description:
This function uses the interval parameter to return a number that indicates the
difference between the two input dates. It returns
a positive number if date2 > date1,
a negative number if date2 < date1,
0 if date2 == date1
Paramet ers:
Name Requir ed/Optional Type Notes
intervalRequired String Interval of time to use for calculating the difference.
date1 Required DateTime DateTime representing a valid date.
date2 Required DateTime DateTime representing a valid date.
When passing a date string as input, use CDate function to wrap the datetime string. T o
get system time in UT C, use the Now function.
The interval string must have one of the following values:DateDiff
ﾉExpand table yyyy Y ear
m Month
d Day
ww W eek
h Hour
n Minute
s Second
Example 1: Comp are curr ent dat e with hir e dat e from W orkday with differ ent int ervals
DateDiff("d", Now(), CDate([StatusHireDate]))
Example intervaldate1 date2 output
Positive difference in days between
two datesd 2021-08-18+08:00 2021-08-
31+08:0013
Negative difference in days between
two datesd 8/25/2021 5:41:18
PM2012-03-16-
07:00-3449
Difference in weeks between two
datesww 8/25/2021 5:41:18
PM2012-03-16-
07:00-493
Difference in months between two
datesm 8/25/2021 5:41:18
PM2012-03-16-
07:00-113
Difference in years between two
datesyyyy 8/25/2021 5:41:18
PM2012-03-16-
07:00-9
Difference when both dates are same d 2021-08-31+08:00 2021-08-
31+08:000
Difference in hours between two
datesh 2021-08-24 2021-08-25 24
Difference in minutes between two
datesn 2021-08-24 2021-08-25 1440
Difference in seconds between two
datess 2021-08-24 2021-08-25 86400
Example 2: Combine Dat eDiff with IIF function t o set attribut e value
If an account is Active in W orkday, set the accountEnabled attribute of the user to T rue
only if hire date is within the next five days.ﾉExpand table Function: DateFromNum(value)
Description: The DateFromNum function converts a value in AD's date format to a
DateTime type.
Paramet ers:
Name Requir ed/ R epeating Type Notes
value Required Date AD Date to be converted to DateTime type
Example: DateFromNum([lastLogonTimestamp])
DateFromNum(129699324000000000)
Returns a DateTime representing January 1, 2012 at 11:00PM.
Function: FormatDateTime(source, dateTimeS tyles, inputFormat, outputFormat)
Description: Takes a date string from one format and converts it into a different format.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute from the source object.
dateTimeS tyles Optional String Use this parameter to specify the formatting options that
customize string parsing for some date and time parsing
methods. For supported values, see DateTimeS tyles doc .
If left empty, the default value used isSwitch([Active], ,
"1", IIF(DateDiff("d", Now(), CDate([StatusHireDate])) > 5, "False", Name Requir ed/
RepeatingType Notes
DateTimeS tyles.R oundtripKind,
DateTimeS tyles.AllowLeadingWhite,
DateTimeS tyles.AllowT railingWhite
inputFormat Required String Expected format of the source value. For supported
formats, see .NET custom date and time format strings .
outputFormat Required String Format of the output date.
Example: Y ou want to send dates to a SaaS application like ServiceNow in a certain
format. Y ou can consider using the following expression.
Expression:
FormatDateTime([extensionAttribute1], , "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")
Sample input/output:
INPUT (extensionAttribute1): "20150123105347.1Z"
OUTPUT : "2015-01-23"
Function: Guid()
Description: The function Guid generates a new random GUID
Example:
Guid()
Sample output: "1088051a-cd4b-4288-84f8-e02042ca72bc"
Function: IgnoreFlowIfNullOrEmpty(expression)
Description: The IgnoreFlowIfNullOrEmpty function instructs the provisioning service to
ignore the attribute and drop it from the flow if the enclosed function or attribute is
NULL or empty.Output date as a string in a certain format
Guid
IgnoreFlowIfNullOrEmpty Paramet ers:
Name Requir ed/ R epeating Type Notes
Expression Required Expression Expression to be evaluated
Example 1: Don 't flow an attribut e if it is null
IgnoreFlowIfNullOrEmpty([department])
The above expression will drop the department attribute from the provisioning flow if it
is null or empty.
Example 2: Don 't flow an attribut e if the expr ession mapping ev aluat es to empty
string or null
Let's say the SuccessF actors attribute prefix is mapped to the on-premises Active
Directory attribute personalTitle using the following expression mapping:
IgnoreFlowIfNullOrEmpty(Switch([prefix], "", "3443", "Dr.", "3444", "Prof.",
"3445", "Prof. Dr."))
The above expression first evaluates the Switch function. If the prefix attribute doesn't
have any of the values listed within the Switch function, then Switch will return an empty
string and the attribute personalTitle will not be included in the provisioning flow to on-
premises Active Directory.
Function: IIF(condition,valueIfT rue,valueIfF alse)
Description: The IIF function returns one of a set of possible values based on a specified
condition.
Paramet ers:
Name Requir ed/
RepeatingType Notes
condition Required Variable or
ExpressionAny value or expression that can be
evaluated to true or false.
valueIfT rue Required Variable or S tring If the condition evaluates to true, the
returned value.ﾉExpand table
IIF
ﾉExpand table Name Requir ed/
RepeatingType Notes
valueIfF alse Required Variable or S tring If the condition evaluates to false, the
returned value.
The following comparison operators can be used in the condition :
Equal to (=) and not equal to (<>)
Greater than (>) and greater than equal to (>=)
Less than (<) and less than equal to (<=)
Example: Set the target attribute value to source country attribute if country="USA",
else set target attribute value to source department attribute. IIF([country]="USA",
[country],[department])
This section includes limitations and workarounds for the IIF function. For information
about troubleshooting user creation issues, see Creation fails due to null / empty values .
The IIF function currently doesn't support AND and OR logical operators.
To implement AND logic, use nested IIF statement chained along the trueValue
path. Example: If country="USA" and state="CA", return value "T rue", else return
"False". IIF([country]="USA",IIF([state]="CA","True","False"),"False")
To implement OR logic, use nested IIF statement chained along the falseValue
path. Example: If country="USA" or state="CA", return value "T rue", else return
"False". IIF([country]="USA","True",IIF([state]="CA","True","False"))
If the source attribute used within the IIF function is empty or null, the condition
check fails.
Unsupported IIF expression examples:
IIF([country]="","Other",[country])
IIF(IsNullOrEmpty([country]),"Other",[country])
IIF(IsPresent([country]),[country],"Other")
Recommended workaround: Use the Switch function to check for empty/null
values. Example: If country attribute is empty, set value "Other". If it is present,
pass the country attribute value to target attribute.
Switch([country],[country],"","Other")Known limitations
InStr Function: InStr(value1, value2, start, compareT ype)
Description: The InS tr function finds the first occurrence of a substring in a string
Paramet ers:
Name Requir ed/ R epeating Type Notes
value1 Required String String to be searched
value2 Required String String to be found
start Optional Integer Starting position to find the substring
comp areType Optional Enum Can be vbT extCompare or vbBinaryCompare
Example: InStr("The quick brown fox","quick")
Evaluates to 5
InStr("repEated","e",3,vbBinaryCompare)
Evaluates to 7
Function: IsNull(Expression)
Description: If the expression evaluates to Null, then the IsNull function returns true. For
an attribute, a Null is expressed by the absence of the attribute.
Paramet ers:
Name Requir ed/ R epeating Type Notes
Expression Required Expression Expression to be evaluated
Example: IsNull([displayName])
Returns T rue if the attribute isn't present.ﾉExpand table
IsNull
ﾉExpand table
IsNullorEmpty Function: IsNullOrEmpty(Expression)
Description: If the expression is null or an empty string, then the IsNullOrEmpty function
returns true. For an attribute, this would evaluate to T rue if the attribute is absent or is
present but is an empty string. The inverse of this function is named IsPresent.
Paramet ers:
Name Requir ed/ R epeating Type Notes
Expression Required Expression Expression to be evaluated
Example: IsNullOrEmpty([displayName])
Returns T rue if the attribute isn't present or is an empty string.
Function: IsPresent(Expression)
Description: If the expression evaluates to a string that isn't Null and isn't empty, then
the IsPresent function returns true. The inverse of this function is named IsNullOrEmpty.
Paramet ers:
Name Requir ed/ R epeating Type Notes
Expression Required Expression Expression to be evaluated
Example: Switch(IsPresent([directManager]),[directManager],
IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])
Function: IsString(Expression)
Description: If the expression can be evaluated to a string type, then the IsS tring
function evaluates to T rue.
Paramet ers:ﾉExpand table
IsPresent
ﾉExpand table
IsString Name Requir ed/ R epeating Type Notes
Expression Required Expression Expression to be evaluated
Function: Item(attribute, index)
Description: The Item function returns one item from a multi-valued string/attribute.
Paramet ers:
Name Requir ed/ R epeating Type Notes
attribut e Required Attribute Multi-valued attribute to be searched
index Required Integer Index to an item in the multi-valued string
Example: Item([proxyAddresses], 1) returns the first item in the multi-valued attribute.
Index 0 shouldn't be used.
Function: Join(separator, source1, source2, …)
Description: Join() is similar to Append(), except that it can combine multiple source
string values into a single string, and each value will be separated by a separator string.
If one of the source values is a multi-value attribute, then every value in that attribute
will be joined together, separated by the separator value.
Paramet ers:
Name Requir ed/
RepeatingType Notes
separator Required String String used to separate source values when they
are concatenated into one string. Can be "" if no
separator is required.ﾉExpand table
Item
ﾉExpand table
Join
ﾉExpand table Name Requir ed/
RepeatingType Notes
source1 …
sourceNRequired, variable-
number of timesString String values to be joined together.
Function: Left(S tring, NumChars)
Description: The Left function returns a specified number of characters from the left of a
string. If numChars = 0, return empty string. If numChars < 0, return input string. If
string is null, return empty string. If string contains fewer characters than the number
specified in numChars, a string identical to string (that is, containing all characters in
parameter 1) is returned.
Paramet ers:
Name Requir ed/
RepeatingType Notes
String Required Attribute The string to return characters from
NumChar sRequired Integer A number identifying the number of characters to
return from the beginning (left) of string
Example: Left("John Doe", 3)
Returns "Joh".
Function: Mid(source, start, length)
Description: Returns a substring of the source value. A substring is a string that contains
only some of the characters from the source string.
Paramet ers:Left
ﾉExpand table
Mid
ﾉExpand table Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute.
start Required Integer Index in the source string where substring should start. First
character in the string has an index of 1, second character
has an index 2, and so on.
length Required Integer Length of the substring. If length ends outside the source
string, function returns substring from start index until end
of source string.
Function: NormalizeDiacritics(source)
Description: Requires one string argument. R eturns the string, but with any diacritical
characters replaced with equivalent nondiacritical characters. T ypically used to convert
first names and last names containing diacritical characters (accent marks) into legal
values that can be used in various user identifiers such as user principal names, SAM
account names, and email addresses.
Paramet ers:
Name Requir ed/ R epeating Type Notes
source Required String Usually a first name or last name attribute.
Charact er with Diacr itic Normalized
charact erCharact er with Diacr itic Normalized
charact er
ä, à, â, ã, å, á, ą, ă, ā, ā ́, ā̀,
ā̂, ā̃, ǟ, ā̈, ǡ, a̱, å̄a Ä, À, Â, Ã, Å, Á, Ą, Ă, Ā, Ā́, Ā̀,
Ā̂, Ā̃, Ǟ, Ā̈, Ǡ, A̱, Å̄A
æ, ǣ ae Æ, Ǣ AE
ç, č, ć, c ̄, c̱ c Ç, Č, Ć, C ̄, C̱ C
ď, d̄, ḏ d Ď, D̄, Ḏ D
ë, è, é, ê, ę, ě, ė, ē, ḗ, ḕ, ē ̂,
ē̃, ê̄, e̱, ë̄, e̊̄e Ë, È, É, Ê, Ę, Ě, Ė, Ē, Ḗ, Ḕ, Ē̂, Ē̃, Ê̄,
E̱, Ë̄, E̊̄ENormalizeDiacritics
ﾉExpand table
ﾉExpand table Charact er with Diacr itic Normalized
charact erCharact er with Diacr itic Normalized
charact er
ğ, ḡ, g ̱ g Ğ, Ḡ, G ̱ G
ï, î, ì, í, ı, ī, ī ́, ī̀, ī̂, ī̃, i̱ i Ï, Î, Ì, Í, İ, Ī, Ī́, Ī̀, Ī̂, Ī̃, I̱ I
ľ, ł, l̄, ḹ, ḻ l Ł, Ľ, L ̄, Ḹ, Ḻ L
ñ, ń, ň, n ̄, ṉ n Ñ, Ń, Ň, N ̄, Ṉ N
ö, ò, ő, õ, ô, ó, ō, ṓ, ṑ, ō ̂,
ō̃, ȫ, ō̈, ǭ, ȭ, ȱ, o ̱o Ö, Ò, Ő, Õ, Ô, Ó, Ō, Ṓ, Ṑ, Ō̂,
Ō̃, Ȫ, Ō̈, Ǭ, Ȭ, Ȱ, O ̱O
ø, ø̄, œ̄ oe Ø, Ø̄, Œ̄ OE
ř, r̄, ṟ, ṝ r Ř, R̄, Ṟ, Ṝ R
ß ss
š, ś, ș, ş, s ̄, s̱ s Š, Ś, Ș, Ş, S ̄, S̱ S
ť, ț, t̄, ṯ t Ť, Ț, T ̄, Ṯ T
ü, ù, û, ú, ů, ű, ū, ū ́, ū̀, ū̂,
ū̃, u̇̄, ǖ, ṻ, ṳ ̄, u̱u Ü, Ù, Û, Ú, Ů, Ű, Ū, Ū́, Ū̀, Ū̂, Ū̃,
U̇̄, Ǖ, Ṻ, Ṳ ̄, U̱U
ÿ, ý, ȳ, ȳ ́, ȳ̀, ȳ̃, y̱ y Ÿ, Ý, Ȳ, Ȳ́, Ȳ̀, Ȳ̃, Y̱ Y
ź, ž, ż, z ̄, ẕ z Ź, Ž, Ż, Z ̄, Ẕ Z
Example: R eplace characters containing accent marks with equivalent characters that
don't contain accent marks.
Expression: NormalizeDiacritics([givenName])
Sample input/output:
INPUT (givenName): "Zoë"
OUTPUT : "Zoe"
Function: Not(source)Remove diacritics from a string
Not Description: Flips the boolean value of the source. If source value is T rue, returns F alse.
Otherwise, returns T rue.
Paramet ers:
Name Requir ed/ R epeating Type Notes
source Required Boolean S tring Expected source values are "T rue" or "F alse".
Function: Now()
Description:
The Now function returns a string representing the current UT C DateTime in the format
M/d/yyyy h:mm:ss tt .
Example: Now()
Example value returned 7/2/2021 3:33:38 PM
Function: NumFromDate(value)
Description: The NumFromDate function converts a DateTime value to Active Directory
format that is required to set attributes like accountExpires . Use this function to convert
DateTime values received from cloud HR apps like W orkday and SuccessF actors to their
equivalent AD representation.
Paramet ers:
Name Requir ed/
RepeatingType Notes
value Required String Date time string in ISO 8601 format. If the date variable is in
a different format, use FormatDateTime function to convert the
date to ISO 8601 format.
Example:ﾉExpand table
Now
NumFromDate
ﾉExpand table Workday example Assuming you want to map the attribute ContractEndDat e from
Workday, which is in the format 2020-12-31-08:00 to accountExpir es field in AD,
here's how you can use this function and change the timezone offset to match
your locale. NumFromDate(Join("", FormatDateTime([ContractEndDate], ,"yyyy-MM-
ddzzz", "yyyy-MM-dd"), " 23:59:59-08:00"))
SuccessF actors example Assuming you want to map the attribute endDat e from
SuccessF actors, which is in the format M/d/yyyy hh:mm:ss tt to accountExpir es field
in AD, here's how you can use this function and change the time zone offset to
match your locale. NumFromDate(Join("",FormatDateTime([endDate], ,"M/d/yyyy
hh:mm:ss tt","yyyy-MM-dd")," 23:59:59-08:00"))
Function: PCase(source, wordSeparators)
Description: The PCase function converts the first character of each word in a string to
upper case, and all other characters are converted to lower case.
Paramet ers:
Name Requir ed/Optional Type Notes
source Required String source value to convert to proper case.
wordSep aratorsOptional String Specify a set of characters that is used as word
separators (example: " ,-'")
Remarks:
If the wordSep arators parameter isn't specified, then PCase internally invokes the
.NET function ToTitleCase to convert the source string to proper case. The .NET
function ToTitleCas e supports a comprehensive set of the Unicode character
categories as word separators.
Space character
New line character
Control characters like CRLF
Format control characters
Connect orPunctuation characters like underscore
DashPunctuation characters like dash and hyphen (including characters such En
Dash, Em Dash, double hyphen, etc.)PCase
ﾉExpand table OpenPunctuation and ClosePunctuation characters that occur in pairs like
parenthesis, curly bracket, angle bracket, etc.
InitialQuot ePunctuation and FinalQuot ePunctuation characters like single
quotes, double quotes and angular quotes.
OtherPunctuation characters like exclamation mark, number sign, percent sign,
ampersand, asterisk, comma, full stop, colon, semi-colon, etc.
MathS ymbol characters like plus sign, less-than and greater-than sign, vertical
line, tilde, equals sign, etc.
CurrencyS ymbol characters like dollar sign, cent sign, pound sign, euro sign, etc.
Modi fierSymbol characters like macron, accents, arrow heads, etc.
OtherS ymbol characters like copyright sign, degree sign, registered sign, etc.
If the wordSep arators parameter is specified, then PCase only uses the characters
specified as word separators.
Example:
Let's say you're sourcing the attributes firstName and lastName from SAP
SuccessF actors and in HR both these attributes are in upper-case. Using the PCase
function, you can convert the name to proper case as shown below.
Expr ession Input Output Notes
PCase([firstName]) firstName =
"PABLO
GONSAL VES
(SECOND)""Pablo
Gonsalves
(Second)"As the wordSep arators parameter
isn't specified, the PCas e function
uses the default word separators
character set.
PCase([lastName]," '-
")lastName =
"PINT O-
DE'SIL VA""Pinto-
De'Silva"The PCas e function uses characters
in the wordSep arators parameter to
identify words and transform them
to proper case.
PCase(Join(" ",
[firstName],
[lastName]))firstName =
GREGOR Y,
lastName =
"JAMES""Gregory
James"You can nest the Join function within
PCase. As the wordSep arators
parameter isn't specified, the PCas e
function uses the default word
separators character set.
Function: RandomS tring(Length, MinimumNumbers, MinimumSpecialCharacters,
MinimumCapital, MinimumLowerCase, CharactersT oAvoid)ﾉExpand table
RandomString Description: The RandomS tring function generates a random string based on the
conditions specified. Characters allowed can be identified here.
Paramet ers:
Name Requir ed/
RepeatingType Notes
Length Required Number Total length of the random string. This
should be greater than or equal to the
sum of MinimumNumbers,
MinimumSpecialCharacters, and
MinimumCapital. 256 characters max.
MinimumNumber s Required Number Minimum numbers in the random string.
MinimumSpecialCharact ersRequired Number Minimum number of special characters.
MinimumCapital Required Number Minimum number of capital letters in the
random string.
MinimumLow erCase Required Number Minimum number of lower case letters in
the random string.
Charact ersToAvoid Optional String Characters to be excluded when
generating the random string.
Example 1: - Generate a random string without special character restrictions:
RandomString(6,3,0,0,3) Generates a random string with 6 characters. The string
contains 3 numbers and 3 lower case characters (1a73qt).
Example 2: - Generate a random string with special character restrictions:
RandomString(10,2,2,2,1,"?,") Generates a random string with 10 characters. The
string contains at least 2 numbers, 2 special characters, 2 capital letters, 1 lower case
letter and excludes the characters "?" and "," (1@!2BaR g53).
Function: Redact()
Description: The R edact function replaces the attribute value with the string literal "
[Redact]" in the provisioning logs.
Paramet ers:ﾉExpand table
Redact Name Requir ed/
RepeatingType Notes
attribut e/value Required String Specify the attribute or constant / string to redact
from the logs.
Example 1: Redact an attribute: Redact([userPrincipalName]) Removes the
userPrincipalName from the provisioning logs.
Example 2: Redact a string: Redact("StringToBeRedacted") Removes a constant string
from the provisioning logs.
Example 3: Redact a random string: Redact(RandomString(6,3,0,0,3)) Removes the
random string from the provisioning logs.
Function: RemoveDuplicates(attribute)
Description: The R emoveDuplicates function takes a multi-valued string and make sure
each value is unique.
Paramet ers:
Name Requir ed/
RepeatingType Notes
attribut eRequired Multi-valued
AttributeMulti-valued attribute that has duplicates
removed
Example: RemoveDuplicates([proxyAddresses]) Returns a sanitized proxyAddress
attribute where all duplicate values are removed.
Function: Replace(source, oldV alue, regexP attern, regexGroupName, replacementV alue,
replacementAttributeName, template)
Description: Replaces values within a string in a case-sensitive manner. The function
behaves differently depending on the parameters provided:ﾉExpand table
RemoveDuplicates
ﾉExpand table
Replace When oldValue and replacementV alue are provided:
Replaces all occurrences of oldValue in the source with replacementV alue
When oldValue and templat e are provided:
Replaces all occurrences of the oldValue in the templat e with the source value
When regexP attern and replacementV alue are provided:
The function applies the regexP attern to the source string and you can use the
regex group names to construct the string for replacementV alue
When regexP attern, regexGr oupName , replacementV alue are provided:
The function applies the regexP attern to the source string and replaces all
values matching regexGr oupName with replacementV alue
When regexP attern, regexGr oupName , replacementA ttribut eName are provided:
If source has a value, source is returned
If source has no value, the function applies the regexP attern to the
replacementA ttribut eName and returns the value matching regexGr oupName
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute from the
source object.
oldValue Optional String Value to be replaced in source or templat e.
regexP attern Optional String Regex pattern for the value to be replaced
in source. When
replacementA ttribut eName is used, the
regexP attern is applied to extract a value
from replacementA ttribut eName .
regexGr oupName Optional String Name of the group inside regexP attern.
When named replacementA ttribut eName is
used, we'll extract the value of the named
regex group from the７ Note
To learn more about regex grouping constructs and named sub-expressions, see
Grouping Constructs in R egular Expr essions .
ﾉExpand table Name Requir ed/
RepeatingType Notes
replacementA ttribut eName and return it as
the replacement value.
replacementV alue Optional String New value to replace old one with.
replacementA ttribut eName Optional String Name of the attribute to be used for
replacement value
templat e Optional String When templat e value is provided, we'll look
for oldValue inside the template and replace
it with source value.
Example 1: Using oldValue and replacementV alue to replace the entire source string
with another string.
Let's say your HR system has an attribute BusinessTitle. As part of recent job title
changes, your company wants to update anyone with the business title "Product
Developer" to "Software Engineer". Then in this case, you can use the following
expression in your attribute mapping.
Replace([BusinessTitle],"Product Developer", , , "Software Engineer", , )
source: [BusinessTitle]
oldValue: "Product Developer"
replacementV alue: "Software Engineer"
Expression output : Software Engineer
Example 2: Using oldValue and templat e to insert the source string into another
templatized string.
The parameter oldValue is a misnomer in this scenario. It's actually the value that gets
replaced.
Let's say you want to always generate login ID in the format
oldValue: "
regexP attern: "(?
Function: SelectUniqueV alue(uniqueV alueRule1, uniqueV alueRule2, uniqueV alueRule3,
…)
Description: Requires a minimum of two arguments, which are unique value generation
rules defined using expressions. The function evaluates each rule and then checks the
value generated for uniqueness in the target app/directory. The first unique value found
will be the one returned. If all of the values already exist in the target, the entry will get
escrowed, and the reason gets logged in the audit logs. There is no upper bound to the
number of arguments that can be provided.
This function must be at the top-level and cannot be nested.
This function cannot be applied to attributes that have a matching precedence.
This function is only meant to be used for entry creations. When using it with an
attribute, set the Apply Mapping property to Only during object cr eation .
This function is currently only supported for "W orkday to Active Directory User
Provisioning" and "SuccessF actors to Active Directory User Provisioning". It cannot
be used with other provisioning applications.
The LD AP search that SelectUniqueV alue function performs in on-premises Active
Directory doesn't escape special characters like diacritics. If you pass a string like
"Jéssica Smith" that contains a special character, you will encounter processing
errors. Nest the NormalizeDiacritics function as shown in the example below to
normalize special characters.
Paramet ers:
Name Requir ed/ R epeating Type Notes
uniqueV alueRule1 …
uniqueV alueRuleNAt least 2 are required,
no upper boundString List of unique value
generation rules to evaluate.
Example: Based on the user's first name, middle name and last name, you need to
generate a value for the UPN attribute and check for its uniqueness in the target AD
directory before assigning the value to the UPN attribute.
Expression:
ad-attr-mapping-exprSelectUniqueValue
ﾉExpand table
Generate unique value for userPrincipalName (UPN) attribute Sample input/output:
INPUT (PreferredFirstName): "John"
INPUT (PreferredLastName): "Smith"
OUTPUT : "John.Smith@contoso.com" if UPN value of John.Smith@contoso.com
doesn't already exist in the directory
OUTPUT : "J.Smith@contoso.com" if UPN value of John.Smith@contoso.com
already exists in the directory
OUTPUT : "Jo.Smith@contoso.com" if the above two UPN values already exist in
the directory
Function: SingleAppR oleAssignment([appR oleAssignments])
Description: Returns a single appR oleAssignment from the list of all
appR oleAssignments assigned to a user for a given application. This function is required
to convert the appR oleAssignments object into a single role name string. The best
practice is to ensure only one appR oleAssignment is assigned to one user at a time. This
function isn't supported in scenarios where users have multiple app role assignments.
Paramet ers:
Name Requir ed/ R epeating Type Notes
[appR oleAssignments] Required String [appR oleAssignments] object.
Function: Split(source, delimiter) SelectUniqueValue(
Join("@", NormalizeDiacritics(StripSpaces(Join(".", Description: Splits a string into a multi-valued array, using the specified delimiter
character.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String source value to update.
delimit erRequired String Specifies the character that will be used to split the
string (example: ",")
Example: Y ou need to take a comma-delimited list of strings, and split them into an
array that can be plugged into a multi-value attribute like Salesforce's P ermissionSets
attribute. In this example, a list of permission sets has been populated in
extensionAttribute5 in Microsoft Entra ID.
Expression: Split([extensionAttribute5], ",")
Sample input/output:
INPUT (extensionAttribute5): "P ermissionSetOne, P ermissionSetT wo"
OUTPUT : ["PermissionSetOne", "P ermissionSetT wo"]
Function: StripSpaces(source)
Description: Removes all space (" ") characters from the source string.
Paramet ers:
Name Requir ed/ R epeating Type Notes
source Required String source value to update.ﾉExpand table
Split a string into a multi-valued array
StripSpaces
ﾉExpand table Function: Switch(source, defaultV alue, key1, value1, key2, value2, …)
Description: When source value matches a key, returns value for that key. If source
value doesn't match any keys, returns defaultV alue. Key and value parameters must
always come in pairs. The function always expects an even number of parameters. The
function shouldn't be used for referential attributes such as manager.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Sour ce value to update.
defaultV alue Optional String Default value to be used when source doesn't match
any keys. Can be empty string ("").
key Required String Key to compare source value with.
value Required String Replacement value for the source matching the key.Switch
７ Note
Switch function performs a case-sensitive string comparison of the source and key
values. If you'd like to perform a case-insensitive comparison, normalize the source
string before comparison using a nested T oLower function and ensure that all key
strings use lowercase. Example: Switch(ToLower([statusFlag]), "0", "true", "1",
"false", "0"). In this example, the source attribute statusFlag may have values
("True" / "true" / "TRUE"). However, the S witch function will always convert it to
lowercase string "true" before comparison with key parameters.
Ｕ Caution
For the source parameter, do not use the nested functions IsPresent, IsNull or
IsNullOrEmpty. Instead use a literal empty string as one of the key values.
Example: Switch([statusFlag], "Default Value", "true", "1", "", "0"). In this
example, if the source attribute statusFlag is empty, the S witch function will return
the value 0.
ﾉExpand table Example: Define the time zone of the user based on the state code stored in Microsoft
Entra ID. If the state code doesn't match any of the predefined options, use default
value of "Australia/S ydney".
Expression: Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD",
"Australia/Brisbane", "SA", "Australia/Adelaide")
Sample input/output:
INPUT (state): "QLD"
OUTPUT : "Australia/Brisbane"
Function: ToLower(source, culture)
Description: Takes a source string value and converts it to lower case using the culture
rules that are specified. If there is no cultur e info specified, then it will use Invariant
culture.
If you would like to set existing values in the target system to lower case, update the
schema for your target application and set the property caseExact to 'true' for the
attribute that you're interested in.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute from the source object
cultur eOptional String The format for the culture name based on RFC 4646 is
languagec ode2-c ountr y/regionc ode2 , where languagec ode2 is the
two-letter language code and countr y/regionc ode2 is the two-
letter subculture code. Examples include ja-JP for Japanese
(Japan) and en-US for English (United S tates). In cases where a
two-letter language code isn't available, a three-letter code
derived from ISO 639-2 is used.Replace a value based on predefined set of options
ToLower
ﾉExpand table
Convert generated userPrincipalName (UPN) value to lower case Example: Y ou would like to generate the UPN value by concatenating the
PreferredFirstName and PreferredLastName source fields and converting all characters
to lower case.
ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName],
[PreferredLastName]))), "contoso.com"))
Sample input/output:
INPUT (PreferredFirstName): "John"
INPUT (PreferredLastName): "Smith"
OUTPUT : "john.smith@contoso.com"
Function: ToUpper(source, culture)
Description: Takes a source string value and converts it to upper case using the culture
rules that are specified. If there is no cultur e info specified, then it will use Invariant
culture.
If you would like to set existing values in the target system to upper case, update the
schema for your target application and set the property caseExact to 'true' for the
attribute that you're interested in.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute from the source object.
cultur eOptional String The format for the culture name based on RFC 4646 is
languagec ode2-c ountr y/regionc ode2 , where languagec ode2 is the
two-letter language code and countr y/regionc ode2 is the two-
letter subculture code. Examples include ja-JP for Japanese
(Japan) and en-US for English (United S tates). In cases where a
two-letter language code isn't available, a three-letter code
derived from ISO 639-2 is used.ToUpper
ﾉExpand table
Word Function: Word(S tring,W ordNumber,Delimiters)
Description: The W ord function returns a word contained within a string, based on
parameters describing the delimiters to use and the word number to return. Each string
of characters in string separated by the one of the characters in delimiters are identified
as words:
If number < 1, returns empty string. If string is null, returns empty string. If string
contains less than number words, or string doesn't contain any words identified by
delimiters, an empty string is returned.
Paramet ers:
Name Requir ed/
RepeatingType Notes
String Required Multi-valued
AttributeString to return a word from.
WordNumber Required Integer Number identifying which word number
should return
delimit ers Required String A string representing the delimiter(s) that
should be used to identify words
Example: Word("The quick brown fox",3," ")
Returns "brown".
Word("This,string!has&many separators",3,",!&#")
Returns "has".
This section provides more expression function usage examples.
Strip a known domain name from a user's email to obtain a user name. For example, if
the domain is "contoso.com", then you could use the following expression:
Expression: Replace([mail], "@contoso.com", , ,"", ,)ﾉExpand table
Examples
Strip known domain name Sample input / output:
INPUT (mail): "john.doe@contoso.com"
OUTPUT : "john.doe"
Generate a user alias by taking first three letters of user's first name and first five letters
of user's last name.
Expression: Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))
Sample input/output:
INPUT (givenName): "John"
INPUT (surname): "Doe"
OUTPUT : "JohDoe"
Add a comma between last name and first name.
Expression: Join(", ", "", [surname], [givenName])
Sample input/output:
INPUT (givenName): "John"
INPUT (surname): "Doe"
OUTPUT : "Doe, John"
This expression allows you to generate an identifier for a user that starts with 1000 and
is likely to be unique.
Expression: Join("", 1000, R eplace(ConvertT oUTF8Hex([objectId]), , "[a-zA-Z_]*", , "", , ))
Sample input/output:
INPUT : "d05e47b1-3909-445a-ba5e-ca60cbc0e4b4"Generate user alias by concatenating parts of first and
last name
Add a comma between last name and first name.
Generate an ID for a user based on their Microsoft Entra
ID object ID. Remove any letters from the ID and add
1000 at the beginning. OUTPUT :
"100064303565343762312333930392343435612626135652636136306362633065346234"
Automate User Provisioning/Deprovisioning to SaaS Apps
Customizing Attribute Mappings for User Provisioning
Scoping Filters for User Provisioning
Using SCIM to enable automatic provisioning of users and groups from Microsoft
Entra ID to applications
Account Provisioning Notifications
List of Tutorials on How to Integrate SaaS AppsRelated Articles
"MultiTenantOrganization.ReadWrite.All" ,"Policy.Read.All" ,"Policy.R
"Cairo"
Get-MgBetaTenantRelationshipMultiTenantOrganization | Format-List
CreatedDateTime : 1/8/2024 7:47:45 PM
Description :
DisplayName : Cairo
Id :
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationJoinRequestRecord
State : active
Tenants :
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/beta/$metadata#tenantRelationships/mult
iTenantOrganization/$entity]}
$MemberTenantIdB -DisplayName "Berlin" | Format-List
New-MgBetaTenantRelationshipMultiTenantOrganizationTenant -TenantID
$MemberTenantIdA -DisplayName "Athens" | Format-List
Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant | Format-
List
AddedByTenantId :
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[multiTenantOrgLabelType, none]}
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[multiTenantOrgLabelType, none]}
AddedByTenantId :
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[multiTenantOrgLabelType, none]}
Step 4: (Optional) Change the role of a tenant
PowerShell
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/beta/$metadata#tenantRelationships/mult
iTenantOrganization/tenants/$entity],
[multiTenantOrgLabelType, none]}
Step 5: (Optional) Remove a member tenant
PowerShell
Unable to read the company information from the directory.
Status: 404 (NotFound)
ErrorCode: Directory_ObjectNotFound
Date: 2024-01-08T20:35:11
...
Step 6: Sign in to a member tenant
"MultiTenantOrganization.ReadWrite.All" ,"Policy.Read.All" ,"Policy.R
eadWrite.CrossTenantAccess" ,"Application.ReadWrite.All" ,"Directory.
ReadWrite.All"
Step 7: Join the multitenant organization
PowerShell
Update-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest -
AddedByTenantId $OwnerTenantId | Format-List
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationJoinRequestTransitionDetails
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/beta/$metadata#tenantRelationships/mult
iTenantOrganization/joinRequest/$entity]}
Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant | Format-
List
AddedByTenantId :
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[multiTenantOrgLabelType, none]}
AddedByTenantId :
Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrg
anizationMemberTransitionDetails
AdditionalProperties : {[multiTenantOrgLabelType, none]}
Step 8: (Optional) Leave the multitenant
organization
PowerShell
Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -
MultiTenantOrganizationMemberId
the correct information for an administrative account.Disable SMS Sign-in options for the users
Import module
The value for phoneAuthenticationMethodId is 3179e48a-750b-4051-897c-
Get the User Details
validate the value for SmsSignInState
Disable Sms Sign-In for the user is set to ready
Disable-MgUserAuthenticationPhoneMethodSmsSignIn -UserId $userId -
administrator for more details.
Next steps
"Policy.Read.All" ,"Policy.ReadWrite.CrossTenantAccess"
Microsoft.Graph.PowerShell.Models.MicrosoftGraphInboundOutboundPoli
cyConfiguration
B2BCollaborationInbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BCollaborationOutbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BDirectConnectInbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BDirectConnectOutbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
IdentitySynchronization :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantIdentity
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyInboundTrust
IsServiceProvider :
TenantId :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyTenantRestrictions
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/v1.0/$metadata#policies/crossTenantAcce
ssPolicy/partners/$entity],
[crossCloudMeetingConfiguration,
-CrossTenantAccessPolicyConfigurationPartnerTenantId
$SourceTenantId ).UserSyncInbound
2. Get the tenant ID of the source and target tenants and initialize variables.IsSyncAllowed
-AutomaticUserConsentSettings $AutomaticUserConsentSettings
Step 4: Sign in to the source tenant
PowerShell
"Policy.Read.All" ,"Policy.ReadWrite.CrossTenantAccess" ,"Application
.ReadWrite.All" ,"Directory.ReadWrite.All" ,"AuditLog.Read.All"
Step 5: Automatically redeem invitations in the
source tenant
PowerShell
Microsoft.Graph.PowerShell.Models.MicrosoftGraphInboundOutboundPoli
cyConfiguration
B2BCollaborationInbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BCollaborationOutbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BDirectConnectInbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
B2BDirectConnectOutbound :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyB2BSetting
IdentitySynchronization :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantIdentity
SyncPolicyPartner
InboundTrust :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyInboundTrust
IsServiceProvider :
TenantId :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPo
licyTenantRestrictions
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/v1.0/$metadata#policies/crossTenantAcce
ssPolicy/partners/$entity],
[crossCloudMeetingConfiguration,
-AutomaticUserConsentSettings $AutomaticUserConsentSettings
Step 6: Create a configuration application in
the source tenant
PowerShell
Invoke-MgInstantiateApplicationTemplate -ApplicationTemplateId
"518e5f48-1fc8-4c48-9387-9fdf28b0dfe7" -DisplayName "Fabrikam"
Get-MgServicePrincipal -Filter "DisplayName eq 'Fabrikam'" |
Format-List
AccountEnabled : True
AddIns : {}
AlternativeNames : {}
AppDescription :
AppDisplayName : Fabrikam
Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttri
buteValue
DelegatedPermissionClassifications :
DeletedDateTime :
Description :
DisabledByMicrosoftStatus :
DisplayName : Fabrikam
Endpoints :
ErrorUrl :
FederatedIdentityCredentials :
HomeRealmDiscoveryPolicies :
Homepage :
https://account.activedirectory.windowsazure.com:444/applications/d
efault.aspx?metadata=aad2aadsync|ISV9.1|primary|z
Id :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphInformationalUrl
KeyCredentials : {}
LicenseDetails :
...
$ServicePrincipalId = "
$ServicePrincipalId -TemplateId "Azure2Azure" | Format-List
Id :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSche
dule
Schema :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSche
ma
Status :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationStat
us
SynchronizationJobSettings : {AzureIngestionAttributeOptimization,
LookaheadQueryEnabled}
TemplateId : Azure2Azure
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('
$ServicePrincipalId -BodyParameter $Params | Format-List
AppRoleId :
https://graph.microsoft.com/v1.0/$metadata#appRoleAssignments/$enti
ty]}
Step 11: Test provision on demand
PowerShell
$SynchronizationSchema = Get-
MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId
$ServicePrincipalId -SynchronizationJobId $JobId
$SynchronizationSchema .SynchronizationRules | Format-List
ContainerFilter :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphContainerFilter
Microsoft.Graph.PowerShell.Models.MicrosoftGraphGroupFilter
Id :
supportsProvisionOnDemand}
Name : USER_INBOUND_USER
ObjectMappings : {Provision Azure Active Directory Users, , ,
…}
Priority : 1
SourceDirectoryName : Azure Active Directory
TargetDirectoryName : Azure Active Directory (target tenant)
AdditionalProperties : {}
$RuleId = "
Microsoft.Identity.Health.CPP.Common.DataContracts.SyncFabric.Statu
sInfo
Value : [{"provisioningSteps":
[{"name":"EntryImport","type":"Import","status":"Success","descript
ion":"Retrieved User
Directory","timestamp":"2023-07-31T22:31:15.9116590Z","details":
{"objectId":
"
https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.stringKe
yStringValuePair]}
Step 12: Start the provisioning job
PowerShell
Start-MgServicePrincipalSynchronizationJob -ServicePrincipalId
$ServicePrincipalId -SynchronizationJobId $JobId
Step 13: Monitor provisioning
PowerShell
$ServicePrincipalId -SynchronizationJobId $JobId | Format-List
Id :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSche
dule
Schema :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSche
ma
Status :
Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationStat
us
SynchronizationJobSettings : {AzureIngestionAttributeOptimization,
LookaheadQueryEnabled}
TemplateId : Azure2Azure
AdditionalProperties : {[@odata.context,
https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('
Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitia
tor1
LoggedByService : Account Provisioning
OperationType :
Result : success
Azure Active Directory (target tenant)
TargetResources : {
Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitia
tor1
LoggedByService : Account Provisioning
OperationType :
Result : success
ResultReason : User 'user2@fabrikam.com' was updated in
Azure Active Directory (target tenant)
TargetResources : {
Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitia
tor1
LoggedByService : Account Provisioning
OperationType :
Result : success
ResultReason : User 'user2@fabrikam.com' will be created in
Azure Active Directory (target tenant) (User is active and assigned
in Azure Active Directory, but no matching
User was found in Azure Active Directory (target tenant))
TargetResources : {
the same value for property tenantId already exists.
https://graph.microsoft.com/v1.0/policies/crossTenantAccessPolicy/partne
rs/
conflicting object with one or more of the specified property values is
present in the directory.","details":
[{"code":"ConflictingObjects","message":"A conflicting object with one
or more of the specified property values is present in the directory.",
... }}}
(Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization
-CrossTenantAccessPolicyConfigurationPartnerTenantId
$SourceTenantId ).UserSyncInbound
-BodyParameter $Params
Next steps
ConvertT oBase64 ConvertT oUTF8Hex Count CStr DateAdd DateDiff
DateFromNum FormatDateTime Guid IgnoreFlowIfNullOrEmpty IIF InStr
IsNull IsNullOrEmpty IsPresent IsString Item Join Left Mid
NormalizeDiacritics Not Now NumFromDate PCase RandomS tring
Redact RemoveDuplicates Replace SelectUniqueV alue
SingleAppR oleAssignment Split StripSpaces Switch ToLower ToUpper
Word
Function: Append(source, suffix)
Description: Takes a source string value and appends the suffix to the end of it.
Paramet ers:
Name Requir ed/
RepeatingType Notes
source Required String Usually name of the attribute from the source object.
suffix Required String The string that you want to append to the end of the
source value.
Example: If you're using a Salesforce Sandbox, you might need to append another suffix
to all your user names before synchronizing them.
Expression: Append([userPrincipalName], ".test")
Sample input/output:
INPUT : (userPrincipalName): "John.Doe@contoso.com"
OUTPUT : "John.Doe@contoso.com.test"
Function: AppR oleAssignmentsComplex([appR oleAssignments])Append
ﾉExpand table
Append constant suffix to user name
AppRoleAssignmentsComplex
"True"),
"0", "False")
DateFromNum
ﾉExpand table
FormatDateTime
ﾉExpand table
[PreferredFirstName], [PreferredLastName]))), "contoso.com"),
Join("@", NormalizeDiacritics(StripSpaces(Join(".",
Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),
Join("@", NormalizeDiacritics(StripSpaces(Join(".",
Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")
)
SingleAppRoleAssignment
ﾉExpand table
Split