Please help us by completing this survey

Go to survey
Documentation

Docs / Guides / Sync Active Directory to the portal

Sync Active Directory to the portal

Active Directory Synchronization is about replicating LDAP or portal users, groups and other security-related entities in another server or repository. In case of ‘AD to Portal’ sync this means creating the same set of entities in the Content Repository as in in Active Directory (AD).

The synchronization of users from Active Directory to the portal is performed by a task executor tool. For details about deploying and managing task executors please visit the following article:

The tool can be found in the web folder at the following location:

TaskManagement\TaskExecutors\SyncAD2Portal 

This tool is not intended to be executed manually. Please copy it to the appropriate Task Management location and let the task management framework execute the tool automatically.

The program connects to the AD servers according to the sync-trees specified in the setting and synchronizes all objects to the portal in the following order:

For general details please refer to Active Directory Synchronization.

Installation

To configure AD to portal sync follow these steps:

  1. Copy the executor folder (see above) to the agent machine
  2. Set the necessary values in the setting in the Content Repository (see below)

Settings

The settings for AD to Portal sync can be found here:

/Root/System/Settings/SyncAD2Portal.settings

By navigating to this file in Content Explorer there are two ways to edit the settings:

Please note that all values (AD and Content Repository paths, property names, etc.) are case sensitive. Please use the exact same names here as the ones you see in Active Directory.

The settings can be divided into the following main parts:

General settings

Servers

In this section you can define one or more server connections for the ad sync tool. You may have to define multiple servers in case you have multiple AD servers or your sync trees (see below) require different user credentials.

Server settings

Server properties

Please note that before setting a password above for a domain user that has access to the AD, you have to configure the certificate that we use for encrypting/decrypting the password.

Cryptography: setting a certificate

Sync-tree definitions

A sync tree defines a container that should be synced from a certain LDAP server to the portal. You may define exceptions and filters to shorten the list of sync objects.

At least one sync tree has to be defined for the process to do its job.

Sync trees

Sync-tree properties

PortalPath should be the exact match of Base DN (ie OU=x,OU=y,DC=a,DC=b should be mapped to /Root/IMS/a/y/x). To skip a line of levels (ie. /Root/IMS/a/x) all the containers (a and x) should be created manually and the SyncGuid field should be set manually before syncing!

User property mapping definitions

In this section one can define property mappings that determine the target fields of synchronized AD properties. Properties can be split to multiple fields, or multiple properties can be merged to a single field.

You have to select a property mapping definition for every sync tree above.

In special cases the different properties cannot be mapped one-on-one to each other. A separator character can be defined that helps concatenating or splitting property values. The following scenarios are supported:

Monitoring

As AD sync is a task executor, it provides a real-time progress that you can follow on the Task Monitor user interface.

Logging

The AD sync tool creates an extensive log next to itself in the file system. In case of errors or unexpected behavior you should examine the latest log for details.

SyncAD2Portal_20160522-132243.log

After every sync execution a summary is sent to the portal that will be logged into the Event log (execution time, number of errors).

Example/Tutorials

The following example displays the underlying JSON that contains all the settings that are accessible on the UI. This json can be edited by clicking on the Edit in browser link of the AD sync setting in Content Explorer.

{  
   "Enabled":true,
   "Scheduling": {
         "Frequency": 0,                                                
         "ExactTime": "01:00:00"                           
   },
   "ParallelOperations": 10,   
   "Servers":[  
      {  
         "Name":"testcorp",
         "LdapServer":"exampledc.examplecorp.local",
         "Novell":false,
         "LogonCredentials":{  
            "Username":"examplecorp\\adadmin",
            "Password":"",
            "Anonymous":false
         },
         "UseSsl":true,
         "Port":0,
         "SyncEnabledState":true,
         "SyncUserName":true,
         "DeletedPortalObjectsPath":"/Root/IMS/Deleted",
         "UserType":"User"
      }
   ],
   "SyncTrees":[  
      {  
         "Server":"testcorp",
         "BaseDN":"OU=Company001,DC=examplecorp,DC=local",
         "PortalPath":"/Root/IMS/examplecorp/Company001",
         "ADExceptions":[  ""  ],
         "UserFilter":"*",
         "GroupFilter": "*",
         "ContainerFilter":  "*",
         "SyncGroups": true,
         "SyncPhotos": true,
         "Mappings":"ActiveDirectory"
      }
   ],
   "MappingDefinitions":[  
      {  
         "Name":"ActiveDirectory",
         "Mappings":[  
            {  
               "Separator":",",
               "ADProperties":[  
                  {  
                     "Name":"mail",
                     "Unique":true
                  }
               ],
               "PortalProperties":[  
                  {  
                     "Name":"Email",
                     "Unique":true
                  }
               ]
            },
            {  
               "Separator":",",
               "ADProperties":[  
                  {  
                     "Name":"givenName",
                     "Unique":false,
                     "MaxLength":100
                  },
                  {  
                     "Name":"sn",
                     "MaxLength":100
                  },
                  {  
                     "Name":"initials",
                     "Unique":false,
                     "MaxLength":6
                  }
               ],
               "PortalProperties":[  
                  {  
                     "Name":"FullName"
                  }
               ]
            }
         ]
      }
   ]
}

FAQ

Q: How can I assign permission settings for the AD groups on the portal?

A: After the first synchronization users and groups will be created on the portal. Group membership information is also synchronized, so the portal groups will contain those users whose pairs in AD are members of the corresponding AD groups. You can assign permissions to the created portal groups after the first synchronization. These permission settings will remain unchanged for subsequent synchronizations, as long as the groups are not deleted from AD.

Q: Can I synchronize objects from AD after I have manually created them in the portal?

A: Only if you set the SyncGuid property of the portal object (let it be an OU, an ADFolder, a Group, or a User) to the value of the objectGuid property of the corresponding AD object, and start the sync afterwards. This method however is not advised. We encourage you to set up the AD sync configuration so that all portal objects are created by the first synchronization.

Q: What happens if I move a synced orgunit to another path in the same sync-tree in AD?

A: The orgunit and all of its contents will be moved to the corresponding place on the portal.

Q: What happens if I move a synced object in AD to a path that is not under any defined sync-tree?

A: This is considered as deletion and object is deleted from the portal (users are disabled, other objects are deleted).

Q: What happens if I move a synced object to a path that is under a different sync-tree in AD?

A: If the target sync-tree resides on the same AD server as the source sync-tree, the object is moved in the repository too.

Q: What happens if I move an unsynced object in AD under a sync-tree?

A: This is considered as creating a new object so a new object is created in the repository.

Q: What happens if I move a synced object out of a sync-tree in AD and then move it back later?

A: In case of users the object is deleted and thus moved to the appointed delete folder. Then it is moved back and its properties get updated - provided that the delete folder is under /Root/IMS. In case of other types of objects the object will be deleted and later a new object is created.

Q: What happens if I create a new user under a sync-tree but the properties defined cause an error on the portal?

A: The user is not created on the portal. Before you try to resync the user make sure to save it in the AD so that its whenchanged property is updated.

Q: What happens if I update a user in AD so that its name and some properties are changed but the changes cause an error on the portal?

A: The changes are not updated and the error is logged. Before you try to resync the user make sure to save it in AD so that its whenchanged property is updated.

Q: What happens if I create a new object in AD and an object with the same name (but no Guid) already exists on the portal?

A: If the existing object with the same name is not under a sync-tree, the object will not be created. Otherwise the new object still cannot be created, but the obstacle object is deleted from the portal, as there won’t be any corresponding object in the AD. Thus in the next sync phase the object from AD is synced and a new object on the portal is created.

Q: What happens if I put an unsynced user in a synced group in AD?

A: A warning is logged. This does not affect the other users in the group.

Q: What happens if I put an unsynced user in a synced group and later move the user under the same sync-tree in AD?

A: Groups are always updated, so the new user created on the portal will be a member of the synced group.

Q: What happens if I delete a user from AD?

A: The corresponding user on the portal is disabled and moved to the configured delete folder. It is renamed and its unique property values are prefixed with the date of deletion.

Q: What happens if I delete an orgunit or container from AD?

A: Every portal object contained in the corresponding container is deleted including the container itself. Contained users are disabled and moved to the delete folder.

Q: What happens if I delete a group from AD?

A: The corresponding portal group is deleted. Member users remain unchanged.

Q: What happens if I deleted a synced user from AD and then I create a new user with the same properties?

A: The deleted user is moved to the deleted folder and a new user is created with a new Guid.

Q: What happens if I remove a synced AD user’s property?

A: The value of the property on the portal is set to empty.

References

Is something missing? See something that needs fixing? Propose a change here.