Call us: +1-415-738-4000

Setting Up LDAP-Based Authentication

Introduction

Instead of using the built-in user management system, you can set up authentication and authorization for the Terracotta Server Array (TSA) based on the Lightweight Directory Access Protocol (LDAP). This allows you to use your existing security infrastructure for controlling access to Terracotta clusters.

The two types of LDAP-based authentication supported are Microsoft Active Directory and standard LDAP. In addition, LDAPS (LDAP over SSL) is supported.

NOTE: Terracotta servers must be configured to use SSL before any Active Directory or standard LDAP can be used.

Configuration Overview

Active Directory and standard LDAP are configured in the <auth> section of each server's configuration block:

<servers secure="true"> 
  <server host="172.16.254.1" name="server1">
    ...
    <security>
      ...
      <auth>
        <realm>...</realm>
        <url>...</url>
        <user>...</user>
      </auth>
    </security>
...
</server>

Active Directory and standard LDAP are configured using the <realm> and <url> elements; the <user> element is used for connections between Terracotta servers and is not required for LDAP-related configuration.

For presentation, the URLs used in this document use line breaks. Do not use line breaks when creating URLs in your configuration.

Realms and Roles

The setup for LDAP-based authentication and authorization uses Shiro realms to map user groups to one of the following two roles:

  • admin – This is the typical administrator role that can perform system functions such as shutting down servers and reloading configuration.
  • terracotta – A typical operator's role, with no rights to perform system functions such as shutdowns or configuration reloads. Though they may overlap, note that the terracotta role is not completely a subset of the admin role.

URL Encoding

Certain characters used in the LDAP URL must be encoded, unless wrapped in a CDATA construct. Characters that may be required in an LDAP URL are described below:

  • & (ampersand) – Encode as %26.
  • { (left brace) – Encode as %7B.
  • } (right brace) – Encode as %7D.
  • Space – Encode as %20. Spaces must always be encoded, even if wrapped in CDATA.
  • = (equals sign) – Does not require encoding.

Active Directory Configuration

Specify the realm and URL in the <security> section of the Terracotta configuration as follows:

<auth>
  <realm>com.tc.net.core.security.ShiroActiveDirectoryRealm</realm>
  <url>ldap://admin_user@server_address:server_port/searchBase=search_domain%26
       groupBindings=groups_to_roles</url>
  <user></user>
</auth>

Note the value of the <realm> element, which must specify the correct class (or Shiro security realm) for Active Directory. The components of the URL are defined in the following table.

Component Description
ldap:// For the scheme, use either ldap:// or ldaps://.
admin_user The name of a user with sufficient rights in Active Directory to perform a search in the domain specified by searchBase. The password for this user password must be stored in the Terracotta keychain used by the Terracotta server, using as key the root of the LDAP URI, ldap://admin_user@server_name:server_port, with no trailing slash ("/").
server_address:server_port The IP address or resolvable fully qualified domain name of the server, and the port for Active Directory.
searchBase Specifies the Active Directory domain to be searched. For example, if the Active Directory domain is reggae.jamaica.org, then the format is searchBase=dc=reggae,dc=jamaica,dc=org.
groupBindings Specifies the mappings between Active Directory groups and Terracotta roles. For example, groupBindings=Domain%20Admins=admin,Users=terracotta maps the Active Directory groups "Domain Admins" and "Users" to the "admin" and "terracotta" Terracotta roles, respectively. To be mapped, the named Active Directory groups must be part of the domain specified in searchBase; all other groups (including those with the specified names) in other domains are ignored.

For example:

<auth>
  <realm>com.tc.net.core.security.ShiroActiveDirectoryRealm</realm> 
  <url>ldap://bmarley@172.16.254.1:389?searchBase=dc=reggae,dc=jamaica,dc=org%26
       groupBindings=Domain%20Admins=admin,Users=terracotta</url>
  <user></user>
</auth>

Standard LDAP Configuration

Specify the realm and URL in the <security> section of the Terracotta configuration as follows:

<auth>
  <realm>com.tc.net.core.security.ShiroLdapRealm</realm>
  <url>ldap://directory_manager@myLdapServer:636?
       userDnTemplate=cn=%7B0%7D,ou=users,dc=mycompany,dc=com%26
       groupDnTemplate=cn=%7B0%7D,ou=groups,dc=mycompany,dc=com%26
       groupAttribute=uniqueMember%26
       groupBindings=bandleaders=admin,bandmembers=terracotta</url>
  <user></user>
</auth>

Note the value of the <realm> element, which must specify the correct class (or Shiro security realm) for Active Directory. The components of the URL are defined in the following table.

Component Description
ldap:// For the scheme, use either ldap:// or ldaps://.
directory_manager The name of a user with sufficient rights on the LDAP server to perform searches. No user is required if anonymous lookups are allowed. If a user is required, the user's password must be stored in the Terracotta keychain, using as key the root of the LDAP URL, ldap://admin_user@server_name:server_port, with no trailing slash ("/").
server_address:server_port The IP address or resolvable fully qualified domain name of the server, and the LDAP server port.
userDnTemplate Specifies user-template values. See the example below.
groupDnTemplate Specifies group-template values. See the example below.
groupAttribute Specifies the LDAP group attribute whose value uniquely identifies a user. By default, this is "uniqueMember". See the example below.
groupBindings Specifies the mappings between LDAP groups and Terracotta roles. For example, groupBindings=bandleaders=admin,bandmembers=terracotta maps the LDAP groups "bandleaders" and "bandmembers" to the "admin" and "terracotta" Terracotta roles, respectively.

For example:

<auth>
  <realm>com.tc.net.core.security.ShiroLdapRealm</realm>
  <url>ldap://dizzy@172.16.254.1:636?
       userDnTemplate=cn=%7B0%7D,ou=users,dc=mycompany,dc=com%26
       groupDnTemplate=cn=%7B0%7D,ou=groups,dc=mycompany,dc=com%26
       groupAttribute=uniqueMember%26
       groupBindings=bandleaders=admin,bandmembers=terracotta</url>
  <user></user>
</auth>

This implies the LDAP directory structure is set up similar to the following:

+ dc=com  
    + dc=mycompany  
        + ou=groups  
            + cn=bandleaders  
                  | uniqueMember=dizzy
                  | uniqueMember=duke
            + cn=bandleaders
                  | uniqueMember=art
                  | uniqueMember=bird

If, however, the the LDAP directory structure is set up similar to the following:

+ dc=com  
    + dc=mycompany  
        + ou=groups  
            + cn=bandleaders  
                  | musician=dizzy
                  | musician=duke
            + cn=bandleaders
                  | musician=art
                  | musician=bird

then the value of groupAttribute should be "musician".

Using the CDATA Construct

To avoid encoding the URL, wrap it in a CDATA construct as shown:

<url><![CDATA[ldap://dizzy@172.16.254.1:636?
     userDnTemplate=cn={0},ou=users,dc=mycompany,dc=com&
     groupDnTemplate=cn={0},ou=groups,dc=mycompany,dc=com&
     groupAttribute=uniqueMember&
     groupBindings=bandleaders=admin,bandmembers=terracotta]]></url>