Structuring LDAP Connector files and directory on an AD Server
Overview:
In this document, we will walk-through the steps for setting up connection with your Database Application to IDHub into your dedicated environment using IDHUB LDAP connector, This file will be deployed in the server where the onboarding application is running. The IDHUB connector application serves as a bridge between the onboarding application and IDHUB for information flow
Before starting the establishing of connection, few things needs to be checked/ done (for completion) as below:
- Extract IDHUB LDAP zip File, from downloaded IDHUB website from here
- List of Fields present in your application
- Administrator 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
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 you checked the fields
Setup Step 2: Your Administrator 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 command prompt as admin:
cd C:\ - takes you to the root directory of the boot disk
mkdir command- used to create directory
cd c:\
mkdir apps
mkdir apps\IdhubLDAPconnector
mkdir apps\IdhubLDAPconnector\configurations
mkdir apps\IdhubLDAPconnector\configurations\scim
mkdir apps\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:
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.zip - End 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.
- ServiceProviderConfig.json (This file will be only be changed by the service provider)
- application.yml
- splice.yml
- Account.json (This file needs to be changed as per different resource)
Detailed steps for each one of the above steps are provided below
ServiceProviderConfig.json
Service Provider configuration json file is the place to define the scope of what IDHUB connector can support and some metadata related to the connector
Where is the file?
The directory structure for ServiceProviderConfig.json file in the LDAP-connector folder would be
c:\apps\idhubLDAPconnector\configurations\scim\ServiceProviderConfig.json
What changes to make?
Only the service provide i.e from the IDHUB development team will be changing this file configurations
How does the end output look like?
This files end output will look as below
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"documentationUri": "https://www.sath.com/idhub/documentation",
"patch": {
"supported": false
},
"bulk": {
"supported": false,
"maxOperations": 0,
"maxPayloadSize": 0
},
"filter": {
"supported": false,
"maxResults": 0
},
"changePassword": {
"supported": false
},
"sort": {
"supported": false
},
"etag": {
"supported": false
},
"authenticationSchemes": [
{
"name": "OAuth Bearer Token",
"description": "Authentication scheme using the OAuth Bearer Token Standard",
"specUri": "http://www.rfc-editor.org/info/rfc6750",
"documentationUri": "no documentation",
"type": "oauthbearertoken",
"primary": true
},
{
"name": "HTTP Basic",
"description": "Authentication scheme using the HTTP Basic Standard",
"specUri": "http://www.rfc-editor.org/info/rfc2617",
"documentationUri": "no documentation",
"type": "httpbasic"
}
],
"meta": {
"location": "scim/v2/ServiceProviderConfig",
"resourceType": "ServiceProviderConfig",
"created": "2019-09-03T00:00:00Z",
"lastModified": "2019-09-03T00:00:00Z",
"version": "W\/\"3694e05e9dff594\""
}
}
Where to place the updated file?
This file will be placed under the same folder location
C:\idhubLDAPconnector\configurations\scim\ServiceProviderConfig.json
Application.yml
This YAML file has Core Compatibility version, IDHUB services and security configurations
Where is the file?
The directory structure for Application.yml file in the LDAP-connector folder would be
C:\apps\idhubLDAPconnector\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?
Field Name | Field Description | Field Type | Sample Values |
---|---|---|---|
access-token-uri | Authorization engine url for keycloak/etc where the connector is deployed,replace <> which the server DNS where the connector is deployed, rest remains the same | URL | https://abc.com/auth/realms/protocol/openid-connect/token |
idhub-core url: | Application base URL Only the domain name needs to be changed under <> where the connector is deployed, rest remains the same | URL | https://<abc.com>/api/core |
jwk-set-uri: | certs URL for the DNS replace <> which the server DNS where the connector is deployed, rest remains the same | URL | https://<abc.com>/auth/realms/IDHub/protocol/openid-connect/certs |
server port: | Port where the application is running | Numeric | 8805 |
security | access-token: This will be generated through any post API response generator by passing header and body | Alphanumeric | b29cxxxx-4exx-xx37-aa16-e5xx-2xxxxxxx b2e5cxx-4exx-xx37-aa16-e5c52xxxxxxx b29cxxxx-4exx-xxxx--aa16-e5c52xxxxxxx |
How does the end output look like?
This files end output will look as below
info:
app:
name: Connector API Application
description: IDHUB Connector Application
version: 1.0.0
compatible-core-version: 1.0
management:
endpoints:
web:
exposure:
include: info,health,httptrace
idhub-core:
url: https://<abc>.com/api/core
target-system:
name: Active Directory
server:
port: 8805
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://<abc.com>/auth/realms/IDHub/protocol/openid-connect/certs"
client:
client-id: Connector
access-token-uri : https://<abc.com>/auth/realms/IDHub/protocol/openid-connect/token
tenant-name: example-92202
access-token: <eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJWb0ExRjZIU3F2VXN3eExottyyX1AwMlVCalJOcHZoeDBXSWF0NmIzeHd1VnFNIn0.eyJleHAiOjE2MTg1NzgzMTMsImlhdCI6MTYxNTk4NjMxMywianRpIjoiNWQ2NDEwOWYtYzU0Zi00MTliLWEyOTItNzQ5ZDVlNWMxNzI5IiwiaXNzIjoiaHR0cHM6Ly9kZXY3LmlhbXNhdGguY29tL2F1dGgvcmVhbG1zL2FwcGxlLTkyMjAyIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjM5MGVhZDBkLTVhZTktNGMyYS1hYWFlLWE5ZDBjYzAzOTEzMSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImxkYXAtY29ubmVjdG9yIiwic2Vzc2lvbl9zdGF0ZSI6IjgyOGRiMjdlLTY1ZTQtNDhjMS05NzQ0LTA0MDJlZDUyYmQ0ZiIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBvZmZsaW5lX2FjY2VzcyBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoibGRhcC1jb25uZWN0b3IifQ.ddOrTcO_WFN4B5GL4QTebDL9TRzocpGTp-4fYEOzzUegd72WMaaLud7uhkGykRMvyEJADcMtw3Ut7EQWcIrXJGTLc9Zdyuwe-L6-PzyG6ZRYjxaL0KizqvMEs4g7Ah8g0npGOkPBSrlsh0xcQT5f2OYN0zPf0Kahbe6ffUdOknelo_sQGf1Nc-9Uuvp-QM_5ERd2lFFxVs6LNShEzYxgzIGxO6ZkG27jJT1f_l8d8R_JUndHzAE1qCmt9N_bFqLAj3p6jXmfjkOskhKIMCQcFG4VbeocRqUmt9Xrc8OUotlDXvhrIczpABVvLKHaMf912DABT8FoPHqoMAIU3yzB49tg>
Where to place the updated file?
This file will be placed under the same folder location
c:\apps\idhubLDAPconnector\application.yml
Splice.yml
This YAML file has an LDAP based Application connection details
Where is the file?
The directory structure for Splice.yml file in the LDAP-connector folder would be
c:\apps\idhubLDAPconnector\configurations\splice.yml
Where to get data for changes?
The data will be from application specific which needs to be onboarded
The hostname/IP of the application
username and password to login to the application
What changes to make?
Field Name | Field Description | Field Type | Sample Values |
---|---|---|---|
environment | type of environment, it can be test, production, development etc | Alphabetical | test |
searchbase | base for all users (full DN pathname) | Alphabetical | dc=demo,dc=io |
hostname/IP | Host name or ip address for the application | Alphabetical/Numeric | gmail.com/10.2.0.0 |
port | ldap or ldaps port | Numeric | 636 |
username | Username for the application to login (full DN pathname) | Alphabetical | uid=idhub,ou=Admin-Users,ou=App-service-accounts,dc=demo,dc=io |
**password | Username for the application to login | Alphanumeric | rt3cxxxx-5exx-xx89-aa16-t6hju7xxxxxx |
*Password: How to create ?
Step1: Go to the website https://www.devglan.com/online-tools/jasypt-online-encryption-decryption
This is to ensure that the password generated will be encrypted and cannot be used by anyone to misuse hence we defined a separate out of the application password generation tool
Step2: Enter your password in plain text to encrypt text box
Step3: Type of encryption as "Two way encryption"
Step4: In place of secret key use "8598298e-395e-47d9-a0eb-b04242119c24" and encrypt your password
Step5: Copy the encrypted string value to the password section in the splice.yml file
How does the end output look like?
This files end output will look as below
spring:
profile: splice
name: ldap-splice
environment: <test>
version: splice-version
target-system:
name: ldap
host: <hostname/IP>
port: 389
username: CN=svc_IdHubConnector,CN=Managed Service Accounts,DC=uss,DC=ussenterprise,DC=co
password: <rt3cxxxx-5exx-xx89-aa16-t6hju7xxxxxx>
searchbase: dc=iamsath,dc=com
newuserbase:
Where to place the updated file?
This file will be placed under the same folder location
c:\apps\idhubLDAPconnector\configurations\splice.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 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
c:\apps\idhubLDAPconnector\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 object will have 3 attributes :
name
This is the name of IDHUB form attribute as a string
type
This is the datatype of the IDHUB attribute as a string. This is optional. The default value is a string.
required
This defines whether the attribute is required or not. The value is a boolean. This is optional. The default value is true.
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
schema:
Same as the id attribute mentioned above
matching-attributes:
This is a list of attribute names which will be used by splice to determine unique resource in the target system.
i.e.
"matching-attributes": [
"uid",
"mail"
]
attribute-map:
This is a mapping of the IDHUB Resource attribute with the TargetSystem Resource corresponding attribute.
"attribute-map": {
"<TargetSystem Attribute Name>": {
"type": "string",
"attribute": "<IDHUB Attribute Name>"
},
......
}
scripts:
This is a JSON object which holds LDAP scripts for CRUD operation and the TargetSystem response mapping.
This has the following attributes
insert
List of Insert script as a string. The attributes in the query should be the LDAP attribute.
e.g-
"dn: cn=${this.uid},ou=${this.ou},dc=iamsath,dc=com\nobjectClass: top\n#person\nobjectClass: person\nsn: ${scim.givenName}\ncn: ${scim.uid}\ntelephoneNumber: ${scim.phone}\nseeAlsodescription:\n#org person\nobjectClass: organizationalPerson\nx121Address:\nregisteredAddress:\ndestinationIndicator:\npreferredDeliveryMethod:\ntelexNumber:\nteletexTerminalIdentifier:\ninternationaliSDNNumber:\nfacsimileTelephoneNumber:\nphysicalDeliveryOfficeName:\nou: People\n# inet org person\nobjectClass: inetorgperson\naudio:\nbusinessCategory:\ncarLicense:\ndisplayName: ${scim.displayName}\ngivenName: ${scim.givenName}\nhomePhone: ${scim.phone}\ninitials:\nlabeledURI:\nmail: ${scim.email}\no: ${scim.organization}\npager:\nroomNumber:\nsecretary:\nuid: ${scim.uid}"
update
List of update script as a string. The attributes in the query should be the LDAP attribute.
delete
List of delete script as a string. Keep empty array []
select
List of select/search script as a string. Keep empty array []
mappingToExistingToResponse
This is list of JSON object.
Check sample doc for format and reference for setup
"mappingToExistingToResponse": [
{
"id": "cn=${ldif.cn}, ou=${ldif.ou}, dc=iamsath, dc=com",
"externalId": "${ldif.dn}",
"UserLogin": "${ldif.uid}",
"givenName": "${ldif.givenName}",
"DisplayName": "${ldif.displayName}",
"email": "${ldif.mail}",
"PhoneNumber": "${ldif.telephoneNumber}",
"manager": "${ldif.manager}",
"lastReconTimestamp": "${ldif.modifyTimestamp}",
"entitlements": "${ldif.memberOf}"
}
]
configs
This is a JSON object which holds LDAP config for search resource. This config may vary for the different resource types.
e.g.
"configs": {
"OBJECT_CLASS_PRESENT": "(objectClass=person)"
}
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:core:1.0:Account",
"name": "Account",
"description": "User Account",
"schemas": "urn:sath:params:scim:schemas:core:1.0:Account",
"attributes": [
{
"name": "DisplayName",
"type": "string",
"required": true
},
{
"name": "UserLogin",
"type": "string",
"required": true
},
{
"name": "PhoneNumber",
"type": "string",
"required": true
},
{
"name": "email",
"type": "string",
"required": true
},
{
"name": "entitlements",
"type": "array",
"required": true
}
],
"meta": {
"resourceType": "Schema",
"location": "/v2/Schemas/urn:sath:params:scim:schemas:core:1.0:Account"
},
"matching-attributes": [
"uid",
"mail"
],
"attribute-map": {
"givenName": {
"attribute": "DisplayName",
"type": ""
},
"sn": {
"type": "",
"query": ".displayName"
},
"displayName": {
"attribute": "DisplayName"
},
"uid": {
"attribute": "UserLogin"
},
"email": {
"attribute": "email",
"type": "",
"query": "{mail: .emails[].value}"
},
"phone": {
"attribute": "PhoneNumber",
"type": ""
},
"memberOf": {
"attribute": "entitlements",
"type": "array"
},
"modifyTimestamp": {
"attribute": "lastReconTimestamp",
"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.givenName}\ncn: ${scim.uid}\ntelephoneNumber: ${scim.phone}\nseeAlsodescription:\n#org person\nobjectClass: organizationalPerson\nx121Address:\nregisteredAddress:\ndestinationIndicator:\npreferredDeliveryMethod:\ntelexNumber:\nteletexTerminalIdentifier:\ninternationaliSDNNumber:\nfacsimileTelephoneNumber:\nphysicalDeliveryOfficeName:\nou: People\n# inet org person\nobjectClass: inetorgperson\naudio:\nbusinessCategory:\ncarLicense:\ndisplayName: ${scim.displayName}\ngivenName: ${scim.givenName}\nhomePhone: ${scim.phone}\ninitials:\nlabeledURI:\nmail: ${scim.email}\no: ${scim.organization}\npager:\nroomNumber:\nsecretary:\nuid: ${scim.uid}"
],
"update": [
"dn: cn=${this.uid},ou=${this.ou},dc=iamsath,dc=com\nobjectClass: top\n#person\nobjectClass: person\nsn: ${scim.givenName}\ncn: ${scim.uid}\ntelephoneNumber: ${scim.phone}\nseeAlsodescription:\n#org person\nobjectClass: organizationalPerson\nx121Address:\nregisteredAddress:\ndestinationIndicator:\npreferredDeliveryMethod:\ntelexNumber:\nteletexTerminalIdentifier:\ninternationaliSDNNumber:\nfacsimileTelephoneNumber:\nphysicalDeliveryOfficeName:\nou: People\n# inet org person\nobjectClass: inetorgperson\naudio:\nbusinessCategory:\ncarLicense:\ndisplayName: ${scim.displayName}\ngivenName: ${scim.givenName}\nhomePhone: ${scim.phone}\ninitials:\nlabeledURI:\nmail: ${scim.email}\no: ${scim.organization}\npager:\nroomNumber:\nsecretary:\nuid: ${scim.uid}"
],
"delete": [],
"select": [],
"mappingToExistingToResponse": [
{
"id": "cn=${ldif.cn}, ou=${ldif.ou}, dc=iamsath, dc=com",
"externalId": "${ldif.dn}",
"UserLogin": "${ldif.uid}",
"givenName": "${ldif.givenName}",
"DisplayName": "${ldif.displayName}",
"email": "${ldif.mail}",
"PhoneNumber": "${ldif.telephoneNumber}",
"manager": "${ldif.manager}",
"lastReconTimestamp": "${ldif.modifyTimestamp}",
"entitlements": "${ldif.memberOf}"
}
]
},
"configs": {
"OBJECT_CLASS_PRESENT": "(objectClass=person)"
}
}
For more information regarding the LDIF script you can check into the below URL
Refer below URL for LDIF script
https://docs.oracle.com/cd/A84870_01/doc/network.816/a77230/syntax.htm
Where to place the updated file?
This file will be placed under the same folder location
c:\apps\idhubLDAPconnector\configurations\schemas\Account.json
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
c:\apps\idhubLDAPconnector
Step2:
Install java
https://www.java.com/en/download/help/windows_manual_download.html
Step3:
Download Winsw
Step4:
Copy winsw.exe to the app dir
Make winsw.xml file
<!--
This is an example of a minimal Windows Service Wrapper configuration, which includes only mandatory options.
This configuration file should be placed near the WinSW executable, the name should be the same.
E.g. for myapp.exe the configuration file name should be myapp.xml
You can find more information about the configuration options here: https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md
Full example: https://github.com/kohsuke/winsw/blob/master/examples/sample-allOptions.xml
-->
<service>
<!-- ID of the service. It should be unique across the Windows system-->
<id>ID Hub Connector</id>
<!-- Display name of the service -->
<name>ID Hub Connector</name>
<!-- Service description -->
<description>ID Hub Connector</description>
<!-- Path to the executable, which should be started -->
<executable>java</executable>
<arguments>-jar idhub-connector-application-1.0.2.jar</arguments>
</service>
Step5
Install as service
Run the below commands in command prompt as admin:
cd C:\Apps\IdhubLDAPconnector
winsw install
winsw start
Step6
Setup windows firewall for port 8805
open windows firewall with advanced security as admin
Under Unbound Rules
Click on New Rule
In new Inbound Rule Wizard pick port
Click next
enter TCP and port 8805.
Click next
Pick Allow the cobnnection
Click Next
Pick all
Click next
Give it an name and click Finish