LDAP Authentication

The most common external user authentication provider for Simscope is LDAP (Lightweight Directory Access Protocol).

LDAP Configuration

To enable LDAP authentication, add an [ldap] and [ldapmapping] section in your simscope.config file.

# LDAP config: put in simscope.config file.
# NOTE: you can use ldapsearch from the CLI for debugging:
# > ldapsearch -h LDAP_HOSTNAME -x -LLL -b BASEDN uid=UID

[ldap]
url = "ldap://ldap.company.com:389"
# For secure LDAPS
#url = "ldaps://ldap.company.com:636"

basedn = "dc=example,dc=com"
userfilter = "uid=%(uid)"

# Optional: if your LDAP uses email addresses for usernames, enable this setting.
# allowemaillogin = true

# If using Microsoft Active Directory without a uid field, you may need to use
#userfilter = "(&(objectCategory=user)(sAMAccountName=%(uid)))"
# NOTE: docs for objectCategory:
# > https://gist.github.com/jonlabelle/0f8ec20c2474084325a89bc5362008a7
# Alternative: objectCategory=Person
#userfilter = "(&(objectCategory=Person)(sAMAccountName=%(uid)))"
#
# If objectCategory is not supported in your Active Directory, you may omit that (but may have performance issues on LDAP queries)
#userfilter = "(sAMAccountName=%(uid))"

# LDAP session mode is a more secure LDAP authentication scheme, which does not store hashed authentication credentials
enablesessions = true
# optional: LDAP Session expiration interval (can be set shorter for higher security)
#sessionexpire = "7d" # 7 days

# Mapping between Simscope Field and LDAP Fields.
# → Change the right-hand-side to your LDAP field names.
[ldapmapping]
username = "uid"
fullname = "cn"
email = "mail"

Config: LDAP Field Mapping

Simscope needs to read data back from LDAP, via a mapping in the config file.

The format is:

# Left side: Simscope field name
# Right side: company LDAP field name

# line format: SIMSCOPE_FIELD = "LDAP_FIELD"

username = "uid"
fullname = "cn"
email    = "mail"

Simscope Fields:

The above example maps from the LDAP fields named uid, cn, and mail into Simscope.

Authenticated Directory Mode

If your LDAP network requires authentication (ie does not allow anonymous user search queries), you can enable directory mode in Simscope.

This will perform a 2-step operation for LDAP authentication:

1. First, authenticate as the "Directory DN" user
2. Search the directory for the desired UID, to get the "User DN"

To enable, add the following to your [ldap] section:

# Example for directory-based authentication
[ldap]
directorydn = "uid=einstein,dc=example,dc=com"
directorypw = "DIRECTORY_PASSWORD"

LDAP User/Group Filters

Simscope can be configured to allow all users, or matching users to log in via LDAP.

• LDAP Documentation for AND/OR/NOT expression operators (&, |, !)

Examples

• Example 1: Any user

# LDAP: any user
userfilter = "uid=%(uid)"

• Example 2: Scientists only

If your LDAP server supports groups and the memberOf attribute, you can limit Simscope access based on an LDAP search filter.

Here is an example Simscope configuration, requiring users to be a member of the LDAP group called scientists:

# LDAP: scientists only
userfilter = "(&(memberOf=scientists)(uid=%(uid)))"

# Example LDAP filter with multiple hierarchies:
# userfilter = "(&(memberof=cn=officegroup,dc=example,dc=local)(uid=%(uid)))"

• Example 3: User attributes

You can also filter based on user attributes. For example, this query requires users to have an attribute called supplementaryGid with a value of local-admins:

userfilter = "(&(supplementaryGid=local-admins)(uid=%(uid)))"

• Example 4: Multiple groups (AND/OR operators)

If your LDAP server supports the & (AND) and | (OR) operators, you can filter in multiple groups:

userfilter = "(&(|(ou=local-admins)(ou=verification))(uid=%(uid)))"

Microsoft Active Directory Configuration

To use LDAP through Microsoft Active Directory, you may need to use a configuration similar to the following:

[ldap]
url = "ldap://ldap.company.com:389"
# For secure LDAPS:
#url = "ldaps://ldap.company.com:636"
# For LDAPS GC SSL:
#url = "ldaps://ldap.company.com:3269"

basedn = "DC=group,DC=company,DC=com"

# Active directory filter
userfilter = "(sAMAccountName=%(uid))"

# Note: Active Directory usually requires a password for Simscope to inspect the directory.
# You should use a common/directory account username, provided by your IT group.
# (For testing purposes, you can try with a local username, but this is NOT recommended
#  for production.)
directorydn = "DIRECTORY_USERID"
directorypw = "DIRECTORY_PASSWORD"

# Mapping between Simscope Field and Active Directory LDAP Fields.
# → Change the right-hand-side to your Active Directory LDAP field names.
[ldapmapping]
username = "sAMAccountName"
fullname = "displayName"
email = "mail"

# Alternative: the fullname might be this field:
# fullname = "name"

LDAP Debug

Debugging LDAP is tricky, but here are a few tips.

ldapsearch

You should try getting the Linux ldapsearch command to work first, to validate your LDAP configuration.

• How To Search LDAP using ldapsearch (with examples)

Here is an example template:

# NOTE: Replace LDAP_HOSTNAME, LDAP_PORT, BASEDN, UID

> ldapsearch -h LDAP_HOSTNAME -p LDAP_PORT -x -LLL -b BASEDN uid=UID

Here is an example session:

> ldapsearch -h ldap.company.com -p389 -x -LLL -b dc=example,dc=com uid=einstein
dn: uid=einstein,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
objectClass: posixAccount
cn: Albert Einstein
sn: einstein
uid: einstein
mail: einstein@ldap.company.com
uidNumber: 88888
gidNumber: 99999

Note in the above case the following LDAP fields map to Simscope:

ldapsearch with authenticated directory

If your LDAP requires a username/password to do a directory search, you need to run with the options -D and -W.

• -D is the bind DN (account to authenticate with)
• -W indicates to prompt for a password

For example:

> ldapsearch -H ldap://ldap.forumsys.com:389 -D uid=einstein,dc=example,dc=com -W -x -LLL -b dc=example,dc=com uid=einstein
Enter LDAP Password: xxxxx

ldapwhoami (Who Am I)

You can also try ldapwhoami if you know the user's Distinguished Name (aka DN):

> ldapwhoami -H ldap://ldap.COMPANY.com:389 -D "DISTINGUISHED_NAME" -v -W

Example successful session:

> ldapwhoami -H ldap://ldap.company.com:389 -D "uid=einstein,dc=example,dc=com" -v -W

ldap_initialize( ldap://ldap.company.com:389/??base )
Enter LDAP Password: xxxxxx

dn:uid=einstein,dc=example,dc=com
Result: Success (0)

VerOps LDAP Tester

Note: Please contact VerOps to download the LDAP Tester.

This app lets you test Simscope LDAP configuration from the command-line, without needing to start/stop Simscope.

• This is the best method to test LDAP.

To download/install:

> wget ...
> tar zxf verops-ldap*.gz

Now test your LDAP config file:

> ./ldaptest ldap.config

[INFO ] VerOps LDAP tester version=1.9

UserID: einstein
Password: xxxxxx

If login is successful, you should see a result similar to this:

[INFO ] Authenticated LDAP user={
    "dn": "uid=einstein,dc=example,dc=com",
    "username": "einstein",
    "fullname": "Albert Einstein",
    "email": "einstein@ldap.forumsys.com",
    "disabled": false
} token=TOKEN expire=DATE
[INFO ] ✅ LDAP [ok] sessions=1

Running Simscope with --debug mode

Run the Simscope server with the --debug flag, and it will enable extra LDAP log messages on the Simscope terminal.

Here is an example session:

> ./simscope.sh --debug
0.000 [DEBUG] Enabled --debug logging
......
1.328 [INFO ] ────────────────────────────────────────────────────────────
1.329 [INFO ] Simscope version=1.412 build=2023-02-06 pid=5578
1.329 [INFO ] Serving HTTP url=http://localhost:8080
1.329 [INFO ] ────────────────────────────────────────────────────────────

Example LDAP messages:

422.704 [DEBUG] Failed auth login=gauss
422.704 [DEBUG] ldap.SearchDirectoryForUID uid=gauss
430.993 [INFO ] AuthLDAP login=gauss url=ldap://12.34.56.78:389 @error=LDAP search failed: LDAP::Search() error : -1 (Can't contact LDAP server)

500.295 [WARN ] LDAP user invalid mapping uid=galieleo user={username:"galieleo", fullname:"Galileo Galilei", email:"", dn:"uid=galieleo,dc=example,dc=com"}
502.295 [INFO ] AuthLDAP login=galieleo url=ldap://12.34.56.78:389 @error=User mapping decoded incorrectly from LDAP (likely configuration problem)

More Help

If LDAP still fails, please contact VerOps for help.