Skip to main content

LDAP Apache Directory

The purpose of this guide is to provide detailed information regarding the Apache Directory connector. There are a number of things you can learn about this connector here, including information about its configuration and deployment.

About LDAP Apache Directory Connector​

In IDHub, you can create and onboard LDAP Apache Directory applications using the connector.

Connector Version​

ComponentVersion
LDAP Apache Directory ConnectorVer 1.0
Target SystemApache Directory

Connector Operations​

OperationSupported?
User Management
Create userYes
Update userYes
Delete userYes
Enable userYes
Disable userYes
Group Management
Create groupYes
Delete groupYes
Organizational Unit Management
Create organizational unitYes
Delete organizational unitYes

Connector Components​

The components of the connector include Connector Application, Connector Application Configuration, Connector Service Provider Interface, Splice, and Splice configuration.

These connection components contain precise connectivity and setup information for your target system. The connector takes information from these files to allow you to quickly and efficiently onboard your applications using a single, streamlined UI.

Connector Architecture​

The connector's architecture is constructed in accordance with the diagram below: The connector architecture primarily consists of a connector application and a target system component, as seen in the screenshot up above. The native communication with the target system is handled by the target system by leveraging the SPI implementation of the Apache Directory Specific connection. This architecture is implemented because it allows for rapid and straightforward connector deployment as well as precise versioning capabilities.

The connector is configured to run in one of the following modes:

  • Target Resource reconciliation
    • Users are instantly created and changed on IDHub in this situation if you rely on the Apache Directory application as the trusted source. When user records match the reconciliation criteria, the Apache Directory SDK retrieves them and sends them to IDHub. Each user record retrieved from the target system is cross-checked against existing IDHub Users. If there is a match between the target system record and the IDHub User, the User attributes are changed to reflect the changes made to the target system record. If no matches are identified, the target system record is utilized to generate an IDHub User.
  • Account management
    • This entails using IDHub to add, modify, or remove users from the target system.
      • During provisioning, the connector invokes the target system's Apache Directory SDK for provisioning tasks.
      • The target system's SDK accepts provisioning data, does the necessary actions there, and then sends IDHub the result back from the target system. Applications can carry out create, read, update, and delete (CRUD) actions on the target system using the Apache Directory SDK.
note

In developing the connector, we adhere to this fundamental architecture. The IDHub team will handle the connector modification section appropriately based on your unique business requirements if there are any improvements, extra specifications, or variations.

Connector Features​

Full Reconciliation and Incremental Reconciliation​

Full reconciliation can be performed to bring all existing user data from the target system to IDHub. If the target system has an attribute that stores the timestamp at which an item is created or modified, you can configure your connector for incremental reconciliation once the first full reconciliation operation has been completed.

info

The connector's future release version will incorporate incremental & batched recon, which is not supported by the present version of the connector.

Limited Reconciliation​

Records from the target system can be reconciled depending on a defined filter condition. You can define the subset of newly added or updated target system records that must be reconciled in order to restrict or filter the records that are fetched into IDHub during a reconciliation process. You can specify the conditions in which the reconciliation will take place.

Batched Reconciliation​

You can break down a reconciliation run into batches by specifying the number of records that must be included in each batch.

Support for Connector Server​

By using one or more connector servers, the connector architecture permits your application to communicate with externally deployed bundles. In other words, a connector server enables remote execution of an IDHub connector.

Creating an Application by using the Connector​

Pre-requisites​

Establish connection parameters to the LDAP server​

In this step you create the server instance, establish the connection parameters, and identify the entry point in the LDAP hierarchy.

  1. Start Apache Directory Studio.
  2. In the LDAP Servers view, create an LDAP server:
    • Click the New Server button in the view toolbar.
    • Select the default Apache DS 2.0.0.
    • Click Finish.
    • Double-click the server to see its content in the display area. Notice the port number and the available partitions
  3. In the LDAP Servers view, select and start the server. If it does not start on the first try, try again, or delete and recreate the server.
  4. After the server is started, in the Connections view, create a new connection:
    • Click the New Connection button in the view toolbar.
    • Enter ODM1 as the connection name (the name is not used anywhere else).
    • Enter the hostname and and the port number
  5. Click Next. In the next screen, enter uid=admin,ou=system for Bind DN or user, and secret for Bind password. This is the default user required to access the Apache Directory server
  6. Click Check Authentication. Authentication must be successful before moving on. Then click Finish.

Create the first user​

In this step, you create an organization unit (ou) in which to place users, and create the first user

  1. In the LDAP Browser view, right-click dc=example,dc=com, and select New > New Entry.
  2. Select Create entry from scratch, and click Next.
  3. Under Available object classes, find organizationalUnit and add it to Selected objects classes
  4. Click Next. Then, for the RDN (relative distinguished name) field, enter ou=users
  5. Click Next and then Finish. The LDAP Browser shows that your domain now has an organizational unit in which to place users
  6. Create the first user, Jim. In the LDAP Browser view, right-click ou=users, and select New > New Entry.
  7. Select Create entry from scratch, and click Next.
  8. Under Available object classes, find inetOrgPerson and add it to Selected object classes. This is a general purpose object class that holds attributes about persons.
  9. Click Next. For RDN, enter uid=Jim
  10. Create the first user, Jim. In the LDAP Browser view, right-click ou=users, and select New > New Entry.
  11. Select Create entry from scratch, and click Next.
  12. Under Available object classes, find inetOrgPerson and add it to Selected object classes. This is a general purpose object class that holds attributes about persons.
  13. Click Next. For RDN, enter uid=Jim

Create the first group​

  1. In the LDAP Browser view, right-click dc=example,dc=com, and select New > New Entry.
  2. Select Create entry from scratch, and click Next.
  3. Under Available object classes, find organizationalUnit and add it to Selected objects classes.
  4. Click Next. Then, enter for the RDN field, ou=groups. Click Next and then Finish. The LDAP Browser views shows an organizational unit in which to place groups.
  5. Create the first group, Checkers. In the LDAP Browser view, right-click ou=groups, and select New > New Entry.
  6. Select Create entry from scratch, and click Next.
  7. Under Available object classes, find groupOfNames and add it to Selected object classes
  8. Click Next. For RDN, enter cn=Checkers.
  9. Click Next. In the DN Editor, click Browse and select Jim under ou=users.
  10. Click OK and then Finish. The group Checkers now has a member Jim.

Onboard the Application in IDHub​

tip

Click here for the detailed steps for onboarding the application to IDHub

Configuring the Connector​

Connectors use connection-related parameters to connect to IDHub with your target system and perform connector operations when creating a connected application. IDHub requires the following connection-related parameters in order to connect to an Apache Directory application.

ParameterDefault valueDescription
idN/AThe LdapServer identifier
transportsN/AThe LdapServer transports
confidentialityRequiredfalseTells the server to accept requests using startTLS or LDAPS
allowAnonymousAccesstrueTells the server to accept Anynymous requests or not
maxSizeLimit1000The maximum number of entries to return
MaxTimeLimit1000The maximul time before an operation is aborted (in seconds)
saslHostN/AThe name of this host, validated during SASL negotiation
saslPrincipalldap/ldap.example.com@EXAMPLE.COMThe service principal, used by GSSAPI
saslQop"auth, "auth-int", "auth-conf"The quality of protection (QoP), used by DIGEST-MD5 and GSSAPI
saslRealmsN/AThe realms serviced by this SASL host
directoryServiceN/AThe reference to the associated DirectoryService
keystoreFileThe JVM keystoreThe keystore file to use to store certificates
certificatePasswordN/AThe certificate passord

Attribute Mappings for the Connector​

LDAP SchemaUser Schema in IDHubSync DirectionIsVisibleExampleType of Attribute
displayNamedisplayNameBi-DirectionalVisibleJohn33
firstNamefirstNameTarget system to IDHubVisibleJohn
mailemailTarget system to IDHubVisibleJohn@sath.comAccount Name Field
snlastNameTarget system to IDHubVisibleGarret
cnloginTarget system to IDHubVisibleJohn_g33Recon Key
telephoneNumberphoneNumberTarget system to IDHubVisible355-5656-6666
tip
  • Sync Direction of the Attributes depends on whether you regard LDAP Apache Directory as your Trusted Source.
  • You should only synchronize from IDHub to Apache Directory and not the reverse if Apache Directory is not a trusted system in your case.
Possible Recon KeyPossible Recon Key Values
mailJohn@sath.com
userLoginJohn33
employeeNumberJohn8678

Connector Application Configuration​

Connector application is designed such that it works as the wrapper application to the different scim adapters. This majorly consists of the following:

Authentication​

  • Basic Authentication is required
  • The encrypted values of username and password will be stored in the properties file

Resource Type​

These are the two resource types available for the IDHub connector. The "resourceName" attribute value in rest api calls will have one of these values.

  • Account - user account in the target system - this will include entitlement membership
  • Entitlement -available entitlements in the target system

Connector Splice Design​

Account Schema​

The Account Schema configuration of the LDAP connector Splice is as follows:

{
  "id": "urn:sath:params:scim:schemas:ldap:2.0:Account",
  "name": "Account",
  "description": "User Account",
  "schemas": [
    "urn:sath:params:scim:schemas:core:2.0:Schema"
  ],
  "meta": {
    "resourceType": "Schema",
    "location": "/v2/Schemas/Accounts"
  },
  "attributes": [
    {
      "name": "cn",
      "multiValued": false,
      "description": "The UserLogin / id of the user.  REQUIRED.",
      "returned": "always",
      "uniqueness": "global",
      "required": true
    },
    {
      "name": "givenName",
      "type": "string",
      "multiValued": false,
      "description": "The FirstName of the user.  REQUIRED.",
      "returned": "always",
      "required": true
    },
    {
      "name": "sn",
      "type": "string",
      "multiValued": false,
      "description": "The LastName of the user.  REQUIRED.",
      "returned": "always",
      "required": true
    },
    {
      "name": "displayName",
      "type": "string",
      "multiValued": false,
      "description": "The DisplayNameame of the user.  REQUIRED.",
      "returned": "always",
      "required": false
    },
    {
      "name": "telephoneNumber",
      "type": "string",
      "multiValued": false,
      "description": "The phoneNumber of the user.",
      "returned": "always",
      "required": false
    },
    {
      "name": "mail",
      "type": "string",
      "description": "The mail alias for the user.",
      "required": true,
      "returned": "always",
      "multiValued": false
    },
    {
      "name": "entityBaseDN",
      "type": "string",
      "description": "The user base DN",
      "required": false,
      "returned": "always",
      "multiValued": false
    },
    {
      "name": "password",
      "description": "Account password, Required for Creation Only",
      "required": false,
      "returned": "never",
      "multiValued": false
    },
    {
      "name": "entitlements",
      "description": "Assigned entitlement list",
      "multiValued": true,
      "required": true
    }
  ],
  "schemaConfiguration": {
    "id": "cn",
    "objectClass": [
      "top",
      "person",
      "organizationalPerson",
      "inetOrgPerson"
    ],
    "otherDefaultAttributes": {
 
    },
    "relationshipAttribute": "memberOf",
    "namingAttribute": "cn",
    "defaultBaseContainerDN": "ou=People,dc=iamsath,dc=com"
  }
}
Resource Type Schema​
{
  "schemas": "urn:sath:params:scim:schemas:core:1.0:Account",
  "matching-attributes": [
    "uid",
    "mail"
  ],
  "attribute-map": {
    "Fname": {
      "attribute": "Fname",
      "type": ""
    },
    "Lname": {
      "attribute": "Lname",
      "type": ""
    },
    "givenName": {
      "attribute": "Fname",
      "type": ""
    },
    "sn": {
      "type": "",
      "query": ".Lname"
    },
    "displayName": {
      "attribute": "displayName"
    },
    "name": {
      "attribute": "displayName"
    },
    "id": {
      "attribute": "userName"
    },
    "userName": {
      "attribute": "userName"
    },
    "email": {
      "attribute": "email",
      "type": "",
      "query": "{mail: .emails[].value}"
    },
    "phone": {
      "attribute": "phone",
      "type": ""
    },
    "title": {
      "attribute": "title",
      "type": ""
    },
    "addresses": {
      "attribute": "addresses",
      "type": ""
    },
    "department": {
      "attribute": "department",
      "type": ""
    },
    "userType": {
      "attribute": "userType",
      "type": ""
    },
    "organization": {
      "attribute": "organization",
      "type": ""
    },
    "employeeNumber": {
      "attribute": "employeeNumber",
      "type": ""
    },
    "manager": {
      "attribute": "manager",
      "type": ""
    }
  },
  "scripts": {
  "insert": ["dn: cn=${this.uid},ou=${this.ou},dc=iamsath,dc=com\nobjectClass: top\n#person\nobjectClass: person\nsn: ${scim.name}\ncn: ${scim.Fname} ${scim.Lname}\ntelephoneNumber: ${scim.phone}\nseeAlsodescription:\n#org person\nobjectClass: organizationalPerson\ntitle: ${scim.title}\nx121Address:\nregisteredAddress:\ndestinationIndicator:\npreferredDeliveryMethod:\ntelexNumber:\nteletexTerminalIdentifier:\ninternationaliSDNNumber:\nfacsimileTelephoneNumber:\nstreet: ${scim.addresses.streetAddress}\npostOfficeBox:\npostalCode: ${scim.addresses.postalCode}\npostalAddress: ${scim.addresses.region}\nphysicalDeliveryOfficeName:\nou: People\nst: ${scim.addresses.region}\nl: ${scim.addresses.locality}\n# inet org person\nobjectClass: inetorgperson\naudio:\nbusinessCategory:\ncarLicense:\ndepartmentNumber: ${scim.department}\ndisplayName: ${scim.displayName}\nemployeeNumber: ${scim.employeeNumber}\nemployeeType: ${scim.userType}\ngivenName: ${scim.givenName}\nhomePhone: ${scim.phone}\nhomePostalAddress: ${scim.addresses.region}\ninitials:\nlabeledURI:\nmail: ${scim.email}\no: ${scim.organization}\npager:\nroomNumber:\nsecretary:\nuid: ${scim.userName}"],
  "update": ["dn: cn=${this.uid},ou=${this.ou},dc=iamsath,dc=com\nobjectClass: top\n#person\nobjectClass: person\nsn: ${scim.name}\ncn: ${scim.Fname} ${scim.Lname}\ntelephoneNumber: ${scim.phone}\nseeAlsodescription:\n#org person\nobjectClass: organizationalPerson\ntitle: ${scim.title}\nx121Address:\nregisteredAddress:\ndestinationIndicator:\npreferredDeliveryMethod:\ntelexNumber:\nteletexTerminalIdentifier:\ninternationaliSDNNumber:\nfacsimileTelephoneNumber:\nstreet: ${scim.addresses.streetAddress}\npostOfficeBox:\npostalCode: ${scim.addresses.postalCode}\npostalAddress: ${scim.addresses.region}\nphysicalDeliveryOfficeName:\nou: People\nst: ${scim.addresses.region}\nl: ${scim.addresses.locality}\n# inet org person\nobjectClass: inetorgperson\naudio:\nbusinessCategory:\ncarLicense:\ndepartmentNumber: ${scim.department}\ndisplayName: ${scim.displayName}\nemployeeNumber: ${scim.employeeNumber}\nemployeeType: ${scim.userType}\ngivenName: ${scim.givenName}\nhomePhone: ${scim.phone}\nhomePostalAddress: ${scim.addresses.region}\ninitials:\nlabeledURI:\nmail: ${scim.email}\no: ${scim.organization}\npager:\nroomNumber:\nsecretary:\nuid: ${scim.userName}"],
    "delete": [],
  "select": [],
  "mappingToExistingToResponse": [
    {
      "id": "cn=${ldif.cn}, ou=${ldif.ou}, dc=iamsath, dc=com",
      "externalId": "${ldif.dn}",
      "userName": "${ldif.uid}",
      "givenName": "${ldif.givenName}",
      "displayName": "${ldif.displayName}",
      "name": "${ldif.displayName}",
      "emails": "${ldif.mail}",
      "userType": "${ldif.employeeType}",
      "title": "${ldif.title}",
      "department": "${ldif.departmentNumber}",
      "organization": "${ldif.o}",
      "phone": "${ldif.telephoneNumber}",
      "employeeNumber": "${ldif.employeeNumber}",
      "manager": "${ldif.manager}",
      "addresses": {
        "region": "${ldif.postalAddress}",
        "locality": "${ldif.l}",
        "postalCode": "${ldif.postalCode}",
        "streetAddress": "${ldif.street}"
      }
    }
 
  ]
},
  "configs": {
    "OBJECT_CLASS_PRESENT": "(objectClass=person)"
  }
}

Entitlement Schema​

{
"schemas"``: ``"urn:sath:params:scim:schemas:core:1.0:Account"``,
"meta"``:{
"resourceType"``: ``"User"``,
"created"``:``"2011-08-01T18:29:49.793Z"``,
"lastModified"``:``"2011-08-01T18:29:49.793Z"``,
"location"``:``"https://example.com/v2/Users/2819c223..."``,
"version"``:``"W\/\"f250dd84f0671c3\""
},
"Fname"``:``"Aman"``,
"Lname"``: ``"Singh"``,
"userName"``:``"asingh"``,
"displayName"``:``"Amar Singh"``,
"phone"``: ``"+1 5555551111"``,
"email"``: ``"amansingh@sath.com"``,
"title"``:``"System Engineer"``,
"addresses"``:{
"region"``:``"Kolkata"``,
"locality"``:``"west-bengal"``,
"postalCode"``:``"700064"``,
"countryCode"``:``"IN"``,
"country"``:``"India"``,
"streetAddress"``:``"Street 31"
},
"department"``:``"Research"``,
"userType"``:``"EMP"``,
"organization"``:``"Exelon"``,
"employeeNumber"``:``"132356456"``,
"manager"``:``"Alexa"
}

Deploying the LDAP Apache Directory Connector​

Deploying using IDHub Connector Onboarding Wizard​

tip

The documentation for deploying the connector using the IDHub Connector Onboarding Wizard is coming soon

Deploy on your own​

Deploy on Cloud​

tip

The documentation for deploying the connector on your own Cloud Platform is coming soon

Deploy on your Server​

Prerequisites​
  • IDHub web hostname.
  • An IDHub Tenant.
  • The SASL principal is ldap/example.net@EXAMPLE.COM
  • The Search Base DN should point to the place under which we store users and services (dc=security,dc=example,dc=com)
  • Your domain name (here, example.net_) has to be reachable on your machine.
    • Either you define in on a DNS server, or you can also add it in your /etc/hosts file.
  • An Ubuntu/Debian Linux VM with Docker engine, Compose plugin, cURL, jq and unzip.
  • A service URL with valid certificate which points to port 7001 on the above VM.
Step 1 — Creating Connector OAuth Client (ID)​

From IDHub Dashboard, go to Admin Settings > Sign-On > Keycloak Administration and do the following steps.

  • Go to Clients menu.
  • Create client and set Client ID to ‘ldap-connector’ and Save.
  • Set Valid Redirect URIs to '*' and Save.
Step 2 — Create service account user and password in Keycloak in tenant realm​

In your Keycloak realm, do the following.

  • Go to Users menu.
  • Add user.
  • Set Username to ‘ldap-service-account’ and Save.
  • Go to its Credentials menu and set a password. (Note: For this tutorial, we have used ‘sapassword1’. We highly recommend using a different one for your service account).

Step 3 — Generate Access token and Refresh token​
curl --location --request POST 'https://IDHUB_HOSTNAME/auth/realms/TENANT_NAME/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=OAUTH_CLIENT_ID' \
--data-urlencode 'username=SERVICE_ACCOUNT_USER' \
--data-urlencode 'password=SERVICE_ACCOUNT_PASSWORD' \
--data-urlencode 'scope=offline_access' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'request_token_type=urn:ietf:params:oauth:token-type:access_token' \
| jq

Replace the following:

  • IDHUB_HOSTNAME: The IDHub web hostname. A prerequisite. eg. test.sath.com
  • TENANT_NAME: Tenant that you created in test.sath.com. A prerequisite. eg. alpha
  • OAUTH_CLIENT_ID: OAuth Client ID you created in Step 1.
  • SERVICE_ACCOUNT_USER: Service account username you created in Step 2.
  • SERVICE_ACCOUNT_PASSWORD: Service account password you created in Step 2.
info

We now have our tokens. Let’s deploy the connector.

Step 4 — Prepare the .env file​
  • Clone the IDHub’s AD Connector repository and edit the .env file.
wget https://storage.googleapis.com/sath-public-binaries/connectors/idhub-ldap-apache-connector.zip
unzip idhub-ldap-apache-connector.zip
cd ldap-apache-connector
nano .env
IDHUB_HOSTNAME=IDHUB_HOSTNAME
KEYCLOAK_ACCESS_TOKEN=ACCESS_TOKEN
KEYCLOAK_REFRESH_TOKEN=REFRESH_TOKEN
KEYCLOAK_CLIENT_ID=OAUTH_CLIENT_ID
KEYCLOAK_REALM=TENANT_NAME
LDAP_BASE_DN=APACHE_DOMAIN_BASE_DN
LDAP_SEARCH_BASE=APACHE_DOMAIN_BASE_DN
LDAP_USERNAME=APACHE_ADMIN_USERNAME
LDAP_PASSWORD=APACHE_ADMIN_PASSWORD
LDAP_HOST_IP=APACHE_SERVER_IP_ADDRESS
LDAP_HOST_PORT=APACHE_SERVER_PORT
PORT=CONNECTOR_PORT
info

Replace the following:

  • IDHUB_HOSTNAME: IDHub web hostname. From prerequisites. eg. test.sath.com
  • ACCESS_TOKEN: From Step 3 output. Put it WITHOUT the quotes.
  • REFRESH_TOKEN: From Step 3 output. Put it WITHOUT the quotes.
  • OAUTH_CLIENT_ID: From Step 1. eg. ldap-connector
  • TENANT_NAME: Tenant created in IDHub. From prerequisites. eg. alpha
  • APACHE_DOMAIN_BASE_DN: From prerequisites. eg. DC=idhub,DC=com
  • APACHE_ADMIN_USERNAME: From prerequisites. eg. Administrator@idhub.com
  • APACHE_ADMIN_PASSWORD: From prerequisites. eg. P@ssword1
  • APACHE_SERVER_IP_ADDRESS: From prerequisites. eg. 10.128.6.87
  • APACHE_SERVER_PORT: From prerequisites. eg. 389 or 636
  • CONNECTOR_PORT: AD connector port which you are planning to run on. The Service URL points to this port.
Step 5 — Set schema configuration​
  • Edit Account.json file.
nano Account.json
...
},
"relationshipAttribute": "memberOf",
"namingAttribute": "cn",
"defaultBaseContainerDN": "DISTINGUISHED_NAME"
}
}

Replace the following: DISTINGUISHED_NAME: DN of target OU where you want to sync the users from. eg. OU=Users,OU=IDHub,DC=sath,DC=com

  • Edit Entitlement.json file.
nano Entitlement.json
...
},
"relationshipAttribute": "member",
"namingAttribute": "cn",
"defaultBaseContainerDN": "DISTINGUISHED_NAME_ZERO",
"searchDNs": [
{
"dn": "DISTINGUISHED_NAME_ONE",
"searchScope": "sub"
},
{
"dn": "DISTINGUISHED_NAME_TWO",
"searchScope": "sub"
}
]
}
}
note
  1. Use defaultBaseContainerDN if you have only one OU to pull AD groups from. Works only if searchDNs are not provided.
  2. searchDNs key can be used in scenarios where you need to pull AD groups from different OUs. Takes precedence over defaultBaseContainerDN. Remove array if not required
Step 6 — Run the container​
  • In the connector directory, run the following command.
docker compose up -d
  • Confirm if the (JVM) service is running by running the following command.
docker logs -f ldap-idhub-connector