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 Security 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 Security 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 Security 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 Security 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
andSynchronize users and groups
- Copy the
Client ID
aClient 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
andrealm
in the "user" object. TheuserCategory
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 therealm
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 thenotifyType
attribute to "NONE" under theurn: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. Themember
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 Security 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.
Updated 5 months ago