Synchronizing users and groups from Active Directory

Introduction

Organizations using an LDAP (or Active Directory) to hold user identities have a need to synchronize those identities and group memberships from the hosted directory to IBM Verify's Cloud Directory. This may be desirable for a variety of reasons. Some of the common ones are listed here:

Segment the user population that is allowed to authenticate to IBM Verify using External LDAP identity source.
Continue to manage group memberships on the corporate directory.
Part of a migration strategy to eventually enable Cloud Directory as the user registry.

IBM Verify Bridge for Directory Sync offers this capability and propagates changes on the hosted LDAP directory to Verify.

The goals of this article are:

Synchronize users and group memberships from a hosted Active Directory instance to IBM Verify for the purpose of authenticating users directly with this Active Directory from Verify.
Demonstrate delta updates.

Installation and configuration

Follow the download and installation instruction in order to install the Directory Sync utility on a Windows Server OS.
Once the installation succeeds it will create file structure as below:
Copy the file named "IcbLdapSync.json.ad-sample" and name the copy "IcbLdapSync.json". Then, proceed to the next steps to modify this file.

Get the Verify tenant details

Login to Verify tenant as admin user
Go to Security > API access
Create a new API client with entitlements: Manage users and standard groups and Synchronize users and groups
Copy the Client ID a Client secret of the newly created API client

Configure IcbLdapSync.json file

Use the IBM obfuscation tool to encrypt the client secret to prevent exposure.

C:\Program Files\IBM\DirectorySync> IcbLdapSync.exe -obf apisecret
OfFE5gNch3u5cJbeTj10Mm2Mbd1yS4eQjzqihj0lz7jGIG9fK7vNqTS90EmebtaU

Fill in the Verify tenant hostname, client ID and obfuscated client secret in the "ibm-auth-api" JSON object in the file.

"ibm-auth-api":{
    "timeout":100,
    "client-id":"96a1e9c0-a2a8-4fbf-8092-67caa02c6507",
    "obf-client-secret":"obfuscated_client_secret",
    "protocol":"https",
    "host":"abc.verify.ibm.com",
    "port":443,
    "max-handles":16
},

Configure the cloud-bridge json object where LDAP server details, base dn and search filter parameters need to be specified.

"cloud-bridge":{
    "max-ops": 512,
    "trace-file":"C:/Program Files/IBM/DirectorySync/logs/cloudbridge.log",
    "enable-op-log":true,
    "op-log-rollover": 2097152,
    "do-not-sync-delete":  false,
    "ldap-search-filter":"(&(|(objectClass=user)(objectClass=group))(|(cn=User90*)(cn=Sync*))(!(isCriticalSystemObject=*)))",
    "ldap-is-deleted-attr":"isDeleted",
    "ldap-poll-time":4,
    "log-stats-interval": 30,
    "ldap-base-dn": "OU=DirSyncRoot,DC=security,DC=com",
    "ldap":{
        "host":"AD_host",
        "port":389,
        "user":"cn=Administrator,cn=Users,dc=abc,dc=com",
        "obf-password":"obfuscated_password",
        "use-tls":false,
        "start-tls":false
    },

Define the userCategory and realm in the "user" object. The userCategory can be either "regular" or "federated", depending on whether the user should be allowed to use password authentication or not.
a. If "regular" user needs to be created, then set the realm to "cloudIdentityRealm". When the users are onboarded into Verify, they are sent an email with a temporary and randomly generated password. If a notification is not desired, set the notifyType attribute to "NONE" under the urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification section.
```
"user":{
    "ldap-object-classes": [ "user" ],
    "scim-external-id-attr":"externalId",
    "scim-outline":{
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:User":{
            "realm":"cloudIdentityRealm",
            "userCategory":"regular"
        },
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification": {
            "notifyType": "NONE"
        },
        "schemas":[
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification"
        ]
    },
```
b. If "federated" user needs to be created, then use the realm based on the identity provider created on Verify. Passwords authentication is not allowed for federated users.

Map Active Directory attributes to Cloud Directory attributes in the "ldap-to-scim" section. This is processed for both user creation and update. Each entry in the array defines how to map one Active Directory attribute.

"ldap-to-scim": [
    {
        "ldap":"sAMAccountName",
        "tweaks":{
            "append":""
        },
        "new-attr":{
            "scim":{"userName":"{{value}}"}
        },
        "mod-attr":{
            "scim":{
                "add":{"op":"add","path":"userName","value":"{{value}}"},
                "remove":{"op":"remove","path":"userName"},
                "replace":{"op":"replace","path":"userName","value":"{{value}}"}
            }
        }
    },

Configure the group json object define how user should get added or removed to the groups. The member attribute need to be crafted properly in order to maintain the correct group membership when groups get synced.

"group": {
    "ldap-object-classes": [ "group" ],
    "scim-external-id-attr":"externalId",
    "scim-outline": {
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification": {
            "notifyType": "NONE"
        },
        "schemas":[
            "urn:ietf:params:scim:schemas:core:2.0:Group",
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:Group",
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification"
        ]
    },
    "ldap-to-scim": [
        {
            "ldap":"member",
            "is-dn":true,
            "is-multi-value":true,
            "new-attr":{
                "scim":{"members":[{"type":"{{type}}","value":"{{value}}"}]}
            },
            "mod-attr":{
                "scim":{
                    "add":{"op":"add","path":"members","value":[{"type":"{{type}}","value":"{{value}}"}]},
                    "remove":{"op":"remove","path":"members[value eq {{jq_value}}]"},
                    "remove-all":{"op":"remove","path":"members"},
                    "replace":{"op":"replace","path":"members","value":[{"type":"{{type}}","value":"{{value}}"}]}
                }
            }
        },

📘
Note
Use the tweaks attribute to process and transform the values. Refer to Tweaks reference for more details.
Also, the current version of the Verify Bridge for Directory Sync only synchronizes users and groups within the "ldap-base-dn". If the user or group is moved out of the tree, it will no longer be managed.

Start the service

Once IcbLdapSync.json file is configured properly start the "IBM Verify Bridge for Directory Sync" service from the Windows Services list.

Validation in verify

Login to the Verify admin console to check if the users and group memberships are correctly synchronized.
Now, perform an update OR delete operation with a user or change a group membership on Active Directory. The corresponding change should reflect on Verify. All of these user and group operations are audited and visible in the "Admin Activity" report on the Verify Admin Console.

Troubleshooting

Errors may be logged in the Windows Event Log. Use this method for problem determination first.
Monitor the Directory sync logs for any errors. The location of the logs is specified in the "IcbLdapSync.json" file.

Introduction

Installation and configuration

Get the Verify tenant details

Configure IcbLdapSync.json file

📘Note

Start the service

Validation in verify

Troubleshooting

📘
Note