LDAP Authentication

Lightweight Directory Access Protocol (LDAP) is an application protocol for querying directory information. The LDAP Authentication method provides single-sign-on capability using your organization’s LDAP environment. It can be used in intranet and internet deployments of EMS Everyday applications such as EMS Web App.

For example, when a user logs into EMS Web App with their User ID and Password, their credentials are authenticated against LDAP and compared against corresponding user information recorded in the Network ID and/or External Reference fields of your EMS Everyday User records. If a match exists, the Everyday User gets logged in to the application and inherits Everyday User Process Template rights to which their LDAP Group has been assigned.

The EMS Web App LDAP-Process Template assignment process requires that your implementation of LDAP stores group information as a Directory Service object containing a property that contains the users that belong to your various groups.

The Field Used to Authenticate Everyday User parameter (within System Administration > Settings > Parameters Everyday User Applications tab) is used by the applications to determine which value should be used for authentication.

To authenticate your users via LDAP follow the steps in this section. After successful connection to the platform API, the user will log in following the scenario below:

  • Enter credentials on the Sign In screen and tap Sign In.
  • EMS Platform Services verifies credentials against the configured LDAP provider.
  • EMS Platform Services responds.
  • User taken to the Home screen.

If the credentials are missing when the user taps Sign In, an error message displays stating that fields are required. If the platform API is can't verify the credentials, the user is informed based on that response.

ClosedConfigure Your LDAP Provider

  1. Navigate to Platform Services admin portal (for example: https://Yourcompany.com/EmsPlatform/admin) and select Integrations from the sidebar.
  2. Select EMS Mobile and from Everyday User Authentication Method, choose LDAP.
  3. Under your name in the upper right, navigate to the EMS Web App > Admin Functions page.
  4. Tap the LDAP Configuration tab and complete all required LDAP information, and then test your configuration.

This is the same process you use to authenticate EMS Web App with LDAP. The EMS Platform Services API uses the same configuration information.

ClosedConfigure EMS Web App to Use LDAP Authentication

  1. Log into EMS Web App with a User that belongs to an Everyday User Security Template containing the Web Administrator role.

    This is controlled in the EMS Desktop Client under Configuration > Everyday User Applications > Everyday User Security Templates.

  2. From the User Options, select Admin Functions.
  3. Click the LDAP Configuration tab.
  4. The LDAP Configuration window opens.

ClosedConfigure EMS Web App Security

  1. Navigate to the Security tab.
  2. To enable LDAP authentication, select Authenticate users via LDAP.
  3. If LDAP will be used to assign Everyday User Process Templates to your Web Users, select Use LDAP to assign Process Templates.
  4. Use advanced communication options: Skip this step for Active Directory environments. Enabling this checkbox requires that you complete the settings on the Communication Options tab.
  5. In Path for LDAP Query, specify a valid LDAP path (for example – LDAP://YourCompany.com)
  6. List of Domains: Skip this step if your organization uses a single domain. Otherwise, add a comma separated list of your domains.
  7. In LDAP Domain\User, enter a Domain User account that has rights to query LDAP (for example – YourDomain\User)
  8. In Password, enter a valid Password for the User Account entered in the previous step.
  9. Specify the LDAP Authentication Type for your environment.

ClosedConfigure Communication Options

If you’re not familiar with LDAP settings, we recommend that you get assistance from a System Admin in your organization who is.

The Communication Options tab includes fields that define how to fetch a Group or a User when sending communications from the EMS Desktop Client. You can also set the SSL configurations, including the Security Certificate Path. To force communication to use SSL, select the Use SSL box.

  • Certificate Path – If there is a specific certification that you want to use to validate your authentication.
  • Authentication Type – Type of authentication that your LDAP server will use during the binding process. Basic is the default.
  • Search Root – Level at which your search begins.
  • User Search Filter – Specifies the filter to use when performing the user search.
    • Example – (&(objectClass=Person)(SAMAccountName={0})) or (&(objectClass=Person)(uid={0}))
  • Group Search Filter – Specifies the filter to use when performing the group search.
    • Example – (&(objectClass=Person)(objectClass=user))
  • Protocol Version – Insert the current version number. The default is 3, as the current version should be 3.

ClosedCore Properties

If you’re not familiar with LDAP settings, we recommend that you get assistance from a System Admin in your organization who is.

Indicate whether your LDAP implementation is Active Directory. These properties are set to the common defaults, but can be changed if the LDAP properties differ from the defaults.

  • LDAP Name Property – The property for user name on the user record in LDAP that displays. Displayname is the default.
  • LDAP Phone Property – The property for the phone number on the user record in LDAP that displays. Telephonenumber is the default.
  • Domain to append to users – Field is unnecessary unless the domain of your user is different from the domain returned from the query.
  • Field for LDAP Group Lookup – Identifies the EMS property to use when performing the search. For example, if you use LDAP solely to assign templates and you want the EMS Web App to look up group membership using a field other than the login name, then you must enter that field's name here.

ClosedNon-AD Configuration

If you’re not familiar with LDAP settings, we recommend that you get assistance from a System Admin in your organization who is.

If your LDAP implementation is not Active Directory, use these fields to redefine the LDAP property names used when searching directory information.

  • LDAP Account/User ID Property – Property in your LDAP store that contains the user name.
    • Example – If sameaccountname=xxxx, then enter sameaccountname
  • Full LDAP User ID Format – Leave blank unless authentication requires a full path.
    • Example – cn={0},ou=staff,o=yourdomain
  • LDAP Group Category – Property in your LDAP store that contains the group category.
    • Example – If filter should be objectClass=groupOfNames, then property should be groupOfNames
  • LDAP Group Name – Property in your LDAP store that contains the group name.
  • LDAP Group Member Name – Property in your LDAP store that contains the name of a single member in the group.
    • Example – If member property is member=jdoe, then property should be member
  • LDAP Group Member User Name Attribute – Property of the user record that corresponds to the group's member property to determine group membership.

ClosedLDAP Queries

If you’re not familiar with LDAP settings, we recommend that you get assistance from a System Admin in your organization who is.

These are LDAP query overrides to fetch Groups and Users from the domain. These settings rarely need to overridden, but can be used to customize queries.

  • LDAP query for security groups – Search for security groups in your LDAP store.
  • LDAP query to find users – Search for users in your LDAP store.
  • LDAP query for find users with space – Search for users that have spaces surrounding their user names in your LDAP store.

ClosedSave Your Configuration

  1. Click Save.

    Everyday Users can inherit Everyday User Process Templates based on the LDAP Group(s) with which they belong. Otherwise, you have completed the configuration process.

  2. Within EMS Desktop Client, go to the Everyday User Process Templates area (Configuration > Web > Everyday User Process Templates).
  3. Within an Everyday User Process Template, locate the LDAP Groups tab and select an LDAP Group(s) to map to that Everyday User Process Template.
  4. Click OK.

ClosedTest Your Configuration

  1. After completing configuration, navigate to the Test Configuration tab in the EMS Web App under LDAP Configuration.
  2. Enter your Network UserId Without Domain Name and password.
  3. Click Test. One of the following messages displays:
    • Successful – you will receive a message in a green box at the top that includes domain information and the words "Authentication successful".
    • Unsuccessful – you will receive a prompt stating that LDAP could not be accessed. Check your logs to determine the reason for the failure.

ClosedTest Your LDAP Configuration

Assuming you installed the EMS Platform Services at https://Yourcompany.com/EmsPlatform, then you can test the configuration with a curl command:

curl -X GET -H 'x-ems-consumer: MobileApp' https://ems.yourcompany.com/endpoint/api/v1/health

You can also use the API's Swagger interface to accomplish this goal.

You should see a portion of the JSON response that looks like this (unrelated details omitted for brevity):

{
    ...
    "additionalProperties": {
        "authConfig": {
            "activities":"ldap"  // <-- these are the critical lines
            "ui":"ldap"
        }
    }
}

ClosedTest Your LDAP Authentication

Assuming you installed the EMS Platform Services API at https://ems.yourcompany.com/endpoint, you can test the authentication with a curl command:

curl -X POST -H 'x-ems-consumer: MobileApp' -H 'Content-Type: application/json' -d '{"username":
"your_username", "password":"your_password"}' https://ems.yourcompany.com/endpoint...authentication

...where your_username and your_password are your credentials.

Send your request to the endpoint, api/v1/authentication, within the API.