Office 365 provisioning

CyberArk for Office 365 + Provisioning can synchronize and provision users from Active Directory, LDAP, and the CyberArk Cloud Directory.

Support for basic authentication ends on October 1, 2023. For new Office 365 integrations, use token-based authentication.

Watch the videos.

  1. Configure token-based authentication.

  2. Configure provisioning.

Before you begin

Complete the following tasks before configuring provisioning for Office 365.

Provision and license users to Office 365

CyberArk supports provisioning the following object types to Office 365:

Object Description
Users

Includes all AD user objects

If you are using token-based authentication, the attributes listed in the following links are supported:

Contacts Includes all AD contact objects
Resources Includes resources such as a conference room mailbox
Groups CyberArk provisions both security and distribution groups from Active Directory to Azure AD as a mail-enabled group

Selecting object types provisions all objects of the selected type for that domain/login suffix (unless you reject specified objects with a script).

If you would rather provision only specific users that are members of an the Identity Administration portal role, you can add a role mapping. When you change an the Identity Administration portal role membership or a user’s AD group membership for an AD group that is a member of a role, CyberArk Identity synchronizes these changes automatically.

Licensing users in Office 365 requires mapping roles to licenses.

Refer to Set up app-specific provisioning for more information about how CyberArk Identity handles provisioning.

To automatically provision users with Office 365 accounts

  1. On the Application Settings page, make sure that you’ve already entered and verified your Office 365 administrator credentials and taken ownership of the domain.
  2. Select Enable provisioning for this application.

    A warning appears prompting you to disable the Azure AD Connect service before using CyberArk for provisioning.

  3. Disable the Azure Connect service if you haven't already done so, otherwise click Close to continue.

    You can disable the Azure Connect service with a PowerShell cmdlet.

    1. Connect to Azure AD for your Microsoft 365 subscription.

      Refer to Microsoft's documentation for details.

    2. Disable directory synchronization by running the following PowerShell cmdlet.

      Set-MsolDirSyncEnabled –EnableDirSync $false 
  4. Select either Preview Mode or Live Mode.

    • Preview Mode: Use Preview Mode when you’re initially testing the application provisioning or making configuration changes. The identity platform does a test run to show you what changes it would make but the changes aren’t saved.
    • Live Mode: Use Live mode when you want to use application provisioning in your production system. The identity platform does the provisioning run and saves the changes to both the identity platform and the application’s account information.
  5. Select objects to provision.

    If your deployment uses a hybrid deployment where you have on-premise Exchange servers in addition to Office 365 Exchange Online, you can select the login suffixes and domains, as well as objects in Active Directory domains, that you want to sync with Office 365.

    User objects from the CyberArk Cloud Directory are synced when you create or delete CyberArk Cloud Directory users. Active Directory objects are synced when the object’s Active Directory attributes are changed. If you want to sync existing CyberArk Cloud Directory or AD objects without making changes in the source directory, manually start a sync. Otherwise, objects will sync during the next daily sync. Refer to Provisioned account synchronization options for more information about manually syncing source directory objects.
    To sync objects from on-premise Exchange servers, make sure you have configured the connectors joined to those domains.
  6. Specify duplicate or existing account handling.

    Select either Overwrite or Keep to specify how CyberArk Identity handles situations when it determines that the user already has an account in the target application (same userPrincipalName).

    • overwrite: Updates and overwrite the target application user account information with the CyberArk Cloud Directory user account information. This includes removing data if the target account has a value for a user attribute that is not available from the CyberArk Cloud Directory
    • no overwrite: Keeps the target user account as it is; CyberArk Identity skips and doesn’t update the duplicate user account in the application.
    • do not deprovision: The user's account in the target application is not de-provisioned when a role membership change that would trigger a de-provisioning event occurs.
  7. Add the role mappings and licenses.

    Select whether you want to assign licenses mapped to each role a user is a member of, or if you want to assign a single license based on role mapping order.

    For example:

    • Licenses for all mapped roles: If a user is a member of two roles mapped to separate licenses, the user is assigned both licenses.

    • Single license based on order: If a user is a member of two roles mapped to separate licenses, the user is assigned the license mapped to the role that is higher in the role mapping list.

  8. To add role mappings and specify which users get provisioned to this application, click Add.

  9. The License and Attributes dialog box opens. CyberArk Identity connects to your account and lists the license profiles that are available for your account, including how many licenses have been used and how many are available.

  10. From the Role list, select the desired role.

    CyberArk Identity uses this role to synchronize the users that belong to this role.

  11. Select one or more license profiles that the users in the specified roles will have.

    If you select a license profile that has additional options, select or deselect those additional options as needed. For example, you can specify a specific software within an E1 license, if you need to do so.

    If you don’t specify a license, CyberArk Identity synchronizes the user but the user isn’t licensed to use any Office 365 features. The user can log in to Office 365, but the user cannot access Office 365 features.

    If you have local users that do not have Office 365 access but you still need to see the user accounts in Office 365, you can assign those users to a role that you do not assign a license to in the role mappings section. For example, this can be helpful if you want your Office 365 users to be able to email these local users.

  12. Click Save to save the role mapping and return to the Provisioning page.

  13. Continue adding roles and license profiles, as needed.

    • To change a mapping, select the role mapping and click Modify.
    • To remove a mapping, select the role mapping and click Delete.
    • To change the order of the role mappings, select the role mapping that you want to move higher in the list and click Move Up.
  14. (Optional) Update the provisioning script to exclude AD objects from synchronizing.

    See Exclude AD objects from synchronizing for more information.

    The provisioning script is intended for advanced users who are familiar with editing server-side JavaScript code. However, if you need to map users from different domains, you can make a simple edit to accommodate these users. For details, see Synchronize users with a different login suffix.
  15. Click Save to save the provisioning details.

You are now ready to synchronize users.

Deprovision users and other objects

CyberArk Identity deprovisions users and non-user objects based on deprovisioning rules that you define. You define a deprovisioning rule by selecting an event and mapping it to a deprovisioning action.

Deprovisioning events include the following.

  • Disabling or deleting users in Active Directory
  • Deleting non-user objects in Active Directory
  • Changing a user’s role membership

    To deprovision users by changing the user’s role membership, you must deselect Users from the Objects to provision grid. If Users is selected, CyberArk Identity will provision the user object at the next sync.
  • Deselecting the object type in the Objects to provision table

Deprovisioning actions are described in the following table.

Deprovisioning Action

Behavior

Remove User Licenses

Removes licenses from a user, but does not delete the user account from the application when you deprovision the user. Remove User Licenses is the default deprovisioning action.

You can restore licenses to the selected users (if the licenses are still available) by returning the user to the role, or adding the role mapping.

Select Remove User licenses if the user no longer requires a certain license, but you want to keep the user account in Office 365.

Delete Office 365 Account

Deletes the user account and all associated data. The data associated with those user accounts is held for a period of time defined by Exchange Online’s Messaging records management (MRM) retention policies and tags, then permanently deleted. Refer to https://technet.microsoft.com/en-us/library/dd297955(v=exchg.150).aspx for more information about Exchange Online’s retention policy.

You can find deleted users that have not been permanently deleted in the Office 365 admin center under Users > Deleted Users.

Select Delete Office 365 Account only if you are completely sure you do not need the user account

Leave User Unmodified

Leaves the user account and associated licenses unchanged in the application.

Select Leave User Unmodified if you need to make changes in Active Directory without impacting Office 365 users. If you leave users unmodified but later decide that you want to delete the user accounts in the application, you have to manually delete them with Powershell scripts.

Delete Office 365 Object Account

Deletes the non-user object account in the application. Non-user objects are deleted immediately and are not recoverable.

Examples of non-user objects are contacts, groups, and resources. Select Delete Office 365 Object Account only if you are completely sure you do not need the object account.

Leave Object Unmodified

Leaves the non-user object unchanged in the application.

Select Leave User Unmodified if you need to make changes in Active Directory without impacting Office 365 objects. If you leave non-user objects unmodified but later decide that you want to delete the objects in the application, you have to manually delete them with Powershell scripts.

To prevent conflicting rules, each deprovisioning event can only be mapped to a deprovisioning action once. For example, you can’t create the following two rules.

Event

Deprovisioning Action

User Disabled in Active Directory

Delete Office 365 Account

User Disabled in Active Directory

Remove User Licenses

To add a deprovisioning rule

  1. Click Add Rule under Deprovisioning Rules.

  2. Select a deprovisioning event from the Event drop-down menu.

  3. Select an action from the Deprovisioning Action drop-down menu, then click Add.

  4. Click Save when you are finished adding deprovisioning events.

    CyberArk Identity syncs source directory information with the application either immediately or during the next incremental sync, depending on the event. See Provisioned account synchronization options for more information.

    You can also manually start a synchronization job. See Synchronize user accounts with provisioned applications for more information.

  5. Verify your users were successfully provisioned by logging in to the Office 365 Admin Portal, expanding the Users tree, then clicking Active Users.

    You can then select any provisioned user to view licensing information for that user.

Exclude AD objects from synchronizing

The provisioning script features a method that you can use to exclude AD objects from synchronizing. You can use this method to prevent objects from appearing in the Global Address List, or prevent a set of objects from appearing in Office 365.

To configure the provisioning script to exclude AD objects from synchronizing

  1. In the Identity Administration portal, go to the Apps page and open your Office 365 application.
  2. On the Provisioning page, scroll to the Provisioning script section at the bottom, then click the downward arrow in the heading.

    The Provisioning Script Editor appears.

  3. Modify the provisioning script to exclude an object from synchronization by calling the reject statement. For example, if you want to exclude groups with SharePoint in the DisplayName, you could use the following script:

    if (isGroup()) {
        trace("CommonName=" + destination.CommonName);
        trace("DisplayName=" + destination.DisplayName);
        var displayName = String(destination.DisplayName).toLowerCase();
        if (displayName.indexOf("sharepoint")>=0)
        { reject("We are not syncing SharePoint groups"); }
    }

    Explanation

    The section of the script shown in this example only executes when syncing AD groups.

    The trace statements are a way to show some logging in the sync report or for troubleshooting purposes.

    The script converts the DisplayName to lowercase since the method that determines if an object should be excluded does so by finding lowercase occurrences of sharepoint in the display name.

    The reject statement causes O365 provisioning to exclude the group object from syncing. The reject statement takes a string to indicate a reason for the exclusion that appears in the sync report or logs. In this example, the string is We are not syncing SharePoint groups.

    Excluding a group does not exclude the group’s members.
  4. Click Save.

Modify the provisioning script to link AD objects

You can use the provisioning script to link one AD object to another by creating a source anchor. For example, you might want to link a user’s Manager field to the manager’s user object. The Office 365 provisioning script supports the following methods to link AD objects.

Method

Description

getObjectByPath

Searches the source AD for an object at the specified LDAP path.

Arguments: ldap path (string)

Returns: Domain Services object

guidToBase64

Converts a guid (string) to a base64-encoded string

Arguments: guid (string)

Returns: string (base64-encoded byte array)

The following example shows the usage of these two methods to create a source anchor.

var adObject = getObjectByPath("CN=Manager,CN=Users,DC=mydomain,DC=com");
if (adObject != null) {
    var objectGuid = adObject["objectguid"][0];
    trace("adObject.objectguid " + objectGuid);
    var sourceAnchor = guidToBase64(objectGuid);
    trace(sourceAnchor);
    destination.Manager = sourceAnchor;
    trace("destination.Manager" + destination.Manager);
}

Explanation

The previous script performs the following tasks.

  1. Passes the manager’s user object LDAP path to the getobjectByPath method, returning a Domain Services object (the manager’s user object).
  2. Passes the manager’s user object’s objectGUID property to the guidToBase64 method, which encodes the GUID as a base64 byte array (required for Office 365).
  3. Sets the Manager attribute in the destination to the base64 encoded GUID.

Synchronize users with a different login suffix

If your Active Directory domain or your login suffix (for use with CyberArk User Service) is not the same as your domain that you’ve verified in Office 365, then you need to modify the provisioning script to use your Active Directory domain (or login suffix) in the destination UPN (UserPrincipalName).

For example, if some users in the “Sales” role are in a domain called acmetester.com, then you’d need to modify the provisioning script to adjust for users with emails such as steve@acmetester.com.

To modify the Office 365 provisioning script for users from a different domain

  1. In the Identity Administration portal, go to the Apps page and open your Office 365 application.
  2. On the Provisioning page, scroll to the Provisioning script section, and click the downward arrow in the heading.
  3. Find the following line in the Office 365 provisioning script:

    destination.UserPrincipalName = destination.UserPrincipalName.split("@")[0] + "@" + "yourO365domain.com";
  4. Modify the provisioning script to include the desired domain.

    Using the example mentioned above, you would modify the line as follows:

    destination.UserPrincipalName = destination.UserPrincipalName.split("@")[0] + "@" + "acmetester.com";
  5. Click Save.

Best practices for synchronizing (migrating) users and mailboxes

If an Office 365 domain is federated with CyberArk then Office 365 redirects the user to CyberArk for authentication. The resulting token given back to Office 365 is required to have both the UPN and an Immutable ID which must match with the corresponding UPN and Immutable ID saved in Office 365. This section discusses recommended best practices to ensure your users retain all of their data and can successfully authenticate through CyberArk after migration.

This section is for advanced users who are comfortable administering Active Directory and Azure Active Directory using PowerShell cmdlets.

The following points are the basis for the recommended best practices. Refer to Terminology for migrating users and mailboxes for more information about the terms used below.

  • The Immutable ID in the token must match the Immutable IDs in Office 365 for the same UPN.

  • If the Immutable ID in the source (Active Directory or CyberArk Cloud Directory) is different from the one set in Office 365 for the same UPN, Office 365 rejects the token.

  • Both AD and CyberArk Cloud Directory users always have an Immutable ID.

  • Federated users in Office 365 must have an Immutable ID.

  • Microsoft does not support login if the Immutable ID is not set on a federated user in Office 365. This can happen if users were created in a managed domain, and the domain was later federated.

  • The Immutable ID can be changed only for a managed user.

  • The Immutable ID for a federated user is the base64-encoded value of the GUID of the source attribute.

  • For AD the default source attribute is objectGUID. For CyberArk Cloud Directory, it's the internal ObjectId.

  • Once the Immutable ID is set on a federated user, it cannot be set again.

  • To set it, we'll have to convert the user to a managed user first.

Terminology for migrating users and mailboxes

The following table defines terminology and acronyms used in the discussion of synchronizing users and mailboxes between Active Directory and Office 365.

Term

Definition

AD

Active Directory

AAD

Azure Active Directory. This is the directory service for Office 365. We’ll refer to it as Office 365 for convenience, except where discussing installation of the related PowerShell cmdlets.

CyberArk Cloud Directory User

Users created in the Identity Administration portal.

DC

Domain Controller

Federated users

Users synced into Office 365 from AD or CyberArk Cloud Directory. Once an Immutable ID is set for a federated user, it cannot be set again.; we’ll have to convert the user to a managed user first.

Federated domain

The Office 365 domain which is configured to redirect to an external identity provider for authentication.

Immutable ID

An attribute for Office 365 users. The value is the base64-encoded value of objectGUID for AD and ObjectID for CyberArk Cloud Directory users.

Managed users

Users in Office 365 which are not synced from AD (created via UI or PowerShell) .

Managed domain

The Office 365 domain which is not federated.

Office 365 User

Users created in Office 365.

UPN

UserPrincipalName.

Prerequisites for migrating users and mailboxes

Many migration procedures require the Azure AD PowerShell module. Refer to Microsoft's documentation for download links and more information about Azure AD PowerShell.

In addition, procedures requiring PowerShell cmdlets assume you have authenticated with the relevant directory (AD or Azure AD) so you can run the cmdlets.

Mailbox migration best practice

We recommend combining on-premise and online mailboxes in a hybrid environment if you plan to use both on-premise Exchange and Exchange Online.

It’s important to combine on-premise and online environments before syncing your users to Office 365 and assigning them Exchange Online licenses, otherwise your users will have a split mailboxes and might not receive mail. The only solution for split mailboxes is to delete one of the mailboxes, which might result in data loss.

An organization can combine both the on premise and online Exchange environment by running Exchange Hybrid Configuration wizard. In the Exchange hybrid case, the user will not have a split mailbox and Exchange will configure itself automatically. Refer to the following links for more information about Hybrid deployments and Microsoft’s Hybrid Configuration Wizard.

If you are only using Exchange Online and do not have an on-premise Exchange environment, refer to https://support.office.com/en-us/article/How-to-migrate-mailboxes-from-one-Office-365-tenant-to-another-65af7d77-3e79-44d4-9173-04fd991358b7 for more information about migrating mailboxes from one Office 365 domain to another.

User migration scenarios

The following table illustrates the recommended solutions to migrating users for common scenarios.

 

No matching users in target Office 365

Matching users in target Office 365 with an Immutable ID

Matching users in target Office 365 without an Immutable ID

AD to Office 365

no conflict

Save the Immutable ID from Office 365 in a different attribute in active directory

Overwrite empty Immutable IDs in Office 365 by provisioning

One Office 365 domain to another Office 365 domain

Mailbox migration best practice

Save the Immutable ID from Office 365 in a different attribute in active directory, then Mailbox migration best practice .

Save the Immutable ID from Office 365 in a different attribute in active directory, then Mailbox migration best practice

One AD domain to another AD domain

no conflict

Save the Immutable ID from Office 365 in a different attribute in active directory

Save the Immutable ID from Office 365 in a different attribute in active directory

CyberArk Cloud Directory User to AD to Office 365

Migrate CyberArk Cloud Directory users to AD

Migrate CyberArk Cloud Directory users to AD, then Save the Immutable ID from Office 365 in a different attribute in active directory

Migrate CyberArk Cloud Directory users to AD, then Overwrite empty Immutable IDs in Office 365 by provisioning

Overwrite empty Immutable IDs in Office 365 by provisioning

If your matching UPN users in Office 365 do not have an Immutable ID and therefore can’t authenticate, you can use provisioning to overwrite the empty Immutable ID attribute with the Immutable ID from the source directory (either AD or CyberArk Cloud Directory).

You do not have to worry about overwriting existing Immutable IDs; only empty Immutable IDs can be overwritten.

This approach to migrating users does not require scripting; however, the time required for a full sync is proportional to the number of users.

If this approach is not desirable, you can Manually set the Immutable ID in Office 365 as an alternative.

To overwrite the Immutable ID in Office 365 by provisioning

  1. Enable and configure Office 365 provisioning.
  2. In the Identity Administration portal, click Settings > Users > Outbound Provisioning.

  3. Select Office 365 in the Provisioning Enabled Applications drop-down menu, then click Start Sync.

    A message displays that prompts you for confirmation.

  4. Select bypass caching and re-sync all objects, then click Yes.
  5. Validate that one of the affected users is able to successfully login to Office 365 by clicking on the Office 365 app in the Identity User Portal.

Manually set the Immutable ID in Office 365

If you have a small number of matching users in Office 365 that need an Immutable ID attribute and you don’t want to touch provisioning settings or wait for a full provisioning sync as described in Overwrite empty Immutable IDs in Office 365 by provisioning, you can manually set Immutable IDs for Office 365 users.

You have to do this one by one, so it can become time consuming.

To manually set the Immutable ID in Office 365

  1. Get the Immutable ID for your source directory users (either AD or CyberArk Cloud Directory).

    AD users

    1. On a Domain Controller, or on a machine with Active Directory Powershell cmdlets installed, open PowerShell.
    2. Run the following command to see the immutable of a single user.

      Get-ADUser <name> | select UserPrincipalName,ObjectGuid, @{e={[system.convert]::ToBase64String($_.ObjectGuid.ToByteArray())};l="ImmutableId" }

      CyberArk Cloud Directory users

    3. Contact CyberArk support and request the ObjectID value for the users you want to migrate.
    4. Convert the ObjectID (which is the user’s GUID) into an Immutable ID using the following PowerShell example.

      $guid = [GUID]"ba2f9dce-2a8d-44ef-8c88-ae8d98393431";

      $base64 = [system.convert]::ToBase64String($guid.ToByteArray());

    5. Use the following cmdlet to set the Immutable ID of the target user in Office 365.

      Set-MsolUser -UserPrincipalName <upn> -ImmutableId <immutableId>
      Note that you can only set the Immutable ID once in a federated domain (and only if it was empty).

Save the Immutable ID from Office 365 in a different attribute in active directory

If you have Office 365 users that match the UPN of users in your source directory, but have different Immutable IDs set, those users will not be able to authenticate. You can work around this by saving the Immutable ID from Office 365 in a different AD attribute and later using the Identity Administration portal provisioning script to replace the AD user’s Immutable ID with the Office 365 Immutable ID saved in a different attribute.

This solution reduces migration downtime and is easily reversible; however, it can be time consuming.

If updating AD users is not desirable. Change the Immutable ID in Office 365.

If you don’t want to update AD or Office 365 users, you can Delete the Office 365 users.

To save the Immutable ID from Office 365 in a different attribute in AD

  1. In Active Directory, choose an attribute on the User object of type string where the Immutable ID from the Office 365 user will be saved.

    We recommend using the extensionAttribute1 attribute; however, any attribute of type string can be used.

    If the attribute extensionAttribute1 doesn't exist or there are no appropriate attributes on the User object in AD, then create a new single-valued attribute of type string.

    Do not name the attribute extensionAttribute* as these names are used by the Exchange server.

    Refer to http://social.technet.microsoft.com/wiki/contents/articles/20319.how-to-create-a-custom-attribute-in-active-directory.aspx for instructions on creating attributes.

  2. Find the Immutable ID(s) of your Office 365 user(s).

    The following command saves the UserPrincipalName and ImmutableId attributes of all Office 365 users in a csv file.

    Get-MsolUser -All | Sort UserPrincipalName | Select UserPrincipalName, ImmutableId | Export-Csv "O365Users.csv" -NoTypeInformation

    The following command gets the UserPrincipalName and ImmutableId attributes of a single Office 365 user.

    Get-MsolUser -UserPrincipalName <upn> | Select UserPrincipalName, ImmutableId
  3. (Optional) Remove from the CSV file any users that do not need their Office 365 Immutable ID saved in AD.
  4. Find the users in AD that match the UserPrincipalName values from Office 365 and update the desired attribute with the Immutable ID from Office 365.

    For many Office 365 users

    On the Domain Controller or a machine with the PowerShell Active Directory module installed, run the following script (copy/paste, then press Enter twice) to read the CSV file with the Office 365 users and update the attribute you specified (we recommend extensionAttribute1) on the user objects in AD.

    Update the attrName variable below with the correct attribute name if it is not extensionAttribute1.
    $attrName = "extensionAttribute1";
    Import-Csv .\O365Users.csv | %{
      $upn = $_.UserPrincipalName;
      $id = $_.ImmutableId;
      $users = Get-ADUser -Filter {UserPrincipalName -eq $upn};
      if($users.Length -eq 0) {
        Write-Host "No users were found in AD with the UPN: $upn";
      }
      elseif($users.Length -gt 1) {
        Write-Host "More than one user is found in AD with the UPN: $upn";
        $users | Select DistinguishedName;
      }
      else {
        Set-ADUser $users.ObjectGuid -Replace @{$attrName=$id};
        Write-Host "$attrName= '$id' UPN= $upn";
      }
    }
    Review the output of the previous step to verify no errors were reported.

    For a single Office 365 user

    On the Domain Controller or a machine with the PowerShell Active Directory module installed, run the following command.

    Set-ADUser <username> -Replace @{extensionAttribute1=<immutableid>}
  5. Verify that the Immutable IDs in AD match the ones from Office 365.

    For many Office 365 users

    The following PowerShell script saves the UserPrincipalName and extensionAttribute1 (or specified attribute) attributes of all the users from AD in a CSV file. Compare the two CSV files for verification.

    Modify the following script if the attribute in use is not extensionAttribute1
    Get-ADUser -Filter * -Properties extensionAttribute1 | Sort UserPrincipalName | Select UserPrincipalName, ExtensionAttribute1 | Export-Csv "ADUsers.txt" -NoTypeInformation

    For a single Office 365 user

    On the Domain Controller or a machine with the PowerShell Active Directory module installed, run the following command.

    Get-ADUser <username> -Properties extensionAttribute1
  6. Contact CyberArk support to enable the following tenant level configuration flags.

    • Flag Name: Office365V2.GetImmutableIdViaProvScript
    • Flag Value: true
    Both the flag name and value are case sensitive and must be set exactly the way they are typed.
  7. In the Identity Administration portal, modify the provisioning script in the Office 365 app to replace the AD user Immutable ID with the modified attribute.

    The following example of the provisioning script reads the immutable id from the attribute extensionAttribute1, if it is set. Ensure that the snippet is added to the isPerson() block.

    if (isPerson()) { 
      var iGUID = getSourcePropertyByName("extensionAttribute1");
      if (iGUID && iGUID.Length && iGUID[0]) { 
        destination.SourceAnchor = iGUID[0];
        trace("Updating the target with new immutable id: " + iGUID[0]);
      }
    } 
    

  8. In the Identity Administration portal, click Settings > Users > Outbound Provisioning.

  9. Select Office 365 in the Provisioning Enabled Applications drop-down menu, then click Start Sync.

    A message displays that prompts you for confirmation.

  10. Select bypass caching and re-sync all objects, then click Yes.
  11. Validate that one of the affected users is able to successfully login to Office 365 by clicking on the Office 365 app in the Identity User Portal.

Change the Immutable ID in Office 365

If you have Office 365 users that match the UPN of users in your source directory, but have different Immutable IDs set, those users will not be able to authenticate. You can change the Immutable ID in Office 365 to resolve the situation.

Changing Immutable IDs in Office 365 offers the following advantages:

  • allows for a clean migration

  • easier to manage after migration

  • does not require a full provisioning sync

Changing Immutable IDs in Office 365 has the following disadvantages:

  • tedious due to need to change the Immutable IDs for each user one at a time

  • requires a long maintenance window for Office 365 to update its federation status

  • hard to revert

To change the Immutable ID in Office 365

  1. Confirm that all existing Office 365 users are synced by CyberArk.

    You can do this by using PowerShell cmdlets to get the Office 365 domain status.

    get-msoldomainfederationsettings -domain <domain-name>

    The FederationBrandName attribute value should include CyberArk, similar to the following image.

  2. Unfederate the Office 365 domain.

    It might take up to 72 hours for Office 365 to update its status from Federated to Managed.
      1. Select the domain that you want to unfederate, then click Actions > Download Powershell Script.

      2. Run the downloaded PowerShell script O365FederationScript.ps1, entering R at the security warning to confirm that you want to run the script.

      3. Enter your Azure AD administrator credentials.

        The script presents options to view, federate, or unfederate the domain.

      4. Enter U to unfederate the domain you selected in the Identity Administration portal.

      5. Run the script again, this time entering V to view the federation settings, confirming success.

  3. Modify the affected user UPN domain suffixes in Office 365 and change it to an unfederated domain.

    The following PowerShell cmdlets change the UPN for all the users in Office 365.

    Get-MsolUser -All | Set-MsolUserPrincipalName -NewUserPrincipalName user1@mytenant.onmicrosoft.com.
  4. Get the ObjectGUID value for your AD users and convert it to Immutable IDs by running the following PowerShell script from the DC.

    This script gets the UserPrincipalName and ObjectGUID, converts the ObjectGUIDs to Immutable IDs, then saves these values in a CSV file named ADUsers.txt located in the current directory.

    Get-ADUser -Filter * | select UserPrincipalName,ObjectGuid, @{e={[system.convert]::ToBase64String($_.ObjectGuid.ToByteArray())};l="ImmutableId" } | Export-Csv "ADUsers.txt"
  5. Set the Immutable ID of the corresponding users in Office 365 with the ones from AD using the following PowerShell script in the PowerShell Azure AD module.

    This script reads the ADUsers.txt CSV file and updates the corresponding users in Office 365 with the new Immutable ID.

    Import-Csv "ADUsers.txt" | %{
      $upn = $_.UserPrincipalName;
      $id = $_.ImmutableId;
      $user = Get-MsolUser -UserPrincipalName $upn;  
      if($users.Length -eq 0) {
        Write-Host "No users were found in O365 with the UPN: $upn";
      }
      else {
        Set-MsolUser -UserPrincipalName $upn -ImmutableId $id;
        Write-Host "ImmutableId = '$id' UPN= $upn";
      }  
    }
    Review the output of the previous script thoroughly to ensure all Office 365 were found and updated correctly.
  6. Change the UPN domain suffix for the affected users back to the federated domain with the following command.

    The following PowerShell cmdlets change the UPN for all the users in Office 365.

    Get-MsolUser -All | Set-MsolUserPrincipalName -NewUserPrincipalName user1@mytenant.com
  7. In the Identity Administration portal, federate the domain.

      1. Select the domain that you want to federate, then click Actions > Download Powershell Script.

      2. Run the downloaded PowerShell script O365FederationScript.ps1, entering R at the security warning to confirm that you want to run the script.

      3. Enter your Azure AD administrator credentials.

        The script presents options to view, federate, or unfederate the domain.

      4. Enter F to federate the domain you selected in the Identity Administration portal.

      5. Run the script again, this time entering V to view the federation settings, confirming success.

Delete the Office 365 users

If you have a split mailbox situation (happens when you have licenses for Exchange and Exchange Online and you sync users before configuring a hybrid environment), you will have to delete the Office 365 to be able to migrate users.

Deleting Office 365 eliminates issues with Immutable IDs and avoids making provisioning changes; however, user data might be lost.

To delete Office 365 users

  1. Backup Office 365 user data.

    Refer to https://technet.microsoft.com/en-us/library/dn440734(v=exchg.150).aspx for more information about backing up Office 365 user data.

  2. Delete the users from Office 365 and then from the Office 365 recycle bin using the following AAD PowerShell cmdlets.

    Remove-MsolUser -UserPrincipalName <upn> -Force
    Remove-MsolUser -UserPrincipalName <upn> -Force -RemoveFromRecycleBin
  3. Use the following two cmdlets to confirm that the users are deleted.

    These cmdlets should not return any users.

    Get-MsolUser -UserPrincipalName <upn>
    Get-MsolUser -UserPrincipalName <upn> -ReturnDeletedUsers

Migrate CyberArk Cloud Directory users to AD

If you have CyberArk Cloud Directory users that have already been migrated to Office 365, you might want to also have those users in AD while keeping their Office 365 data. You will have to manually recreate the CyberArk Cloud Directory users in AD, then resolve Immutable ID conflicts when you sync the new AD users to Office 365.

You will only have Immutable ID conflicts if you have already synced CyberArk Cloud Directory users to Office 365.

To migrate CyberArk Cloud Directory users to AD

  1. Contact CyberArk support for a list of CyberArk Cloud Directory users’ UPNs.
  2. Create the users in AD using the same UPN.
  3. On the Office 365 provisioning page in the Identity Administration portal, create a deprovisioning rule where the event User Deleted in Active Directory results in the action Leave User Unmodified.

    Refer to To add a deprovisioning rule for more information.

    Deprovisioning events apply to CyberArk Cloud Directory in addition to Active Directory.
  4. Delete the CyberArk Cloud Directory user.

    You now have AD users and Office 365 users with matching UPNs, but conflicting Immutable IDs.

    The deprovisioning rule to leave users deleted in the source directory unmodified in Office 365 prevents the user from being deleted in Office 365.
  5. Refer to User migration scenarios for recommended solutions to the conflicting Immutable IDs.
  6. When you are finished, remove the deprovisioning rule to leave users unmodified in Office 365 when the user is deleted from the source directory.

Quick Reference for user migration tasks

The following tasks are frequently used to resolve conflicts with Immutable IDs that prevent successful user migrations. These tasks rely on PowerShell modules for the appropriate directory (AD or AAD) and assume you have already authenticated with that directory.

How to: convert a GUID into Immutable ID

$guid = [GUID]“ba2f9dce-2a8d-44ef-8c88-ae8d98393431";
$base64 = [system.convert]::ToBase64String($guid.ToByteArray());

How to: convert Immutable ID into a GUID

$b = [system.convert]::FromBase64String("uMjntePRV0qghxfRy+/PvA==");
new-object -TypeName System.Guid -ArgumentList(,$b);

How to: get Office 365 domain status (federated vs. unfederated)

Get-MsolDomain -DomainName <domain-name> | FL

How to: get the Immutable ID of an AAD user

For a single user

Get-MsolUser -UserPrincipalName <upn> | select UserPrincipalName,ImmutableId

For all users

Get-MsolUser -All | select UserPrincipalName,ImmutableId

For all users with the corresponding GUID

Get-MsolUser -All | select UserPrincipalName,ImmutableId, @{e={new-object -TypeName System.Guid -ArgumentList(,([system.convert]::FromBase64String($_.ImmutableId)))};l="ObjectGuid" }

How to: get the Immutable ID of an AD user

For a single user

Get-ADUser <name> | select UserPrincipalName,ObjectGuid, @{e={[system.convert]::ToBase64String($_.ObjectGuid.ToByteArray())};l="ImmutableId" }

For all users

Get-ADUser -Filter * | select UserPrincipalName,ObjectGuid, @{e={[system.convert]::ToBase64String($_.ObjectGuid.ToByteArray())};l="ImmutableId" }

How to: migrate mailboxes from one Office 365 domain to another Office 365 domain

Refer to https://support.office.com/en-us/article/How-to-migrate-mailboxes-from-one-Office-365-tenant-to-another-65af7d77-3e79-44d4-9173-04fd991358b7 for more information on how to migrate mailboxes.