Structuring LDAP Connector files and directory

Overview:

In this document, we will walk-through the first part of setting up connection with your Database Application to IDHub, into your dedicated environment using IDHub LDAP connector. This file, once structured and placed, will be deployed in the server where the on-boarding application is running. The IDHub connector application serves as a bridge between the on-boarding application and IDHub, for information flow.

Before establishing a connection, a few items need to be completed:

• Prerequisite: Extract IDHub LDAP zip files
• Step 1: Understanding List of Fields present in your application
• Step 2: Getting your service account credentials for logging into the application 
• Step 3: Making your directory structure with right folders
• Step 4: Changing configuration files
• Step 5: Start the connector

Please note that this connector can be used for connecting to your Apache Directory Studio, phpLDAP Platform, OpenDJ, OpenLDAP, Active Directory etc. 

Detailed steps for each one of the above steps are provided below.

Prerequisite: Extract LDAP Connector Zip Files

How to get the zip File?

• Download LDAP Connector ZIP
• After you download the installation package and extract it, the zip file will be found inside IDHub package named as LDAP-connector.zip
• End Goal - We have all the zip File to update and complete connection establishment with the application

Setup Step 1: Understanding List of Fields present in your application

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 an access request by any IDHub user, 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

How to know your field

Typically the fields are the general information used to register someone/something with unique information to itself :

• Some standard way of checking fields may be considered as what information do we capture in order to register a new user to any application, few examples of fields are as below
  FirstName - Specifies the name of the form
  Address - Specifies the address of the user
  _id - Specifies the identifier of the form, etc
• Here is an example on how your checked fields would be like in your application: 
  

  

Setup Step 2: Getting 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

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 authorisation tokens to prove an identity between consumers and service providers, for this purpose we require a administrator credentials to make necessary changes in the required fields

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 above configuration directory structure follow the below command list in terminal:
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.

cd /
mkdir /idhubLDAPconnector
mkdir /idhubLDAPconnector/configurations
mkdir /idhubLDAPconnector/configurations/scim
mkdir /idhubLDAPconnector/configurations/schemas

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:

/idhubLDAPconnector/

              /idhubLDAPconnector/configurations

                          /idhubLDAPconnector/configurations/schemas

Setup Step 4: 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

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/aplication.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?

How does the end output look like?

#App info
app:
  name: AD
  description: Active Directory
#Password Policy
password:
  numbers: 2
  specialChars: 1
  alphabets:
    lowercase: 4
    uppercase: 1
#Security
spring:
  output:
    ansi:
      enabled: "ALWAYS"
    security:
      oauth2:
        resourceserver:
          jwt:
            jwk-set-uri: "http(s)://<idhub hostname>/auth/realms/IDHub/protocol/openid-connect/certs"
idhub:
  hostname: "<idhub hostname>"
  realm: "<tenant name>"
  clientId: "<Client ID>"
  secret: "<Clinet secret>"
  accessToken: "<Access token to communicate with IDHUB>"
  refreshToken: "<Refresh token to refresh the access token when it expired >"
  test: true

#LDAP Directory properties
ldap:
  directory:
    baseDN: dc=iamsath,dc=com
    userName: cn=Directory Manager
    password: S@th1250
    searchBase: dc=iamsath,dc=com
    host: 10.2.10.80
    port: 389
  splice:
    configurations:
      accountSchemaFile: "./configurations/schemas/Account.json"
      entitlementSchemaFile: "./configurations/schemas/Entitlement.json"

#Logging Properties
logging:
  level:
    root: "ERROR"
    com.sath.idhub: "INFO"
    com.sath.idhub.connector: "DEBUG"
  pattern:
    console: "%clr(%date{yyyy-MM-dd}){blue}%clr(T){faint}%clr(%date{HH:mm:ss.SSS}){green}%clr(%date{XXX}){magenta}\
      \ %clr(%-5p) %clr(%-5(${PID})){faint} %clr(%-30.-30([%thread)]){cyan} %clr(%logger{50}.%M\\\
      (%F:%L\\)){magenta} %clr(:){red}%n%clr(%m){faint}%n%n"
    file: "%date{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}) %-5p %-5(${PID}) %-30.-30([%thread)]\
      \ %logger{50}.%M\\(%F:%L\\) :%n%m%n%n"
server:
  port: 8005

Where to place the updated file?

This file will be placed under the same folder location

 /ldap-connector/application.yml

Resource Configuration (Account.json)

All resource-specific configuration is kept under under this file

There is one file for each type of resource

For example for resource Account, there will be a file Account.json

And here we are configuring 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 :

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 objectClass,namingAttribute, defaultBaseContainerDNfor search resource. This config may vary for the different resource types.

e.g.

"schemaConfiguration": {
    "id": "cn",
    "objectClass": [
      "top",
      "person",
      "organizationalPerson",
      "inetOrgPerson"
    ],
    "namingAttribute": "cn",
    "defaultBaseContainerDN": "ou=People,dc=iamsath,dc=com"
  }

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

{
  "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": true,
      "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"
    ],
    "namingAttribute": "cn",
    "defaultBaseContainerDN": "ou=People,dc=iamsath,dc=com"
  }
}

Where to place the updated file?

This file will be placed under the same folder location

/ldap-connector/configurations/schemas/Account.json

Setup Step 5: Start the connector application

Below are the steps to use on Linux Server, if you have Windows, follow additional steps for AD Server documentation to get the connector started.

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 a LDAP-Connector.service file under like below
/etc/systemd/system/LDAP-Connector.service

Step3:

Setup LDAP-Connector.service file
To setup this below are the exact content which needs to be there

[Unit]

Description=IDHUB LDAP LINK Service

[Service]

User=root

# The configuration file application.properties should be here:

#change this to your workspace

WorkingDirectory=/apps/LDAP-Connector

#path to executable.

#executable is a bash script which calls jar file

#ExecStart=/apps/LDAP-connector/linker

Type=simple

ExecStart=/usr/bin/java -jar idhub-connector-application-1.0.0.jar

SuccessExitStatus=143

TimeoutStopSec=10

Restart=on-failure

RestartSec=5

[Install]

WantedBy=multi-user.target

There are basically 2 things which needs to be configured here:

1. WorkingDirectory= <needs to be the directory location where the LDAP connector file is present >
2. ExecStart= <.jar file can be changed accordingly as per the file inside LDAP connector folder>

Step4:

Execute the below commands in sequence:

1. Reload the service files to include the new service.
   sudo systemctl daemon-reload
   
   
2. Start your service
   sudo systemctl start your-service.service
   
   
3. To check the status of your service
   sudo systemctl status example.service

Next steps:

To perform Keycloak configuration. Once the setup is done a token is to be generated. Upon generation of token, validation for the access token is done.
Final step is Restart the connector application and Onboard your application. Follow next document for keycloak configuration steps.