| Table of Contents |
|---|
Introduction
- LDAP/Directory URL
- Bind user and password
- User search base
- User search filter
LDAP directory can be configured using UI(v6.1 onwards) or API. One Users can configure one or more LDAPs LDAP directories at the same time. Once configured, the LDAPs The LDAP directory names will appear on the login and sign up page as a dropdown.
...
Configure the LDAP Directory via UI
Super admins can configure LDAP directory via UI (v6.1 onwards) by going navigating to Extras from the home page.
...
Click on 'Identity Providers' and create a new entry for registering to your LDAP directory. Select the type as LDAP and fill all required details
...
Once created, the list of all LDAPs LDAP directories registered are displayed and can be updated if required.
Via REST API
openspecimen/rest/ng/auth-domains
Use the register authentication domain resource for registering LDAP authentication domains in OpenSpecimen application. Use the HTTP POST method to call this API by passing the below details in JSON format.
...
...
...
...
A unique user-friendly name that end-user wants to give his/her domain. E.g., Hopkins_LDAP, KUMC_LDAP, etc.
Unique name for the LDAP. E.g., UNIV_LDAP, HOSP_LDAP.
Should be "com.krishagni.catissueplus.core.auth.services.impl.LdapAuthenticationServiceImpl"
If you are going to customize the LDAP implementation for some reason, replace the string with your custom class name.
This parameter is mandatory.
There are two authentication strategies:
- Bind Authentication: Authenticate directly to the LDAP server. Needs URL and userDnPatterns.
- Password comparison: The password supplied by the user is compared with the one stored in the repository. Needs url, userDn, password, userSearchFilter and userSearchBase.
The parameter that comes under the authProviderProps parameter is described below.
url -
LDAP URLs have the following syntax:
ldapItem | Description |
|---|---|
| Host URL | LDAP directory URLs have this syntax: ldap[s]://<hostname>:<port> |
|
|
|
The distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search.
If this component is empty, the search starts at the root DN. Eg
|
userDnPatterns - User Dn pattern. Eg. "uid={0}" or in case of active directory "sAMAccountName={0}".
OpenSpecimen creates full Dn using userDnPattern and baseDn and tries to authenticate by provided username and password.
Eg.
| Code Block |
|---|
userName - "jonDoe",
password - "passwd"
url - ldap://ldap.forumsys.com:389/dc=example,dc=com
userDnPatterns - "uid={0}" or "sAMAccountName={0}"
Full Dn - "uid=jonDoe,dc=example,dc=com" or "sAMAccountName=jonDoe,dc=example,dc=com"
OR
url - ldap://ldap.forumsys.com:389/dc=example,dc=com
userDnPatterns - "uid={0}, ou=users" or "sAMAccountName={0},ou=users"
Full Dn - "uid=jonDoe, ou=users, dc=example, dc=com" or "sAMAccountName=jonDoe, ou=users, dc=example, dc=com" |
| Bind DN | This is required for authenticating to the directory. Eg. "cn=read-only-admin,ou=users,dc=example,dc=com" |
| Password | Password of the Bind DN user. | ||
| Search Base | User search base, from where the search will be started. It might be an empty string like "" or "ou=People". If Oracle DBMS is used, then an empty string is treated as null, which will fail LDAP authentication. Therefore it is advised to specify the base node from which the search needs to be carried. Eg.
|
|
|
|
|
|
http[s]:<host>:<port>/openspecimen/rest/ng/auth-domains
Use this URL to register the authentication domain in the OpenSpecimen application.
Result:
The response of this request will contain the details of the registered authentication domain.
Below is the example of the register authentication domain:
- Ldap Domain Registration :
...
POST: Use to register new domain
PUT : Use to update existing domain
...
| Code Block |
|---|
{
"name": "krishagni-ldap",
"implClass": "com.krishagni.catissueplus.core.auth.services.impl.LdapAuthenticationServiceImpl",
"authType": "ldap",
"authProviderProps": {
"url": "ldap://ldap.forumsys.com:389/",
"userDn": "cn=read-only-admin,ou=users,dc=example,dc=com",
"password": "passwd",
"userSearchFilter": "uid= {0}",
"userSearchBase": "dc=example,dc=com"
}
} |
...
Response
| Code Block |
|---|
{
"id": 3,
"name": "krishagni-ldap",
"implClass": "com.krishagni.catissueplus.core.auth.services.impl.LdapAuthenticationServiceImpl",
"authType": "ldap",
"authProviderProps": {
"url": "ldap://ldap.forumsys.com:389/",
"userDn": "cn=read-only-admin,ou=users,dc=example,dc=com",
"password": "passwd",
"userSearchFilter": "uid= {0}",
"userSearchBase": "dc=example,dc=com"
}
} |
This section describes the response cases for register authentication API
| Search Filter | Search user using an attribute. Eg. "(uid={0})" or in case of active directory "(sAMAccountName={0})" |
Debugging LDAP Issue
Run the below command on command prompt/terminal and fill the same details as configured on OpenSpecimen UI. This command will give you an error if there is an issue with configuration, and if it works fine, then the same configuration will work in OpenSpecimen.
...
Here 'test' is the user account created in LDAP, and the same user needs to be created into OpenSpecimen. Here is a wiki page to setup LDAP users. (refer to via UI section)
Delete the LDAP configuration (via backend)
Note down the domain name and provider id which needs to be deleted.
Code Block language sql select * from os_auth_domains;Delete the entries of the identity provider and their properties from respective tables.
Code Block language sql delete from os_auth_domains where domain_name='<identity-provider-name-to-be-deleted>'; delete from os_auth_provider_props where AUTH_PROVIDER_ID = <provider-id-query#1>; delete from os_auth_providers where identifier = <provider-id-query#1>;