LDAP Configuration

Syndeia Cloud offers delegated authentication to industry-standard and commercial LDAP Providers

In LDAP authentication, the Syndeia Cloud application (generically referred to here as “Service Provider (SP)”) connects to your organization’s LDAP server (aka “Directory [Store|Server] (DS)”) for authentication. Only the LDAP username is stored on Syndeia Cloud, and authentication is handled by your LDAP server for Syndeia Cloud.

1 Preparation Tasks
2 Configure the Directory Store/Server (DS)
3 Configure your Organization
4 Configure silhouette.conf
5 Operation

Preparation Tasks

Deploy Syndeia Cloud according to Intercax Documentation.
Read as much of https://ldap.com/learn-about-ldap/ as you need to be fluent in LDAP terms and administration.
Assure that the browsers on the user workstations which are going to interact with Syndeia Web Dashboard and with the chosen DS can connect to both the SP and the DS and that there are no SSL certificate denials.
Assure that there are no traffic shapers on the corporate network that alter HTTP Request and HTTP Response Headers - especially those headers involved in LDAP protocols.
Assure that there are no network routers or proxies on the corporate network that alter HTTP URLs or HTTP Headers.
Obtain the Fully-qualified Network Domain (FQDN) scheme, host, and port of the Syndeia Cloud SP.
Obtain the FQDN scheme, host, and port of the chosen LDAP DS.
Test your assumptions about your organization’s LDAP DS with either curl or ldapsearch - Syndeia uses a third-party library for LDAP queries and if external, simple LDAP queries do not work, your configuration of Syndeia based on incorrect assumptions is not going to be successful.
1. Read https://devconnected.com/how-to-search-ldap-using-ldapsearch-examples/

Configure the Directory Store/Server (DS)

Browse to and authenticate into your organization’s choice of DS’s administration website (or LDAP Directory desktop utility such as Azure AD or Apache Directory Studio)
- In Syndeia Silhouette, this is the ldap.hostname and ldap.port setting
Enter the integrations management portion of this administration website
Find or Create a new LDAP service for the DS’s users
Browse the DS’s LDAP “tree” to discover all of the following
- The administrator credentials necessary to bind to the LDAP query URL to search the entire tree for groups and users
  - the DS might grant query rights to anonymous users but often a client user or script has to provide administrator credentials to query the DS (via LDAP) for the existence of other user identities
  - This is the “Bind Distinguished Name” (Bind DN) and its password
    - In Syndeia Silhouette, this is the ldap.adminUserDN and the ldap.adminPassword
- The topmost node in the LDAP tree where user identities are stored.
  - This is the “Base Distinguished Name” (Base DN)
    - In Syndeia Silhouette, this is the ldap.baseDN
- The topmost node in the LDAP tree where groups are defined
If you are setting up an LDAP service for the organization, you will need to configure the LDAP tree before attempting to integrate Syndeia with the LDAP service.

Configure your Organization

With LDAP, all management of user identities and of permissible passwords are all the responsibility and choice of the organization.

Assure the LDAP DS has a directory of user identities
Know which users or groups should be permitted access to the Syndeia Service Provider

Users in the organization will not be able to access Syndeia Cloud through LDAP until the organization grants them, through the administration in the LDAP DS, an LDAP user identifier that has a password and an email address.

Configure `silhouette.conf`

ssh log into the Syndeia Cloud server with a user that can perform “passwordless sudo” operations. Root access is not necessary if sudo access has been established.
cd to /opt/icx/syndeia-cloud-current/web-gateway-<SC_version>-impl/conf
copy all of the following into silhouette.conf, adding or replacing any existing ldap. settings.
Replace all EXAMPLE values – like MYCOMPANY.MYCOM:LDAPPORT– with the values for your organization.

  ldap.hostname="MYLDAPSERVICE.MYCOMPANY.MYCOM"
  ldap.baseDN="dc=MYCOMPANY,dc=MYCOM"

The above illustrates how little configuration is mandatory - if the organization has an OpenLDAP service.

  ldap.hostname="MYLDAPSERVICE.MYCOMPANY.MYCOM"
  ldap.baseDN="dc=MYCOMPANY,dc=MYCOM"
  ldap.userBindAttribute="sAMAccountName"
  ldap.mailAttribute="userPrincipalName"

The above illustrates how little configuration is mandatory - if the organization has a Microsoft AD service.

  # LDAP provider
  # The values for hostname, baseDN and adminUserDN are placeholder values.
  # Please provide actual values, and the value for adminPassword, before using an LDAP provider.
  #
  # the hostname where the LDAP service is served
  # Default if absent is no LDAP service
  #ldap.hostname="MYLDAPSERVICE.MYCOMPANY.MYCOM"

  # the port on the host for the LDAP service
  # Default if absent is 389 (for insecure LDAP)
  #ldap.port=636

  # Topmost DN where Syndeia looks for users to authenticate for Syndeia Cloud
  # Default if absent is no LDAP service
  #ldap.baseDN="dc=MYCOMPANY,dc=MYCOM"

  # DN of an LDAP Administrator
  # Default if absent is unauthenticated LDAP searches
  #ldap.adminUserDN="cn=admin,dc=MYCOMPANY,dc=MYCOM"

  # Password for the LDAP Administrator in plain text
  # Default if absent is unauthenticated LDAP searches
  #ldap.adminPassword

  # the LDAP Attribute that indicates a user identity
  # Default if absent is "uid" (MS AD uses sAMAccountName)
  #ldap.userBindAttribute="uid"

  # the LDAP Attribute that indicates each user's email emailAddress
  # Default if absent is "mail"
  #ldap.mailAttribute="mail"

  # should Transport Layer Security be used for the LDAP searches
  # Default if absent is false (must be true for LDAPS)
  #ldap.startTLS=true

  # the SSL Protocol to use for TLS
  # Default if absent is negotiation by client and server
  #ldap.sslProtocol="TLSv1.2"

  # the Cipher to use for TLS
  # Default if absent is negotiation by client and server
  #ldap.sslCipher="TLS_RSA_WITH_AES_256_CBC_SHA256"

  # the path to an SSL certificates trust trustStore
  # Default if absent is all certificates from the LDAP servers are trusted
  #ldap.truststorePath="/some/path/jssecacerts"

  # the password for the SSL certificates trust trustStore
  # Default if absent is the well-known JKS password
  #ldap.truststorePassword="WeReallyDidChangeIt"
  
  # type of the Trust Store
  # Default if absent is jks for a Java Key Store
  #ldap.trustStoreType

  # --------------------------------------------------
  # If you want to limit Syndeia access to the members of
  # LDAP groups, then supply at least one and any more appropriate values
  # for the group settings below
  # Syndeia will search through nested groups of any depth but all Group DNs must be within the DN of ldap.groupSettings.dn
  # --------------------------------------------------
  #
  # Topmost DN where Syndeia looks for <memberAttribute> to identify groups and/or users to authenticate for Syndeia Cloud
  # Default if absent would be the ldap.baseDN for where Users are searched
  # ldap.groupSettings.dn="ou=MYGROUPS,dc=MYCOMPANY,dc=MYCOM"
  #
  # LDAP ObjectClass that indicates an entry is a Groups
  # Default if absent would be "groupOfUniqueNames"
  # ldap.groupSettings.objectClass="groupOfUniqueNames"
  #
  # Obsolete OU attribute value to help Syndeia identify LDAP group nodes
  # ldap.groupSettings.ou="groups"
  #
  # Simple name of the group used to restrict access to Syndeia Cloud
  # Default if absent would be the ldap.baseDN for where Users are searched
  # ldap.groupSettings.name="SyndeiaUsers"
  #
  # Attribute used to indicate group instances
  # Default if absent would be "cn"
  #   for example, given a DN: "cn=SyndeiaUsers,ou=MYGROUPS,dc=MYCOMPANY,dc=MYCOM", then use "cn" next
  # ldap.groupSettings.bindAttribute="cn"
  #
  # Attribute used in group instances to indicate members of that group
  # Default if absent would be "uniqueMember"
  # ldap.groupSettings.memberAttribute="uniqueMember"

Curious about the purpose of each and every setting? Expand this:

Setting	Purpose	Mandatory?	Typical

Setting	Purpose	Mandatory?	Typical
`ldap.hostname`	names the server that is providing the LDAP service	YES	ldap.company.com
`ldap.port`	identifies the port on the LDAP server	YES	389 or 636
`ldap.adminUserDN`	the LDAP Distinguished Name for the LDAP Administrator	Usually	cn=MYADMIN,ou=MYADMINGROUP,dc=MYCOMPANY,dc=MYCOM
`ldap.adminPassword`	encrypted value of the LDAP Admin’s password	Usually	MYADMINPASS (like #$%^&*_NOSOUPFORYOU)
`ldap.baseDN`	base Distinguished Name for the start of user queries	YES	ou=MYUSERS,dc=MYCOMPANY,dc=MYCOM
`ldap.userBindAttribute`	organization’s choice of LDAP attribute that uniquely identifies each user even without a full DN	NO (defaults to “uid”)	uid or sAMAccountName
`ldap.mailAttribute`	organization’s choice of LDAP attribute that uniquely identifies each user’s Email address	NO (defaults to “mail”)	mail or userPrincipalName
`ldap.startTLS`	should Syndeia first attempt to establish an SSL session with the LDAP service before making queries?	NO (defaults to false)	false for LDAP, true for Secure-LDAP
`ldap.truststorePath`	file location on the Syndeia server for the Java Keystore which holds public certificates that sign the public SSL certificate used by the LDAP server	NO	/opt/icx/syndeia-cloud-current/some/secure/path/to/keystore.jks
`ldap.truststorePassword`	password for the JKS file at `ldap.truststorePath`	NO (defaults to “changeit”)	Often it is left as “changes” - but it should be changed when it a proper JKS keystore is being used
`ldap.trustStoreType`	the type of Keystore. JKS is typical. This depends on what the running JVM has been configured to support.	NO (defaults to “jks”)	“jks” - but only when a `ldap.truststorePath` is present.
`ldap.sslProtocol`	the algorithm to use for the TLS Protocol	NO (defaults to client/server negotiation)	TLSv1.2
`ldap.sslCipher`	the encryption algorithm to use for SSL (with JVM, not OpenSSL, name)	NO (defaults to client/server negotiation)	TLS_RSA_WITH_AES_256_CBC_SHA256
When configuring LDAP Group-limited Access, some of the following must be provided:
`ldap.groupSettings.dn`	Distinguished Name for where to start looking for LDAP Group instances	NO - YES if intending to limit access to a Group	ou=MYTEAMS,dc=MYCOMPANY,dc=MYCOM
`ldap.groupSettings.name`	a common name value that indicates the team of Syndeia Users	NO - YES if intending to limit access to a Group	MYSYNDEIAUSERGROUP
`ldap.groupSettings.bindAttribute`	the LDAP attribute in a group instance that identifies the common name	NO (defaults to “cn”)	cn

Operation

Restart the web-gateway service
1. sudo systemctl restart sc-web-gateway
Open a modern web browser (Chrome, Edge, Safari) and visit http:SYNDEIA.MYCOMPANY.MYCOM:MYSYNDEIAPORT/login or https:SYNDEIA.MYCOMPANY.MYCOM:MYSECURESYNDEIAPORT/login
In the Login Form dialog, enter the LDAP user credentials for an existing LDAP user that is within the ldap.baseDN tree or within the ldap.groupSettings.name LDAP Group (if group-limited LDAP access was configured)
Choose LDAP from the Account chooser

If an LDAP user in the proper LDAP scope cannot authenticate into Syndeia, re-confirm with an LDAP search utility that the configuration of Syndeia is correct. Verify this yourself. Usually, either the user is using the wrong user name or wrong password or the LDAP repository has a different tree structure than is assumed.

When a user authenticates via LDAP into Syndeia, Syndeia will create Just In Time an account with rudimentary user read-level permissions - if the account is not already present.

When a user requires more permissions, use the User Management feature in the Web Admin Portal to change this.