LDAP¶
ODAS supports LDAP authentication and group resolution.
Note
In this document, we will refer to LDAP, but it can be used to connect to Active Directory servers as well.
Configuration Settings¶
The following configuration settings are used to configure LDAP authentication:
LDAP_BIND_TEMPLATE
LDAP_HOST
LDAP_PORT
LDAP_USE_SSL
LDAP_BASE_DN
LDAP_DOMAIN
And for LDAP group resolution:
GROUP_RESOLVER_LDAP_HOST
GROUP_RESOLVER_LDAP_PORT
GROUP_RESOLVER_LDAP_USE_SSL
GROUP_RESOLVER_LDAP_BASE_DN
GROUP_RESOLVER_LDAP_USER_SEARCH_FILTER
GROUP_RESOLVER_LDAP_GROUP_SEARCH_FILTER
GROUP_RESOLVER_LDAP_USER
GROUP_RESOLVER_LDAP_PASSWORD
GROUP_RESOLVER_LDAP_MEMBER_FIELD_NAME
Note
You should consult your IT team to find out the actual values for your specific environment for many of these settings.
Configuring LDAP Authentication¶
To configure LDAP authentication, you will need to know the following values:
- Your LDAP server host and port. The port values are typically
389
for non-SSL connections and636
for SSL ones. - Whether or not your LDAP server uses SSL.
- Converting the username to a bindable identifier (e.g. the
DN
,userPrincipalName
, etc).
Converting a username to a bindable identifier¶
In LDAP, each user is identified by a fully-specified Distinguished Name (DN
).
This typically includes the full Organizational Unit and other values, and may even contain the user's full name instead of their username.
For example, a DN might be:
CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com
In order to authenticate to an LDAP server (called "binding"), you need either the full DN of a user or another identifier (such as sAMAccount
or userPrincipalName
) and their password.
Since the username that users supply to authenticate does not typically match one of these values, it needs to be converted to one of them.
ODAS provides three mechanisms to do the conversion:
- LDAP bind template, that provides a string template where the username will be replaced
- Base DN, to which the username will be prepended to create a DN.
- LDAP Domain, which will be prepended to the user.
Using an LDAP Bind Template¶
Values for this setting are put in LDAP_BIND_TEMPLATE
.
Each bind template should contain a single '%s', which is substituted with the user name trying to authenticate.
For example, a bind template of cn=%s,ou=ca,dc=domain,dc=com
with the user Alice
trying to authenticate, the resulting binding string for the LDAP server would be: cn=Alice,ou=ca,dc=domain,dc=com
.
Multiple bind strings can be specified separated by ;
.
In this case, ODAS will try each bind string in order, authenticating the user on the first successful bind.
For example, if this config was set to: cn=%s,ou=ca,dc=domain,dc=com;cn=%s,ou=wa,dc=domain,dc=com
, again with the user being Alice, ODAS will try binding with: cn=Alice,ou=ca,dc=domain,dc=com
and if unsuccessful, try with cn=Alice,ou=wa,dc=domain,dc=com
.
The user can authenticate if any of the binds succeeded and ODAS will not try the subsequent templates.
Since some systems do not have the desired username in the DN at all (e.g. if the DN is CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com
, you would need to authenticate with Smith, John
as the username), you can also typically authenticate with one of userPrincipalName
or sAMAccountName
.
For example, userPrincipalName
for the CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com
might be john.smith@okera.com
, and so the LDAP_BIND_TEMPLATE
would be %s@okera.com
and the login user would be john.smith
.
Note: This value cannot be set if either
LDAP_BASE_DN
orLDAP_DOMAIN
is set.
Using a Base DN¶
Values for this setting are put in LDAP_BASE_DN
.
In some cases, the username appears in the DN in the Common Name (CN
) section, and you can specify the base DN to use.
For example, consider the following DN:
CN=jsmith,DC=ad,DC=okera,DC=com
In this case, the Base DN would be ad.okera.com
, and would look like this in the configuration file:
LDAP_BASE_DN: ad.okera.com
When a user logs in (e.g. with username alice
), it would construct the following DN:
CN=alice,DC=ad,DC=okera,DC=com
Note
Using LDAP_BIND_TEMPALTE
is recommended over LDAP_BASE_DN
as it is more flexible, e.g. if you need to specify an OU
as part of the DN or a non-DN identifier.
Using the LDAP Domain¶
This is the default domain for users.
For example, if set to ALL USERS
and a user tries to log in with their username, userid
, Okera will authenticate (i.e. bind) with the LDAP server using ALL USERS\\userid
.
If a domain is explicitly specified when logging in, Okera will ignore this value.
For example, in the same identical configuration, if the user explicitly logged in as TEST DOMAIN\\userid
, then we will authenticate with LDAP using exactly that login.
By default, this is not set and there is no default domain.
Note
Using LDAP_BIND_TEMPLATE
or LDAP_BASE_DN
is recommended over LDAP_DOMAIN
.
Example Configuration¶
An example LDAP configuration might be:
LDAP_HOST: ldap.company.com
LDAP_PORT: 636
LDAP_USE_SSL: true
LDAP_BIND_TEMPLATE: cn=%s,ou=users,dc=company,dc=com
This would tell ODAS to connect to ldap.company.com:636
using an SSL-enabled connection, and to take the passed in username and password and bind to the LDAP server with with cn=<username>,ou=users,dc=company,dc=com
.
Verify LDAP authentication using curl¶
If you have a username and password that you want to test logging into an ODAS cluster configured with LDAP authentication, you can check that your configuration is correct using cURL
:
$ curl <ODAS REST URL>/api/health-authenticated -u <username>
Enter host password for user '<username>':
{
"health": "ok",
"token": null,
"user": "<username>"
}
NOTE:
ODAS REST URL
should take the form ofhttps://<REST HOST or IP>:<REST PORT>
orhttp://<REST HOST or IP>:<REST PORT>
, depending on whether SSL is enabled or not (it is typically enabled and strongly recommended).
Exploring LDAP related logs¶
To verify if the LDAP related values are set as intended, and for LDAP related debugging, look for the following logs in your REST service.
The logs to look for will follow this general format
LDAP configurations initialized
LDAP Server: <LDAP_HOST>:<LDAP_PORT>
LDAP Server Base DN: <base DN in 'dc=x' format>
An example log output assuming your LDAP server is at 127.0.0.4:389 and LDAP_BASE_DN is "example.com":
LDAP configurations initialized
LDAP Server: 127.0.0.4:389
LDAP Server Base DN: dc=example,dc=com
If the above lines are not present, your REST service did not start with LDAP authentication enabled.
Configuring LDAP Group Resolution¶
LDAP authentication will allow users to authenticate to the Web UI and REST API using their normal credentials, but it will not tell ODAS what groups those users belong to. In order to get this information, LDAP group resolution needs to be used, which allows ODAS to find all the groups a particular user belongs to.
To configure LDAP group resolution, you will need to know the following values:
- Your LDAP server host and port. The port values are typically
389
for non-SSL connections and636
for SSL ones. - Whether or not your LDAP server uses SSL.
- A service account to use to connect to the LDAP server to run queries (both the username and password).
- A templatized search filter to locate a specific user.
- A search filter to search only groups.
- The field name in a group object that has membership information.
Configuration Example¶
An example LDAP configuration might be:
GROUP_RESOLVER_LDAP_HOST="ldaps://ldap.company.com"
GROUP_RESOLVER_LDAP_PORT=636
GROUP_RESOLVER_LDAP_USE_SSL=true
GROUP_RESOLVER_LDAP_BASE_DN: "OU=ldap,DC=company,DC=com"
GROUP_RESOLVER_LDAP_USER_SEARCH_FILTER="(&(objectClass=Person)(userPrincipalName={0}@company.com))"
GROUP_RESOLVER_LDAP_GROUP_SEARCH_FILTER="(objectClass=groupOfNames)"
GROUP_RESOLVER_LDAP_MEMBER_FIELD_NAME="member"
GROUP_RESOLVER_LDAP_USER="cn=svc_account,dc=ldap,dc=company,dc=com"
GROUP_RESOLVER_LDAP_PASSWORD="SuperGreatPassword"
This would tell ODAS to:
- Connect to
ldap.company.com:636
using an SSL-enabled connection. - Bind to it using
svc_account
/SuperGreatPassword
as the username/password. - When a
<username>
needs to be resolved, find it's DN by running the query(&(objectClass=Person)(userPrincipalName=<username>@company.come))
on the base pathOU=ldap,DC=company,DC=com
. - Take the found DN for that username, and find all groups it is a member of using the
(objectClass=groupOfNames)
filter andmember
field.
Service Account¶
ODAS needs to be able to convert arbitrary usernames to DNs without having the credentials of those users, and thus requires a service account to run these queries. The service account should have permissions to see information about any user in the system.
User Search Filter¶
The user search filter is a templatized string, used to convert a username into a query that will uniquely resolve a user (and thus find that user's DN).
The templatized value takes the form of {0}
.
For example, if the username is alice
and it is identified in LDAP by it's userPrincipalName
of alice@company.com
, the user search filter might be:
(&(objectClass=Person)(userPrincipalName={0}@company.com))
Note
We escape XML characters (e.g. &
becomes &
).
Group Search Filter¶
The group search filter is used to limit LDAP queries to only return group-type objects.
In most LDAP configurations, a query of (objectClass=groupOfNames)
is sufficient.
Member Field¶
When running the search to find all groups, ODAS limits it to find only groups that the particular user is a member of.
This is done by specifying an extra constraint on the field inside the group object that contains a member.
This field is typically called member
.
Using ldapsearch
¶
Finding the right values for these settings can be tricky, and typically requires some knowledge of your LDAP set up.
You can use the ldapsearch
tool to try and find what the values might be, assuming that you know your LDAP host/port and whether it uses SSL or not.
NOTE:
ldapsearch
may not be preinstalled on your machine, and you should use your system's package manager to install it.
If your LDAP server does not use SSL, use the following pattern:
ldapsearch -H ldap://<ldap server> -p <ldap port> -x -D "<bind name>" -b "<search directory>" "<bind name>" -vvv -W
If it uses SSL, use the following pattern:
LDAPTLS_REQCERT=never ldapsearch -Z -H ldaps://<ldap host>:<ldap port> -x -D "<bind name>" -b "<search directory>" "<bind name>" -vvv -W
For the following examples, we will use the non-SSL version.
For example, if you were to set LDAP_BIND_TEMPLATE
to %s@okera.com
, you could have the following invocation for the alice
user:
ldapsearch -H ldap://ad.okera.com -p 389 -x -D "alice@okera.com" -b "dc=okera,dc=com" "(userPrincipalName=alice@okera.com)" -vvv -W
This should give you an output that allows you to see the full LDAP object for this user, including their DN.