SSO: LDAP Authentication Follow

This article walks you through the configuration of LDAP based SSO authentication.
This way, your service will perform interaction with your LDAP server prior to the service's execution, allowing you to use values returned from LDAP in the input of your service.

LDAP Server

Create configuration file

You need to provide your ServiceManager the configuration of your LDAP server, and the steps for receiving data from it.

First, create a LDAP configuration file based on the template file attached to this article.
Note that ldap.config has an abstract configuration for explanatory purposes only. If you wish to run a valid example please use working_ldap.config.
For your convenience, the file contents are also pasted here:

{
    url: "ldap://ldap.forumsys.com:389",
    adminUser: "cn=read-only-admin,dc=example,dc=com",
    adminPassword: "password",
    usernameHeader: "UsernameHeader",
    requests: [
        {
            searchBase: "cn=read-only-admin,dc=example,dc=com",
            searchPhrase: "uid=${username},dc=example,dc=com",
            returnedAttribute: "mail",
            outputName: "mail"
        },
        {
            searchBase: "cn=read-only-admin,dc=example,dc=com",
            searchPhrase: "mail=${mail},dc=example,dc=com",
            returnedAttribute: "sn"
        }
    ]
}

Update each of the configuration fields to your proper values, according to the following functionality:

• url: the url of your LDAP server.
• adminUser: the user name of the admin account on the server.
• adminPassword: the password of the admin account on the server.
• usernameHeader: the name of the header, in which the the SSO user is passed.
• requests: an array that represents a list of steps to be executed to receive all required information from the LDAP server.

The following are to be defined per each step in the LDAP interaction:

• searchBase: locator in which the search will be performed.
• searchPhrase: search query. May include references to output values of previous requests/steps or to the special '${username}' parameter. See further details bellow.
• returnedAttribute: name of the field to be returned from the result of the current step. This value will be available both for the procecding requests (steps) of the LDAP interaction, and for the web service that is going to be configured to use LDAP authentication.
• (optional) outputName: custom name for the returned value - the value will be extracted from returnedAttribute but in your ServiceManager you should refer to it via outputName.
  If not declared, then you should use returnedAttribute in the ServiceManager as well. 
• (optional) responseTransformation: action to be performed on the returned response, before passing it to the service. For now only "toUpperCase" is supported.

Search phrase tokens

For help with the searchPharse syntax, refer to the MSDN article:

https://learn.microsoft.com/en-gb/windows/win32/adsi/search-filter-syntax?redirectedfrom=MSDN

In the value of the "searchPhrase" field, you may use the following tokens to reference special values:

• ${username} - the special token representing the user received from the request's header. Available from any request.
• ${mail} - the returnedAttribute from the first LDAP step. Available from the second request or later.
• ${mail} or ${sn} - which are the returnedAttribute values from the first and seconds steps. Available from the third request or later (if there was in this example).
• Etc.

NOTICE: if 'outputName' is declared - then the value will be available via ${outputName} instead of via ${returnedAttribute}

Upload configuration file

Once the configuration file is ready, save it and upload the file to the local folder of your ServiceManager.
You may do that directly on the file system on your ServiceManager server, or use "Admin > Server Files" to upload it to the "/" folder.

 Set system properties

On the "Admin > System Properties" screen, locate the line (add the line if it's missing):
LDAP_CONFIG = ldap.config

 Make sure it is not commented out (not having # sign at the beginning of the line), and set it to the name of the LDAP configuration file you uploaded - "ldap.config" in this example.

Service Configuration

 Set LDAP authentication

Configure your web service to use the LDAP configuration you created by opening the "Service Editor", and setting "Advanced Details > Authentication Type" to "LDAP".

Referencing parameters returned from LDAP

In the "Input Parameters" of a web service using LDAP, you may set the input parameter values to have ${var} tokens that will be evaluated during execution to the values returned from LDAP.

Assuming the above LDAP configuration, you may use the following tokens:

• ${username} - the special token representing the user received from the request's header.
• ${mail} or ${sn} - which are the returnedAttribute values from each of the LDAP steps.