Configure custom LDAP AD authentication

The configuration is carried out on the censhare server, in the censhare Admin Client, and in censhare Web.

Prerequisites

• You need the LDAP URL and the SSL certificate from the LDAP server (only for secure protocol connections).

• To retrieve information from the LDAP server, you need a read-only user for the directory server.

• To set up the mapping, you need the initial user data from the directory. You can use the ldapsearch command (only UNIX-based OS) or export the data from the LDAP server.

Overview

LDAP can be configured to authenticate users when they log in to censhare Web or the censhare Client. You can add multiple LDAP services to a censhare instance.

Censhare user management comprises the following entities:

• Party: Represents an individual user. All actions in censhare must be carried out by a logged-in, active user. Actions that run in the background and automatic actions use so-called system users. Manual actions are carried out by the respective physical users.

• Group: Users that share similar tasks, profiles, or that are part of a team, can be grouped. User groups can be assigned as workflow targets instead of individual users. Users can be members of any number of groups or no group at all.

• Role: Defines the allowed actions (so-called freedom of actions) that a user can carry out in censhare. For an individual user, roles and domains are always paired. Users must have at least one default role/domain pair and can have any number of secondary role/domain pairs.

• Domain: Defines the work areas that a user can access in censhare. For an individual user, roles and domains are always paired. Users must have at least one default role/domain pair and can have any number of secondary role/domain pairs.

LDAP/AD integration

When you register censhare in an LDAP domain and configure LDAP as a default authentication method, the user management is done only in LDAP/AD. When a user logs in to censhare for the first time, the user attributes are copied to the censhare master data. When an existing user logs in to censhare, the account is re-validated and synchronized with LDAP data.

Other than user data are not managed in LDAP. For example, permission keys, permission sets, workflows, etc. are managed in censhare.

As a fallback, the censhare internal standard authentication can be enabled for some or all users. LDAP and internal authentication can be used in parallel. For some user groups, LDAP authentication is not possible or not recommended:

• System administrators: Need direct access at any time. Therefore, LDAP authentication is not recommended.

• System users: Perform automated tasks and run in the background. System users do not represent a physical user. LDAP authentication is not recommended.

• External users: Service providers and other collaborators that are not part of the organization network cannot be managed in LDAP.

Required user attributes and best practices

To successfully authenticate a user, censhare needs a minimal set of user data: Name, Login name, Display name, Default role, and Default domain. Any LDAP user attribute can be mapped to these censhare attributes. The mapping is very flexible and allows to set up LDAP authentication in any organizational structure.

As a best practice, the organizational unit to which a user belongs can be mapped to the default domain and/or role. If a user is a member of additional security groups, these groups can be used to assign secondary domains and/or roles.

If the organizational attributes that are available for a user are not sufficient, or if they cannot be mapped to a corresponding censhare user attribute, you can add censhare specific attributes to the LDAP directory. This can reduce interdependencies and complexity, but increases administrative efforts for the LDAP directory.

For more information, see   User attribute mapping for LDAP & Kerberos SSO.

Authentication sequence

When a user logs in to censhare Web or the censhare Client via SSL, the following procedure authenticates the user and starts a session:

Login schema via LDAP

LDAP standard ports

The standard ports to query the LDAP server in the local domain are 389/TCP and 636/TCP via SSL. If these ports are used, the query response can have a reference to another domain host and an additional query to that host is triggered. In this case, it can happen that the other host is not available for queries to censhare.

To avoid the issue mentioned above, the ports 3268/TCP and 3269/TCP via SSL can be used. They query the global catalog on a Windows Active Directory Server.

Configure the LDAP service

To enable and configure the LDAP service, do the following:

1. In the censhare Admin Client, go to the Configuration/Services/LDAP directory, and open the Configuration.

2. In the General setup area, select the Service enabled field.

3. In the LDAP setting area, configure the properties for each LDAP service. You can configure multiple LDAP services. Each service can be referenced via its ID.

4. The two sample services can be adjusted to your requirements. To remove a service, click the Trash icon at the top left corner.

5. To add a new service, click the Plus icon at the bottom left.

6. Enter an ID and an internal Setting name for the service.

7. Select the Use paging field, if the LDAP server returns a large number of results on several pages. The default number of pages retrieved in one LDAP call is 100. For more information, see the Pages results control note from Oracle.

8. To add a new property, click the Plus icon at the bottom left inside the panel.

9. The following properties are required:

   • The java.naming.provider.url property with the URL of the LDAP server and the respective port. For example ldap://myldap.example.com:3268.

   • The java.naming.security.principal property with the UID of the principal. For example, myReadUser@EXAMPLE.COM.

   • For further properties that are required for a specific use case, contact our professional services.

10. In the JVM properties area, leave all property settings as-is.

11. Click OK to save the configuration.

12. If censhare connects to the LDAP server via SSL (ldaps://), you must add the certificate to the censhare truststore.

13. Update the server configuration. If necessary, synchronize the remote servers.

Configure the internal server module

Important: If you are not familiar with the censhare domain framework and user configuration, contact censhare solution development for the proper configuration of the internal server module.

The internal server module maps the LDAP/AD attributes to the censhare user attributes. To set up the mapping, do the following:

1. In the censhare Admin Client, go to the Configuration/Modules/Server Internal Modules directory and open the Login by custom implementation configuration.

2. In the dialog, click Edit XML file.

3. Add the search queries and filter parameters. censhare performs a 2-stage query. The retrieved values can be restricted to query-specified attributes from the LDAP server using attributes-to-return elements. For example:

   XML

   <search dn="dc=win2003,dc=coware,dc=de"
           search-scope="subtree"
           time-limit="0"
           count-limit="0"
           deref-link="false"
           return-obj="false">
      <filter expr="(& (objectClass=person) (userPrincipalName={0}))">
         <arg value="user@DOMAIN"/>
      </filter>
      <attributes-to-return>
         <attr name="displayName"/>
      </attributes-to-return>
   </search>

   • Edit the element: This element queries the user login (the principal) and user attributes.

   • Edit the element: This element queries the group membership.

   Note: To reference a specific LDAP , add a  setting-id="[ID]"  attribute.

    

4. Edit the section with the user attribute mappings. The mapping defines all required and optional attributes to create or synchronize a censhare user. For more information, see  User attribute mapping for LDAP & Kerberos SSO .

   • The element maps the LDAP principal name to the corresponding censhare party.

   • The element maps the LDAP user attributes to the corresponding censhare user attributes and sets the defaults.

5. Click OK to save your changes and close the XML editor.

6. Click OK to save your configuration.

The result of the query is an XML snippet from the LDAP server. Here is an example.

<result>
   <binding name="CN=Peter Maier,CN=Users"
          dn="CN=Peter Maier,OU=Developer,DC=win2003,DC=coware,DC=de">
      <attr name="displayName" value="Peter Maier"/>
      <attr name="mail" value="pm@coware.de"/>
      <attr name="memberOf"
         value="CN=Admins,CN=Builtin,DC=win2003,DC=coware,DC=de"/>
   </binding>
</result>

Configure the censhare Client login

To define the LDAP service as the default login method to the censhare Client, do the following:

1. Open the host configuration of the client computer under the path ~/Users/[USER]/Library/Preferences/censhare/hosts.xml.

2. In the entry of the desired server, set the attribute authentication-method="custom".

3. Save the configuration.

Configure censhare Web login

The login method for censhare Web is configured in the System asset. You can select multiple login methods. Each login method can be used explicitly through a URL parameter. To force the login via LDAP, use [censhare-base-url]/?auth=custom.

To use the LDAP service to login to the censhare Web, do the following:

1. Log in to censhare Web with administrator credentials, and open the System asset.

2. Edit the System properties widget.

3. Go to the Authentication section, and in the Methods field, select Custom.

4. Click OK to close the dialog and SAVE, to save your changes.

5. Restart the censhare Server.

Result

When a user logs into censhare Web or the censhare Client, the user information is retrieved from the LDAP server. If the user does not exist in censhare, a new user is created with attributes returned from the LDAP server.