IDHUB LDAP Connector setup guide
Overview:
In this document, we will walk through the steps for setting up the connection with your LDAP based Application to IDHub into your dedicated environment using IDHUB LDAP connector, This file will be deployed in the server where the onboarding application of type connected is running. The IDHUB connector application serves as a bridge between the onboarding application like Active Directory and IDHUB for information flow
Before starting the establishment of connection, few things need to be checked/ done (for completion) as below:
Extract IDHUB LDAP zip File, from the downloaded IDHUB website from here
List of Fields present in your application
Service Account credentials for logging into the application
Directory structure with right folders
Detailed steps for each one of the above steps are provided below
Setup Step 1: Know your Field lists
The first step of setting up LDAP Connector Application into IDHub is knowing what fields you will need to make seamless connection establishment
Why is it required?
This is required so that:
Whenever there is a access request by any of the users in IDHub, an account gets created automatically for the requester upon successful approval
The created account will contain all the mapped fields correctly and users will have a seamless experience to go and use the application
Setup Step 2: Your Service Account Credentials
The second step of setting up LDAP Connector Application into IDHub is getting valid credentials to login to your application as an administrator
Why is it required?
This is required so IDHUB application can make changes into your database and application for automatic, fast and best user experience
What are the different types of Authentication mechanism?
User authentication is a method that keeps unauthorized users from accessing sensitive information. For example, User A only has access to relevant information and cannot see the sensitive information of User B
IDHUB Authentication
The list below reviews some common authentication methods used to secure modern systems
Token-based authentication
Password-based authentication
Multi-factor authentication
Certificate-based authentication
Biometric authentication
In this particular implementation, we choose to have Token-based Oauth2
OAuth doesn't share password data but instead uses authorization tokens to prove an identity between consumers and service providers. OAuth is an authentication protocol that allows you to approve one application interacting with another on your behalf without giving away your password
This way no one from the frontend requires to give secure protocol passwords to anyone and can be carried out by token-based authentication
How will IDHub use your credentials?
IDHUB doesn't share password data but instead uses authorization tokens to prove an identity between consumers and service providers, for this purpose we require client credentials to connect idhub connector. IDHUB connectors needs service account credentials to make necessary changes in the required fields of the onboarded application directly.
Setup Step 3: Make your directory structure
The directory structure is supposed to be on the server where the onboarding application is running
How to make the structure?
To achieve the above configuration directory structure follow the below command list in terminal if these directory doesn’t exist:
cd / - takes you to the home directory of the server
mkdir command- used to create directory . We are taking example ldap-connector
as a parent directory
CODE
|
How does an ideal Directory structure look like?
After you have ran all the commands below is the type of directory you will be looking into:
/ldap-connector/
/ldap-connector/configurations
/ldap-connector/configurations/schemas
Setup Step 4: Extract LDAP zip Files
How to get the zip File?
It will come from Install package - If you want to understand how to download - Go here
After you download the installation package and extract it, the zip file will be found inside idhub package named as LDAP-connector.zipEnd Goal - We have all the zip File to update and complete connection establishment with the application
Setup Step 5: Changing Configuration Files
There are 4 files that needs changes based on the information procured above.
/ldap-connector/application.yml
/ldap-connector/configurations/Account.json
/ldap-connector/configurations/Entitlement.json
/ldap-connector/configurations/<resource>.json(This file needs to be changed as per different resource)
Detailed steps for each one of the above steps are provided below
Configure application.yml
This YAML file has Core Compatibility version, IDHUB services, Logging, App and security configurations
Where is the file?
The directory structure for Application.yml file in the LDAP-connector folder would be
/ldap-connector/application.yml
Where to get data for changes?
The Url will basically remain the same, except the DNS name will change every time
access token needs to be generated, details are explained in the later section of the Documentation "Generate access token"
What changes to make?
Field Name | Field Description | Field Type | Sample Values |
---|---|---|---|
app.name | Name of Onboarded Applicatioon | Active Directory | |
app.description | Onboarded Application description | Identity/Authentication Server | |
jwk-set-uri | certs URL for the DNS replace <> which the server DNS where the connector is deployed, rest remains the same | URL | https://<http://abc.com >/auth/realms/IDHub/protocol/openid-connect/certs |
idhub.hostname | The hostname /IP of IDHUB application | demo.iamsath.com | |
idhub.realm | Tenant / Keyclock realm name | ||
idhub.clientId | The client ID of client under idhub.realm of Keyclock | test-connector | |
idhub.secret | Credential of ClientId | xxxxxxxx | |
idhub.accessToken | access-token: This will be generated through any post API response generator by passing header and body | Alphanumeric | b29cxxxx-4exx-xx37-aa16-e5xx-2xxxxxxx |
idhub.refreshToken | This will be generated through any post API response generator by passing header and body | Alphanumeric | |
idhub.timeoutSeconds | Optional timeout in seconds after which a rest call to IDHUB will be timed out | Numeric | 30 |
idhub.test | Boolean | true/false | |
ldap.directory.baseDN | LDAP base directory base directory DN /base DN | dc=iamsath,dc=com | |
ldap.directory.userName | LDAP service account with required permission(read/write) | cn=Directory Manager | |
ldap.directory.password | LDAP service account password as Base 64 encoded string | Alphanumeric | |
ldap.directory.host | LDAP based directory server hostname or IP | xx.xx.xx.xx | |
ldap.directory.port | LDAP based directory application port | Numeric | Non secure: 389 Secure port: 636 |
ldap.splice.configurations.accountSchemaFile: | Relative path of Account resource schema file | String | ./configurations/schemas/Account.json |
ldap.splice.configurations.entitlementSchemaFile: | Relative path of Entitlement resource schema file | String | ./configurations/schemas/Entitlement.json |
server.port | Port on which the idhub connector application will run | Numeric | 8005 |
How does the end output look like?
This files end output will look as below
CODE
|
Where to place the updated file?
This file will be placed under the same folder location
/ldap-connector/application.yml
Resource Configuration
All resource-specific configuration is kept under under this file
There is one file for each type of resource
For example for a resource Account, there will be a file Account.json
And here we are configuring the Account.json file below
Where is the file?
The directory structure for Account.json file in the LDAP-connector folder would be
/ldap-connector/configurations/schemas/Account.json
Where to get data for changes?
The changes are all application and database structure related which needs to be defined in order to insert, delete and modify data into the application database
What changes to make?
Each resource file will have a JSON object with the following attributes:
id:
id of the resource should be in a specific format
"urn:sath:params:scim:schemas:core:<compatible core version number>:<Resource Name>"
e.g. urn:sath:params:scim:schemas:core:1.0:Account
name:
This is referring to Resource name as string i.e Account
description:
Description of the resource as a string
attributes:
An array of JSON Object for different Resource specific attributes of IDHUB system.
Each resource attribute object can have 12 sub attributes :
Attribute name(Required attribute’s font is bold) | Description | Field Type | Default Value |
---|---|---|---|
name | Name of resource attribute | Text | |
description | Description of resource attribute | Text | |
multiValued | Boolean | ||
type | Text | string | |
mutability | Text | readWrite | |
returned | Text | default | |
uniqueness | Text | none | |
caseExact | Boolean | false | |
required | Boolean | false | |
canonicalValues | Text | {} | |
subAttributes | Sub attribute of resource, it’s mandatory if attribute type is complex | Text in Json format |
meta:
This is a JSON object which has 2 attributes. This doesn't need to change until asked by the Service provider on IDHUB new version release
resourceType
location
schemas:
List of schema of the specific resource. No need to update the value. Use the default one.
[ “urn:ietf:params:scim:schemas:core:2.0:Schema” ]
schemaConfiguration
This is a JSON object which holds LDAP configuration like id, objectClass, otherDefaultAttributes, relationshipAttribute, namingAttribute, defaultBaseContainerDNfor search resource. This config may vary for the different resource types.
id: Which attribute of the targetsystem resource will be considered as unique valued aatribute
objectClass : List of objectClass as Strings
otherDefaultAttributes: holds all attributes and their values in JSON format which are defaults
relationshipAttribute: holds attribute for membership of the resource
namingAttribute: Attribute is used to create the DN of thr required resource
defaultBaseContainerDN: The default base container where the resource will get created.
e.g.
CODE
|
How does the end output look like?
Check the sample as the final output for Account Resource schema and will be saved as Account.json file
CODE
|
Where to place the updated file?
This file will be placed under the same folder location
/ldap-connector/configurations/schemas/Account.json
Sample Files For Open LDAP resources:
Sample schema files for Active Directory resources:
Setup Step 6: Start the connector application
Following are the steps which needs to be followed in order to achieve connector application running as a part of the system service, and will also run automatically on each system reboot
Step1:
This step involves keeping the connector application into a desired folder
for example : we are keeping the connector configurations under Connector folder under apps
/apps/ldap-connector
Step2:
We need to have an idhubLDAPconnector.service file under like below
/etc/systemd/system/idhubLDAPconnector.service
Step3:
Setup idhubLDAPconnector.service file
To setup this below are the exact content which needs to be there
CODE
|
There are basically 2 things which needs to be configured here:
WorkingDirectory= <needs to be the directory location where the LDAP connector file is present >
ExecStart= <.jar file can be changed accordingly as per the file inside LDAP connector folder>
Step4:
Execute the below commands in sequence:
Reload the service files to include the new service.
sudo systemctl daemon-reload
Start your service
sudo systemctl start your-service.service
To check the status of your service
sudo systemctl status example.service