Tamr Documentation

LDAP Authentication and Authorization

Configuring LDAP user authentication and authorization.

Tamr uses local database-backed authentication and authorization by default.

Tamr can also use LDAP to authenticate and authorize users. Configuring Tamr to use LDAP allows users to log into Tamr using their LDAP username and password and be authorized under their LDAP group membership.

Tip: LDAP group names are case-sensitive. Be sure to enter all values exactly as they appear.

Configuring LDAP Authentication and Authorization

To configure LDAP authentication and authorization:

  1. Connect Tamr to LDAP. See Connecting Tamr to LDAP.
  2. Configure LDAP User and Group Information. See Configuring LDAP User and Group Information.
  3. Optionally configure additional LDAP domains. See Configuring Additional LDAP Domains.
  4. Map Tamr Groups to LDAP Groups. See Mapping Tamr Groups to LDAP Groups.

User and Group Synchronization

  • User synchronization between Tamr and LDAP is "lazy", meaning that a user's account is added from LDAP to Tamr only when that user first logs into Tamr.
  • Group synchronization. Once a user is logged into Tamr, they must belong to any group in the configured group base domain that passes the configured group filter to be authorized. By default, unauthorized users are not given a role.

Connecting Tamr to LDAP

To connect Tamr to LDAP:

  1. Set each of the following configuration variables using the administration utility. See Creating or Updating a Configuration Variable.
  2. Restart Tamr and its dependencies. See Restarting.

TAMR_AUTH_LDAP_HOST

Configuration Variable

Example Value

TAMR_AUTH_LDAP_HOST

localhost

This must be the fully-qualified hostname of the LDAP server. You cannot specify an alias for this variable. For example, specifying ${TAMR_AUTH_LDAP_HOST} does not work.

TAMR_AUTH_LDAP_PORT

Configuration Variable

Example Value

TAMR_AUTH_LDAP_PORT

389

The port number of the LDAP server.

To use unencrypted connections enter the LDAP port number, typically 389. To use connections secured with LDAPS, enter the port number for secure connections, typically 689.

TAMR_AUTH_LDAP_ADMIN_DN

Configuration Variable

Example Value

TAMR_AUTH_LDAP_ADMIN_DN

cn=admin,dc=example,dc=com

The LDAP domain name for the user account Tamr should use to connect to LDAP. This value must be the fully-qualified domain name (FQDN). Do not use aliases, such as [email protected].

TAMR_AUTH_LDAP_ADMIN_PASSWORD

Configuration Variable

Example Value

TAMR_AUTH_LDAP_ADMIN_PASSWORD

JonSn0w

The password of the user account Tamr should use to connect to LDAP.

TAMR_AUTH_LDAP_SECURE

Configuration Variable

Example Value

TAMR_AUTH_LDAP_SECURE

true

The Boolean value (true or false) that specifies whether to enable Tamr to connect over LDAPS.

Configuring LDAP User and Group Information

To configure LDAP user and group information:

  1. For each of the following configuration variables, set the configuration variable using the admin tool. See Creating or Updating a Configuration Variable.
    Tip: LDAP group names are case-sensitive. Be sure to enter all values exactly as they appear.
  2. Restart Tamr and its dependencies. See Restarting.

TAMR_AUTH_LDAP_USER_BASEDN

Configuration Variable

Example Value

TAMR_AUTH_LDAP_USER_BASEDN

ou=People,dc=example,dc=com

The base domain name for the users Tamr should query.

TAMR_AUTH_LDAP_USER_IDATTR

Configuration Variable

Example Value

TAMR_AUTH_LDAP_USER_IDATTR

cn

The name of the LDAP attribute that Tamr matches a username against, for example, if the user logs into Tamr as john.snow the LDAP attribute containing the value john.snow is configured here. Note, this is not necessarily the name of the LDAP unique identifier attribute of the user, typically uid.

TAMR_AUTH_LDAP_USER_FILTER

Configuration Variable

Example Value

TAMR_AUTH_LDAP_USER_FILTER

(cn=*)

The filter expression Tamr should apply when querying for a list of users. Set a value when you wish to restrict the users (within TAMR_AUTH_LDAP_USER_BASEDN) considered for authentication.

TAMR_AUTH_LDAP_USER_FINDER

Configuration Variable

Example Value

TAMR_AUTH_LDAP_USER_FINDER

(&(uid={username})(memberOf=cn=Directory Administrators,ou=Groups,dc=tamr,dc=com))

Use a user's ldap attributes, in addition to their credentials, to restrict them from authenticating. The expression must return only one result. To enforce this, the expression must begin with the AND condition &(uid={username}). The remainder of the expression can be any ldap search conditions on a user's attributes, e.g. their group membership.

TAMR_AUTH_LDAP_GROUP_BASEDN

Configuration Variable

Example Value

TAMR_AUTH_LDAP_GROUP_BASEDN

ou=Groups,dc=example,dc=com

The base domain name for the groups Tamr should query.

TAMR_AUTH_LDAP_GROUP_IDATTR

Configuration Variable

Example Value

TAMR_AUTH_LDAP_GROUP_IDATTR

cn

The name of the unique identifier attribute of the LDAP groups Tamr should use.
The name of the LDAP attribute that Tamr matches a group name against.

For example, if the user logs into Tamr and is a member of the group cn=curators,ou=Groups,dc=example,dc=com, the LDAP attribute containing the value curators is configured here. Note, this is not necessarily the name of the LDAP unique identifier attribute of the group, which is typically gid.

TAMR_AUTH_LDAP_USER_MEMBEROFATTR

Configuration Variable

Default Value

TAMR_AUTH_LDAP_USER_MEMBEROFATTR

memberOf

The name of the LDAP attribute containing the group membership of a user. The default value is memberOf, but isMemberOf and uniqueMember are also common.

Note: The User object must contain an attribute specifying the user's group membership. Tamr uses the user object to obtain the list of groups to which a user belongs.

TAMR_AUTH_LDAP_GROUP_FILTER

Configuration Variable

Example Value

TAMR_AUTH_LDAP_GROUP_FILTER

(cn=*)

The filter expression Tamr should apply when querying groups.

Configuring Additional LDAP Domains

Tamr can optionally query additional LDAP domains.

To configure additional LDAP domains:

  1. Set each of the following configuration variables using the admin tool. See Setting Configuration Variables.
  2. Restart Tamr and its dependencies. See Restarting.

TAMR_AUTH_ADDITIONAL_CREDENTIAL_FACTORIES

Configuration Variable

Example Value

TAMR_AUTH_ADDITIONAL_CREDENTIAL_FACTORIES

{
    'type': 'com.tamr.auth.dao.LdapCredentialFactory',
    'host':  'examplehost2.myhostname.net',
    'port':     '389',
    'useSSL':     'false',
    'adminDn':     'CN=TAMR_ADMIN,OU=ServiceAccounts,DC=people,DC=company',
    'adminPassword':     'password',
    'userBaseDn':         'OU=Personal,OU=US,OU=people,DC=company',
    'userIdAttribute':     'AccountName',
    'groupBaseDn':         'OU=PersonalGroups,DC=groups,DC=company',
    'groupFilter':         '(cn=*)' 
}
|||
{
    'type': 'com.tamr.auth.dao.LdapCredentialFactory',
    'host':  'examplehost3.myhostname.net',
    'port':     '389',
    'useSSL':     'false',
    'adminDn':     'CN=TAMR_ADMIN,OU=ServiceAccounts,DC=people,DC=company',
    'adminPassword':     'password',
    'userBaseDn':         'OU=Personal,OU=EUR,OU=people,DC=company',
    'userIdAttribute':     'AccountName',
    'groupBaseDn':         'OU=PersonalGroups,OU=EUR,DC=groups,DC=company',
    'groupFilter':         '(cn=*)' 
}

A list of |||-separated JSON dictionaries, where each dictionary comprises an LDAP domain with the following key-value pairs.

JSON Key

Description / Example Value

type

com.tamr.auth.dao.LdapCredentialFactory

host

See TAMR_AUTH_LDAP_HOST.

port

See TAMR_AUTH_LDAP_PORT.

adminDn

See TAMR_AUTH_LDAP_ADMIN_DN.

adminPassword

See TAMR_AUTH_LDAP_ADMIN_PASSWORD.

useSSL

See TAMR_AUTH_LDAP_SECURE.

userBaseDn

See TAMR_AUTH_LDAP_USER_BASEDN.

userIdAttribute

See TAMR_AUTH_LDAP_USER_IDATTR.

userFilter

See TAMR_AUTH_LDAP_USER_FILTER.

userFinder

See TAMR_AUTH_LDAP_USER_FINDER.

userMemberOfAttribute

See TAMR_AUTH_LDAP_USER_MEMBEROFATTR.

groupFilter

See TAMR_AUTH_LDAP_GROUP_FILTER.

groupIdAttribute

See TAMR_AUTH_LDAP_GROUP_IDATTR.

groupBaseDn

See TAMR_AUTH_LDAP_GROUP_BASEDN.

Mapping Tamr Groups to LDAP Groups

To create a Tamr group corresponding to one or more LDAP groups, issue an API request with POST /user/groups API, specifying a list of LDAP group DNs in the attribute sourceGroupNames.

Note: The value returned by the LDAP user attribute configured in TAMR_AUTH_LDAP_USER_MEMBEROFATTR must match exactly (case-sensitive) the value that you configure in the Tamr group attribute, sourceGroupNames.

To map Tamr groups to LDAP groups:

  1. Create groups using POST /user/groups.
    For example: "sourceGroupNames": ["cn=Directory Administrators,ou=Groups,dc=example,dc=com"].
    For a detailed example of adding groups, see Step 4: Configure Tamr and LDAP Group Information in this section.

An example of Configuring LDAP Authentication and Authorization

The following example configures Tamr to integrate with LDAP for both user authentication and authorization.

The example uses:

  • the LDAP browser phpldapadmin to identify configuration values.
  • the command line utility ldapsearch to confirm configuration values.

Step 1. Identify and Confirm the LDAP Bind User Account

To connect to LDAP, Tamr requires the LDAP server details, host and port number, and the credentials of a functional LDAP user account known as the bind account. Contact your LDAP support team to obtain these details.

In this example, the LDAP server has the IP address 10.23.0.29 and the port number 389. The LDAP bind user credentials are cn=admin,dc=example,dc=com and JonSn0w.

To verify the bind user credentials that Tamr requires:

  1. Access the LDAP server by using the web browser application phpldapadmin:
We choose the admin user as our bind user for querying LDAP. In the web browser we see this user's DN is `cn=admin,dc=example,dc=com`. This value is used for the config var `TAMR_AUTH_LDAP_ADMIN_DN`.We choose the admin user as our bind user for querying LDAP. In the web browser we see this user's DN is `cn=admin,dc=example,dc=com`. This value is used for the config var `TAMR_AUTH_LDAP_ADMIN_DN`.

We choose the admin user as our bind user for querying LDAP. In the web browser we see this user's DN is cn=admin,dc=example,dc=com. This value is used for the config var TAMR_AUTH_LDAP_ADMIN_DN.

  1. Use the ldapsearch command to verify the LDAP server details and bind user credentials. Run the following command on the Tamr host server to confirm that the LDAP server is reachable and that the bind user credentials are valid.
ldapsearch -h <tamr-auth-ldap-host> -p <tamr-auth-ldap-port> \
-D <tamr-auth-ldap-admin-dn> -w <tamr-auth-ldap-admin-password>

For example:

ldapsearch -h 10.23.0.29 -p 389 -D cn=admin,dc=example,dc=com -w JonSn0w
  1. Set the Tamr configuration variables to the confirmed values as follows:
<tamr-home-directory>/tamr/utils/unify-admin.sh config:set \
--file <directory-path>/ldap-config.yaml

where ldap-config.yaml is a YAML file as in the following example:

---
TAMR_AUTH_LDAP_HOST: "10.23.0.29"
TAMR_AUTH_LDAP_PORT: "389"
TAMR_AUTH_LDAP_ADMIN_DN: "cn=admin,dc=example,dc=com"
TAMR_AUTH_LDAP_ADMIN_PASSWORD: "JonSn0w"

Step 2. Identify and Confirm User Information

Tamr authenticates a user by searching LDAP and requires details of the corpus of users to search.

  1. Use the web browser application phpldapadmin to browse the LDAP server and identify the LDAP details of the corpus of users you wish Tamr to search when authenticating. Identify the organization unit "People" with DN ou=People,dc=example,dc=com as the corpus of users that Tamr authenticates.
We choose the organization unit "People" as the corpus users that Tamr authenticates.We choose the organization unit "People" as the corpus users that Tamr authenticates.

We choose the organization unit "People" as the corpus users that Tamr authenticates.

  1. Identify the name of the LDAP attribute on the user object that identifies the user's unique login name.
We identify the attribute name that uniquely identifies a user. In the web browser we see this is `uid`. For example a user logging into Tamr will enter `abergin` as the username. Tamr then searches the user attribute `uid` to find this name. This attribute name is set in the config var `TAMR_AUTH_LDAP_USER_IDATTR`.We identify the attribute name that uniquely identifies a user. In the web browser we see this is `uid`. For example a user logging into Tamr will enter `abergin` as the username. Tamr then searches the user attribute `uid` to find this name. This attribute name is set in the config var `TAMR_AUTH_LDAP_USER_IDATTR`.

We identify the attribute name that uniquely identifies a user. In the web browser we see this is uid. For example a user logging into Tamr will enter abergin as the username. Tamr then searches the user attribute uid to find this name. This attribute name is set in the config var TAMR_AUTH_LDAP_USER_IDATTR.

  1. Use ldapsearch to confirm the LDAP user details.
ldapsearch -h <tamr-auth-ldap-host> -p <tamr-auth-ldap-port> \
-D <tamr-auth-ldap-admin-dn> -w <tamr-auth-ldap-admin-password> \
-b <tamr-auth-ldap-user-basedn> <tamr-auth-ldap-user-idattr>="abergin"
  1. Add the configuration variables TAMR_AUTH_LDAP_USER_BASEDN and TAMR_AUTH_LDAP_USER_IDATTR to ldap-config.yaml and update the configuration.
<tamr-home-directory>/tamr/utils/unify-admin.sh config:set \
--file <directory-path>/ldap-config.yaml

where ldap-config.yaml is a YAML file that contains the following lines:

---
TAMR_AUTH_LDAP_HOST: "10.23.0.29"
TAMR_AUTH_LDAP_PORT: "389"
TAMR_AUTH_LDAP_ADMIN_DN: "cn=admin,dc=example,dc=com"
TAMR_AUTH_LDAP_ADMIN_PASSWORD: "JonSn0w"
TAMR_AUTH_LDAP_USER_BASEDN: "ou=People,dc=example,dc=com"
TAMR_AUTH_LDAP_USER_IDATTR: "uid"

Step 3. Identify and Confirm Group Information

Tamr authorizes a user who is logged in by querying LDAP for the user's group membership and matches that LDAP group to a Tamr group. It requires the details of the corpus of groups to search and a user attribute that specifies their group membership.

  1. Browse the LDAP server and identify the LDAP details of the corpus of groups you wish Tamr to search when authorizing. Identify the organization unit "Groups" with DN ou=Groups,dc=example,dc=com as the corpus of groups that Tamr authorizes.
We choose the organization unit "Groups" as the corpus of groups that Tamr authoizes. Additionally note that here, the name of the attribute that uniquely identifies the group is `cn`.We choose the organization unit "Groups" as the corpus of groups that Tamr authoizes. Additionally note that here, the name of the attribute that uniquely identifies the group is `cn`.

We choose the organization unit "Groups" as the corpus of groups that Tamr authoizes. Additionally note that here, the name of the attribute that uniquely identifies the group is cn.

  1. Identify the name of the attribute that uniquely identifies a given group. Here it is the attribute cn.

  2. To identify which group a given user belongs to, look up the user's information and identify which attribute contains the user's groups. Identify the user attribute memberOf as containing this information.

The user information for `uid=gtyler` contains an attribute `memberOf` that lists that user's groups, here "Accounting Managers". The group membership attribute name of the user object is set in the variable `TAMR_AUTH_LDAP_USER_MEMBEROFATTR`.The user information for `uid=gtyler` contains an attribute `memberOf` that lists that user's groups, here "Accounting Managers". The group membership attribute name of the user object is set in the variable `TAMR_AUTH_LDAP_USER_MEMBEROFATTR`.

The user information for uid=gtyler contains an attribute memberOf that lists that user's groups, here "Accounting Managers". The group membership attribute name of the user object is set in the variable TAMR_AUTH_LDAP_USER_MEMBEROFATTR.

  1. Use ldapsearch to confirm the LDAP group details.
ldapsearch -h <tamr-auth-ldap-host> -p <tamr-auth-ldap-port> \
-d <tamr-auth-ldap-admin-dn> -w <tamr-auth-ldap-admin-password> \
-b <tamr-auth-ldap-group-basedn> \
<tamr-auth-ldap-group-idattr>="Accounting Managers"
  1. Use ldapsearch to confirm the LDAP user details contains the attribute memberOf. If this attribute is an operational attribute, add the argument +, as follows:
ldapsearch -h <tamr-auth-ldap-host> -p <tamr-auth-ldap-port> \
-d <tamr-auth-ldap-admin-dn> -w <tamr-auth-ldap-admin-password> \
-b <tamr-auth-ldap-user-basedn> <tamr-auth-ldap-user-idattr>="abergin" +
  1. Add the configuration variables TAMR_AUTH_LDAP_GROUP_BASEDN, TAMR_AUTH_LDAP_GROUP_IDATTR and TAMR_AUTH_LDAP_USER_MEMBEROFATTR to ldap-config.yaml and update the configuration.
<tamr-home-directory>/tamr/utils/unify-admin.sh config:set \
--file <directory-path>/ldap-config.yaml

where ldap-config.yaml is a YAML file that contains the following configuration:

---
TAMR_AUTH_LDAP_HOST: "10.23.0.29"
TAMR_AUTH_LDAP_PORT: "389"
TAMR_AUTH_LDAP_ADMIN_DN: "cn=admin,dc=example,dc=com"
TAMR_AUTH_LDAP_ADMIN_PASSWORD: "JonSn0w"
TAMR_AUTH_LDAP_USER_BASEDN: "ou=People,dc=example,dc=com"
TAMR_AUTH_LDAP_USER_IDATTR: "uid"
TAMR_AUTH_LDAP_GROUP_BASEDN: "ou=Groups,dc=example,dc=com"
TAMR_AUTH_LDAP_GROUP_IDATTR: "cn"
TAMR_AUTH_LDAP_USER_MEMBEROFATTR: "memberOf"

Step 4. Configure Tamr and LDAP Group Information

For each LDAP group, create a corresponding Tamr group.

To configure Tamr groups:

Create the Tamr group Tamr Accounting Managers corresponding to the LDAP group cn=Accounting Managers,ou=Groups,dc=example,dc=com, by calling the API POST /user/groups with the following request.

{
  "groupname": "Tamr Accounting Managers",
  "description": "Group for Tamr Admins.",
   "sourceGroupNames": [
    "cn=Accounting Managers,ou=Groups,dc=example,dc=com"
  ]
}

Note: To configure roles, see Editing a User's Roles.

Step 5. Optionally Configure User Filters

A user filter allows Tamr to prevent users from authenticating using a user's ldap properties in addition to the user's credentials.
For example, to configure a filter that only allows users

  • of objectClass person
  • of group membership Accounting Managers

to authenticate successfully, set the configuration variable TAMR_AUTH_LDAP_USER_FINDER as follows

TAMR_AUTH_LDAP_USER_FINDER: "(&(uid={username})(objectClass=person)(memberOf=cn=Accounting Managers,ou=Groups,dc=example,dc=com))"

Updated about a month ago



LDAP Authentication and Authorization


Configuring LDAP user authentication and authorization.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.