Active Directory and LDAP

This section describes how to configure SuperSTAR to authenticate users against an LDAP directory. LDAP (Lightweight Directory Access Protocol) is a very commonly used interface to user or account information. A very popular variant of LDAP is Microsoft Active Directory service.

When LDAP authentication is in use, SuperSTAR still performs authorisation via its own internal system. However, groups from the LDAP directory can be used to assign permissions in the SuperSTAR system.

Intended Audience

This document is for System Administrators setting up the SuperSTAR suite in an enterprise environment. It is expected that you are familiar with how to launch and login to the SuperADMIN Console command-line tool.

It is also expected that you are familiar with the basics of LDAP, including the use of Distinguished Names (DNs) to identify elements (e.g. users and groups) in the LDAP directory tree.

Authentication in SuperSTAR

In the SuperSTAR software suite, user access is managed by the SuperADMIN service. Other components (such as SuperSERVER and SuperWEB2) connect to SuperADMIN to authenticate users.

SuperADMIN uses the typical system of Users and Groups of users to manage authentication and authorisation. By default, SuperADMIN will use a locally maintained list of users and groups that you can manage using the SuperADMIN console.

However, organisations typically have an existing directory of users and user groups that they maintain. Rather than duplicating that user directory, you can configure SuperADMIN to use the existing external user directory directly.

Authentication Providers

SuperADMIN includes a set of authentication providers for connecting to authentication services or directories. The standard SuperADMIN installation includes the following providers:

Provider	Description
STRLocal	The default user and group store managed entirely via the SuperADMIN console. This user store is private to SuperADMIN.
ActiveDirectory	Authentication against a Microsoft Active Directory system, optionally with Single Sign On using Kerberos. Azure Active Directory is also supported via the Microsoft Azure Active Directory Domain Services Add On.
eDirectory	Authentication using the eDirectory LDAP server.
LDAP	A generic authentication provider for all other LDAP servers.
ExternalJAASModule	Provides a plugin mechanism for advanced users to integrate SuperSTAR with an external authentication system. For example, a module could be written to authenticate via an Intranet portal system. This is the most flexible authentication provider, but it requires custom code to be written. Contact support for further information on using this module.

The ActiveDirectory, eDirectory and LDAP providers are all different flavours of authentication using an external LDAP server. Most of the configuration settings are the same for each of these providers.

To view the list of providers available in your SuperADMIN installation, use the following console command:

CODE

auth providers

Authentication Services

A configured instance of an authentication provider is called an authentication service. To configure SuperADMIN to authenticate users against your LDAP server, you must create and configure a new authentication service.

If necessary, you can authenticate against multiple authentication providers by creating multiple authentication services.

The built-in authentication service (STRLocal) is used for initial configuration and as a fallback login method in case the external authentication service experiences problems. STRLocal cannot be removed or altered.

To view the details of the authentication services currently configured in your SuperADMIN installation, use the following console command (note that the built-in STRLocal service is not listed):

CODE

auth services

Create a New LDAP Authentication Service

To create a new LDAP authentication service, login to SuperADMIN as a user with administrative privileges (typically you should use the local SuperADMIN user to do the configuration), then complete the following steps:

Step 1 - Create the Service

Type the following command to create the service:

CODE

auth add <provider> <service_name>

Replace:

<provider> with either ActiveDirectory, eDirectory or LDAP (if you are not using Active Directory or eDirectory, use the generic LDAP provider for all other cases)
<service_name> with your chosen name for the service

For example:

CODE

auth add LDAP myService

Step 2 - Configure the Service

Use all the following commands (except those marked as optional) to configure the service parameters.

Each command starts with auth <service_name>, where <service_name> is the name you selected when you created the service.
You can type auth services at any time to review the settings you have already configured.

Command	Configures	Example
auth <service_name> url <url>	The fully qualified domain name of your LDAP/Active Directory/eDirectory server.	auth myService url "ldaps://ldaphost.company.com"
auth <service_name> port <port>	The port the LDAP server is running on. This property has been deprecated. It will be automatically set to either port `389` or `636` (the default LDAP ports) depending on whether you specify an `ldap` or `ldaps` url. If you need to specify a non standard port, you can do so in the URL parameter, in the form `<url>:<port>`. For example: `auth myService url "ldaps://ldap.foo.com:686"`
auth <service_name> basedn <base>	The default base location for LDAP searches.	auth myService basedn "dc=company,dc=com"
auth <service_name> user basedn <base> auth <service_name> group basedn <base>	The default search location when searching for users or groups (optional).	auth myService user basedn "cn=users,dc=company,dc=com" auth myService group basedn "cn=groups,dc=company,dc=com"
auth <service_name> user userClass <attribute>	The LDAP "object class" of the objects that represent users or accounts (the standard Active Directory value is person).	auth myService user userClass person
auth <service_name> user groupAttr <attribute>	The name of the attribute of the LDAP user/account objects that indicates which groups the user is a member of (the standard Active Directory value is `memberOf`).	auth myService user groupAttr memberOf
auth <service_name> user idAttr <attribute>	The name of the attribute of the LDAP user/account object that holds the unique ID of the user (the standard Active Directory value is `sAMAccountName`).	auth myService user idAttr sAMAccountName
auth <service_name> group groupclass <attribute>	The LDAP "object class" of the objects that represent groups of users or accounts (the standard Active Directory value is `group`).	auth myService group groupclass group
auth <service_name> group memberAttr <attribute>	The name of the attribute of the LDAP group objects that indicates which users are members of the group (the standard Active Directory value is `member`).	auth myService group memberAttr member
auth <service_name> group idAttr <attribute>	The name of the attribute of the LDAP user/account object that holds the unique ID of the group (the standard Active Directory value is `cn`).	auth myService group idAttr cn
auth <service_name> adminGroup <group>	The name of a group of users from the LDAP server who should have administrator rights in SuperADMIN. Specify the group using just its name (you do not need a full DN).	auth myService adminGroup "SuperSTAR Administrators"
auth <service_name> group filter <groups>	The names of specific LDAP groups SuperADMIN will use for authorisation purposes. This is optional: if you omit this command then SuperADMIN will use all the groups defined in LDAP.	auth myService group filter "Group1,Group2,Group3"
auth <service_name> contextLogin true	Use this command and the following two commands to specify the LDAP user that SuperADMIN will use to login to the LDAP server. You are recommended to create a dedicated user for use by SuperADMIN.	auth myService contextLogin true
auth <service_name> contextLogin userdn <user>	The LDAP user that SuperADMIN will use to connect to the LDAP server.	auth myService contextLogin userdn "cn=superadmin,cn=Users,dc=domain"
auth <service_name> contextLogin password <password>	The password for the LDAP user that SuperADMIN will use to connect to the LDAP server.	auth myService contextLogin password "autobuild"
auth <service_name> priority <priority>	The priority for this authentication service. Each configured service has a priority: the service with the highest priority is tried first. If the login to the service fails, the next service is tried, and so on. The built-in STRLocal service has a priority of 100, so you should set your LDAP service to have a priority greater than 100. If you are adding multiple authentication services you can use the priority to control the order in which they will be tried.	auth myService priority 200

Step 3 - Additional Steps for Secure LDAP Connections

If you are configuring a secure LDAP connection, there are some additional steps required to add the LDAP server's trusted certificate to the Java Virtual Machine (JVM):

Ensure that you have specified the correct port in the LDAP URL when configuring the service. 636 is the default port for secure LDAP connections.
Obtain your LDAP server's signing certificate (you may need to ask your IT administrator for assistance with this step).
In a command prompt, change to the Java bin directory (if you are using the JRE supplied with SuperADMIN and have installed to the default location, this will be C:\Program Files\STR\SuperADMIN\jre\bin).

Import the certificate using the following command:

CODE

keytool -keystore <cacert_name> -importcert -alias <alias_name> -file <signing_certificate_file_location>

For example:

CODE

keytool -keystore ldapkeystore -importcert -alias ldapkeystore -file C:\ldapcert.cer

Run the following command to confirm that the certificate has been successfully imported:
CODE
```
keytool -list -keystore <cacert_name>
```
For example:
CODE
```
keytool -list -keystore ldapkeystore
```

Modify SuperADMIN's java-options.txt file to add the following system properties (if you have installed to the default location, java-options.txt will be located in C:\ProgramData\STR\SuperADMIN\server):

CODE

-Djavax.net.ssl.trustStore=<cacert_path_and_filename>
-Djavax.net.ssl.trustStorePassword=<password_entered_when_importing_the_certificate>

For example:

CODE

-Djavax.net.ssl.trustStore=C:\ldap\ldapkeystore
-Djavax.net.sll.trustStorePassword=MyPassword

Restart the SuperSTAR service.

Troubleshooting

To use a secure LDAP connection:

The LDAP server's certificate must be trusted by the JVM. This should work without any additional configuration.
If the SSL certificate you are using has not been signed by a trusted certificate authority, then you will not be able to login and an error similar to the following will appear in the SuperADMIN console error.log file. Please contact us for assistance if you encounter this error:

CODE

javax.naming.CommunicationException: ... Root exception is javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]

Step 4 - Activate the Service

When you have finished configuring all the service parameters, use the following command to activate your new service (replace <service_name> with the name of your service). Once you have activated the service it will be used to perform authentication if necessary:

CODE

auth <service_name> active true

If you need to temporarily disable the authentication service for any reason, you can use the following command. This deactivates the service without deleting it:

CODE

auth <service_name> active false

Important Note

Up to this point, you have most likely been using an administrator account that is defined by the STRLocal authentication service (the internal SuperADMIN authentication service).

Once you activate an external authentication service, such as LDAP, you need to switch to using an administrator account from that external authentication service (i.e., a user that belongs to the administrator group you specified using the auth <service_name> adminGroup <group> command).

You will not be able to manage permissions for the users or groups defined by this external authentication service unless you are logged in using an administrator account for that service.

If you set up multiple external authentication services, and you want to manage a user's account, then you must make sure you log in with an administrator account that belongs to the same authentication service as the user you want to manage. For example, this is important if you need to unlock a user account when the user has authenticated through Active Directory/LDAP.

The exception to the above rule is the allusers group. This is a special built-in group that applies to all users of the system. As an administrator user logged in under any authentication module, you can set permissions at the allusers level, and these permissions will be inherited by both local authentication users as well as users connected via an external authentication service.

For example, you can grant read access to a folder at the allusers level and this will apply to all users of the system unless specifically overridden at the individual user or group level.

Learn More

Now that you have configured LDAP, you can use groups to configure user permissions.
As an alternative to typing out all the commands to configure LDAP/Active Directory, you can create a macro file and then run the macro in SuperADMIN. See an example.
Learn some other useful commands for configuring an authentication service.
To make it easier for SuperSERVER users to connect to the SuperSERVER, you can enable Single Sign On with Kerberos.