Syncope Basics: Manage Active Directory

Prerequisite: Upgrade Syncope to 2.0.5

In order to take some benefits from the latest release of Syncope, this guide is based on Apache Syncope 2.0.5.

You can still follow the steps described in the first post of this "Syncope Basics" serie; the only difference will be in the first command where you should replace "-DarchetypeVersion=2.0.4" with "-DarchetypeVersion=2.0.5", or you might want to follow the proposed upgrade path.

Step 1: Add Pull Actions to pull memberships

Memberships won't be pulled without adding an ad-hoc Pull Actions class.

The simplest way to implement your pull action is to extend "org.apache.syncope.core.provisioning.java.pushpull.LDAPMembershipPullActions" and override the "getGroupMembershipAttrName()" method.

This method mast return the value of the connector configuration property "groupMemberReferenceAttribute".

See the sample below:

@Override
protected String getGroupMembershipAttrName(final Connector connector) {

     ConnConfProperty groupMembership = IterableUtils.find(connector.getConnInstance().getConf(),
              new Predicate<ConnConfProperty>() {

          @Override
          public boolean evaluate(final ConnConfProperty property) {
              return "groupMemberReferenceAttribute".equals(property.getSchema().getName())
                    && property.getValues() != null && !property.getValues().isEmpty();
           }
     });

     return groupMembership == null ? "member" : groupMembership.getValues().get(0).toString();
}

Make sure your class has the correct package "org.apache.syncope.core.provisioning.java.pushpull" (see here for more info).

Then, simply rebuild and restart Syncope.

Step 2: Create and configure your Active Directory connector instance

Go under Topology and click on your preferred connector location (local, for example "file://"... or remote like "connid://testconnectorserver@host:4554"); then click the "Add new connector" button on the right.

Set a name as "Display name", make sure the "Location" of your Active Directory (JNDI) connector bundle is correct.

Click "next" and configure your connector instance as below:

Move to the next tab ("Capabilities") and choose the preferred ones.

At last, click the "Finish" button.

Step 3: Configure your Active Directory external resource

Click on Active Directory connector and then select "Add new resource".

Set the name you like and set other resource attributes.

IMPORTANT: you have to add the "LDAPMembershipPropagationActions" action class to the resource, otherwise memberships would not get propagated:

Click "Next", optionally override "Capabilities" and then "Finish".

Click on the just created resource and select "Edit provisioning rules". Click the "+" button, choose the "Object Type" and define a mapping for that specific "Object Type" by clicking on "Next" button.

Configure mappings (USER / GROUP mapping) between Syncope user / groups attributes and Active Directory user / groups attributes.

For USER:

For GROUP:

After that click the "Save" button.

Step 4: Propagation testing

With the above configuration Syncope is ready to manage users and groups on Active Directory.

Let's start by creating some samples that will be propagated to AD:

• create user user1, fill all required information and assign the AD resource to it: you will find the AD entry "CN=user1,CN=Users,DC=tirasa,DC=net".
• create group test_AD_group_3 and assign the AD resource to it: you will find the AD entry "CN=test_AD_group_3,CN=Users,DC=tirasa,dc=net".
• create user test_membership and assign it to group test_AD_group_3: you will find "CN=test_membership,CN=Users,DC=tirasa,DC=net" among members attribute values of "CN=test_AD_group_3,CN=Users,DC=tirasa,dc=net" and, viceversa, "CN=test_AD_group_3,CN=Users,DC=tirasa,dc=net" among "memberOf" attribute values of "CN=test_memebership,CN=Users,DC=tirasa,DC=net", as you can see below:
  

It is possible to see the results on your AD resource from Syncope console by clicking on the resource and selecting "Explore resource":

for USER... and GROUP

Step 5: Synchronization testing

Some additional configuration is needed for enabling synchronization, e.g. in this case the ability to pull data from an external Active Directory resource.

Go to "Topology", select the AD resource and click on "Pull tasks". Then add a new pull task by clicking the "+" button.

Set name and description as you like, choose the class provided at the step 1 from "Actions" list and set the other elements as in the images below: 

At this point, Syncope is ready to manage users and groups from Active Directory.

IMPORTANT: if you are not performing a "Full Reconciliation", execute the created Pull Task once in order to initialize the "latestSyncToken" at the current date.

Create some sample users and groups in Active Directory, then go back to Syncope Admin Console and execute the "Pull Task" again: you will find users, groups and memberships in Syncope, created according to data provided in Active Directory.

One remarkable test you can do is to delete all previously created users and groups in Syncope (be careful not to delete those in AD too, so it is important that the AD resource in Syncope does not have the "DELETE" capability) and just execute the pull task.
You'll see all users and groups in Syncope and a more noticeable thing would be that all memberships will be synched too:

To check the memberships, go to "Realms" -> "Groups", click test_AD_group_3 and select "members" to check that:

Advanced: Pull Organizational Units as Syncope Realms

Let's start by creating some "ou" in your AD and add some users / groups to them, somthing like this:

Now, go to Syncope Admin Console and edit your connector by enabling the "Override?" checkbox for the following elements :

• Root suffixes
• Base contexts for group entry searches (this is necessary only if you use the AD connector v1.3.3 due to an issue, it was fixed from v1.3.4 so if you want to use v1.3.4 you have to edit main parent "pom.xml", add the property: "<connid.ad.version>1.3.4</connid.ad.version>" inside the "<properties> ... </properties>" tag and rebuild)
• Default Uid
• Uid Attribute

like this:

Now, create a new resource and give it a name like "AD_realms". Leave all fields as they are except for the text fields in the second step of the creation wizard, you should fill them like this:

Edit the "Provision rules" of the resource in order to provide a correct mapping for Realms:

Now it is the moment to create the Pull Task to actually import realms from AD to Syncope.

Before doing that, you must define a Java class to teach Syncope how to follow the correct realms relationship and structure as it is in AD. So, let's create the class "ADRealmsPullActions" with this content.

For this tutorial purpose that class should be placed in the "org.apache.syncope.core.provisioning.java.pushpull" package, as above.

We can now create the Pull Task and link that action class to it:

At this point you should see something like this in the "Realms" section in Syncope:

How to test

I have prepared a sample project for this purpose: assuming to have GIT and Maven properly configured:

$ git clone https://github.com/Tirasa/syncopeWithActiveDirectory.git
$ mvn -P all clean install
$ cd enduser
$ mvn -P embedded,all

Point your browser to http://localhost:9080/syncope-console

Exercise: pull users and groups from "Realms" to Syncope

At this point you should be capable to try something by yourself. Check again the screenshots at the beginning of the "Advanced section" above and focus on the users and groups I have created as samples. Play with resource / connector configurations in order to succeed in pulling those from "Realms" ou in AD to Syncope.

3 VOTIYes, Excellent!