How to map Active Directory users to Office 365 cloud users

Summary: When performing various hybrid actions in the Web Portal for an Active Directory user, a corresponding Cloud user can be found even if UPN does not match between on-premise and cloud user accounts.

Applies to: Cayosoft Administrator 7.3.0 or later

Configuration

There are cases where the UserPrincipalName (UPN) may differ between on-premises and cloud user accounts. For example, this can happen if Entra ID Connect is configured to use an attribute other than UserPrincipalName as the Entra ID username.

In such cases, additional configuration is required in the Cayosoft Administrator Console:

1. Navigate to Active Directory Extension > Advanced Settings.

2. Set Map cloud users by UPN to No (try anchor attributes first).

How user account is looked up in Cloud

When Map cloud users by UPN is set to No, Cayosoft Administrator searches for the corresponding user account in the cloud using the following attribute pairs:

• msDS-ExternalDirectoryObjectID (Active Directory) → ObjectId (Cloud)

• msDS-ConsistencyGUID (Active Directory) → ImmutableID (Cloud)

The lookup process follows these steps:

1. Primary Match: The msDS-ExternalDirectoryObjectID of the user in Active Directory is matched with the ObjectId of the corresponding user account in the cloud.

2. Fallback Match: If msDS-ExternalDirectoryObjectID is missing or not set, the msDS-ConsistencyGUID in Active Directory is matched with the ImmutableID in the cloud.

3. Final Attempt: If msDS-ConsistencyGUID is empty, the user account is looked up in the cloud by its UserPrincipalName (UPN).

4. Failure Condition: If the user account is still not found, an error is reported:

   Cloud user was not found for this Active Directory user by its external directory ID or anchor.

When Map cloud users by UPN is set to No, Cayosoft Administrator makes additional calls to the cloud to locate the corresponding Microsoft 365 user. As a result, hybrid web actions and rules may run slower compared to the default UPN-based mapping.

List of rules and web actions that support users with mismatched UserPrincipalName

Here is the list of rules and web actions that support users with mismatched UserPrincipalName:

Automation Rules and reports:

• Analytics collection | Microsoft Office 365

• Analytics collection | Quota Information

• AD Groups | Enforce License

• AD Groups | Validate License

• AD Groups | Enforce App Role Assignments

• AD Users | Set Automatic Replies (Out of Office Message, OOF)

• AD Users | Create Office 365 Accounts (Cloud)

• AD Users | Update Office 365 Accounts

• AD Users | Enforce License

• AD Users | Validate License

• AD Users | Assign Teams Policy

• AD Users | Set Office 365 Mailbox Settings

• AD Users | Process Scheduled Suspends

• AD Users | Suspend Expired AD Users

• AD Users | Suspend Users

• AD Users | Process Scheduled Undo Suspends

• AD Users Inactive | Suspend Accounts

• AD Users Expired Office 365 Linked User Status

• AD Users with Office 365 Licenses

• New User | Create Office 365 User

• New User | Office 365 User Enforce License

• New User | Office 365 Mailbox post creation tasks

• New User | Office 365 OneDrive post creation tasks

• Import SQL Data | Suspend AD Users

• Import Oracle Data | Suspend AD Users

• Office 365 Users | Change selected license option by AD Group

• Office 365 Users Billing Count by AD Group (Roll-up)

• Office 365 Users Billing Count by AD Group Membership

• Office 365 Users Inactive by AD Group Membership

• Text file | Suspend AD Users

• Suspend | Office 365 User

• Undo Suspend | Office 365 User

Web Actions

• Convert to Shared Mailbox

• Calendar Permissions

• Delete

• Mailbox

• MFA Settings

• New Equipment Mailbox

• New Room Mailbox

• New Shared Mailbox

• Office 365 License

• Priority Booking

• Properties

• Suspend User

• Teams Policies

• Undo Suspend