Configuring LDAP connection
Configure an LDAP (Lightweight Directory Access Protocol) connection for your IBM® Cloud Private cluster.
You must connect an LDAP directory with your IBM Cloud Private cluster. You can then add users from your LDAP directory into your cluster.
The following LDAP types are supported:
- IBM Tivoli Directory Server
- IBM Lotus Domino
- IBM SecureWay Directory Server
- Novell eDirectory
- Sun Java™ System Directory Server
- Netscape Directory Server
- Microsoft Active Directory
- Custom
Note: You can configure an account lockout policy when you set up your LDAP server. An account lockout policy provides more security by restricting access to the account if multiple login attempts fail.
Required user type or access level: Cluster administrator
Configuring LDAP over SSL
You can secure your LDAP connection by using SSL (Secure Sockets Layer). You must prepare your IBM Cloud Private cluster for connecting with your LDAP over SSL (LDAPS) directory.
Before you begin, you must import the public or private SSL certificate that you used for setting up your LDAPS directory.
Retrieving the SSL certificate
If you have the SSL certificate of your LDAP server, proceed with Encoding the SSL certificate.
If you do not have the SSL certificate of your LDAP server, complete the following steps to retrieve the SSL certificate:
Note: You need the ldapsearch
program to run these commands. You can install it by running apt install ldap-utils
on Ubuntu and yum install openldap-clients
on Red Hat Enterprise Linux (RHEL).
-
Ensure no SSL certificates are in the
/etc/openldap/cacerts
directory. -
Run the following
ldapsearch
command to retrieve the certificate name:ldapsearch -H <LDAP server URL> -d 1 -b <searchbase> -D "" -s base "(<filter>)"
Where,
- LDAP server URL is your LDAP directory domain name, and port. Format:
ldaps://<LDAP server domain name or IP address>:<port>
. - -d is the debugging level.
- -b is the search base.
- -D is the bind DN. This parameter is optional.
- -s is the scope of search.
- filter is the LDAP filter. Default filter:
(objectClass=*)
.
Following is an example command and output:
$ ldapsearch -H ldaps://corp.example.com:636 -d 1 -b o=example.com -D "" -s base "(objectclass=*)" ldap_url_parse_ext(ldaps://corp.example.com:636) ldap_create ldap_url_parse_ext(ldaps://corp.example.com:636/??base) ldap_sasl_bind ldap_send_initial_request ldap_new_connection 1 1 0 ldap_int_open_connection ldap_connect_to_host: TCP corp.example.com:636 ldap_new_socket: 3 ldap_prepare_socket: 3 ldap_connect_to_host: Trying 9.17.186.253:636 ldap_pvt_connect: fd: 3 tm: -1 async: 0 attempting to connect: connect success TLS: certdb config: configDir='/etc/openldap' tokenDescription='ldap(0)' certPrefix='cacerts' keyPrefix='cacerts' flags=readOnly TLS: cannot open certdb '/etc/openldap', error -8018:Unknown PKCS #11 error. TLS: could not get info about the CA certificate directory /etc/openldap/cacerts - error -5950:File not found. TLS: certificate [CN=DigiCert Global Root G2,OU=www.digicert.com,O=DigiCert Inc,C=US] is not valid - error -8172:Peer's certificate issuer has been marked as not trusted by the user.. TLS: error: connect - force handshake failure: errno 2 - moznss error -8172 TLS: can't connect: TLS error -8172:Peer's certificate issuer has been marked as not trusted by the user.. ldap_err2string ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
The certificate information is in the
TLS: certificate [CN=DigiCert Global Root G2,OU=www.digicert.com,O=DigiCert Inc,C=US] is not valid - error -8172:Peer's certificate issuer has been marked as not trusted by the user..
section of the output. - LDAP server URL is your LDAP directory domain name, and port. Format:
-
Locate the certificate in your web browser, export it to a file in a PEM format, and save the PEM file with a
.crt
extension.
Note: If you have multiple certificates, export each certificate to a file in a PEM format and save the PEM file with a.crt
extension. - Copy the
.crt
file to the master node of your IBM Cloud Private cluster.
Preparing for a single LDAPS connection
If you are configuring a single LDAPS connection, complete the steps in the Encoding the SSL certificate section.
Encoding the SSL certificate
Complete the following steps to encode the certificate in base64:
-
Log on to the master node of your IBM Cloud Private cluster.
-
Convert the certificate into PEM format.
openssl x509 -in <cert>.cer -outform PEM -out <convertedCert>.pem
If your LDAP server uses chain certificates (root CA and intermediate certificates), convert each certificate into PEM format. Then, combine them into one file. Use the following command to combine the converted certificates.
cat <convertedFirstCert.pem> <convertedSecondCert.pem> ..<converted_n_Cert.pem> > <convertedCombinedCert>.pem
-
Encode your certificate in base64.
cat <LDAPS SSL certificate name>.pem | base64 -w 0
The output resembles the following code:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUdDRENDQS9DZ 0F3SUJBZ0lRS3k1dTZ0bDFObXdVaW03Ym8zeU1CekFOQmdrcWhraUc5 ... lDOHg0OU9oZ1E9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0KDQo=
Next, proceed with Preparing your cluster.
Preparing for multiple LDAPS connections
If you are configuring multiple LDAPS connections, first check if you already have a certificate in the "data" > "certificate" section of platform-auth-ldaps-ca-cert
. If you have a certificate, then complete the
steps in the following sections:
If no certificate exists, then complete the steps in Encoding the SSL certificate.
Retrieve the current certificate
You can retrieve the certificate by using the management console or by using the command line interface (CLI).
If you are using the management console, follow these steps:
- Log on to the management console as a cluster administrator.
- From the navigation menu, click Configuration > Secrets.
- Locate
platform-auth-ldaps-ca-cert
and click ACTION > Edit. A Edit Secret window displays. -
Copy the base64 encoded certificate value from "data" > "certificate" section.
“data”: { “certificate”: “LS0tLS1...ASDFASDo=” },
-
Convert the existing encoded certificate and save to a file.
echo "<copied_cert_value>" | base64 --decode > existing_cert.pem
If you are using the CLI, follow these steps:
- Access the CLI of your master node. You need
kubectl
, the Kubernetes command line tool to complete the following tasks. For more information about installing and configuringkubectl
, see Accessing your cluster from the Kubernetes CLI (kubectl). - Get the base64 certificate.
kubectl -n kube-system get secret platform-auth-ldaps-ca-cert -o “jsonpath={.data[‘certificate’]}” | base64 --decode > existing_cert.pem
Next, proceed with Encode the SSL certificate.
Encode the SSL certificate
Complete the following steps to encode the certificate in base64:
- Log on to the master node of your IBM Cloud Private cluster.
-
Convert the new certificate into PEM format.
openssl x509 -in <cert>.cer -outform PEM -out <convertedCert>.pem
If your LDAP server uses chain certificates (root CA and intermediate certificates), convert each certificate into PEM format. Then, combine them into one file. Use the following command to combine the converted certificates.
cat <convertedFirstCert.pem> <convertedSecondCert.pem> ..<converted_n_Cert.pem> > <convertedCombinedCert>.pem
-
Add the existing certificate to the new certificate, or to the combined certificate if you use chain certificates.
cat existing_cert.pem <new_cert.pem or convertedCombinedCert.pem> > final_combined_cert.pem
-
Encode your certificate in base64.
cat <LDAPS SSL certificate name>.pem | base64 -w 0
The output resembles the following code:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUdDRENDQS9DZ 0F3SUJBZ0lRS3k1dTZ0bDFObXdVaW03Ym8zeU1CekFOQmdrcWhraUc5 ... lDOHg0OU9oZ1E9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0KDQo=
Next, complete the steps in the Preparing your cluster section.
Preparing your cluster
You can prepare your cluster by using the management console or by using the CLI.
If you are using the management console, follow these steps:
- Log on to the management console as a cluster administrator.
- From the navigation menu, click Configuration > Secrets.
- Locate
platform-auth-ldaps-ca-cert
and click ACTION > Edit. A Edit Secret window displays. -
Paste the base64 certificate in the following section:
"data": { "certificate": "" },
The updated section resembles the following text:
"data": { "certificate": "LS0tLS1<very_long_base64_string>ASDFASDo=" },
- Click Submit.
- From the navigation menu, click Workloads > DaemonSets.
- Locate
auth-idp
and click ACTION > Edit. A Edit DaemonSet window displays. - Click Submit without making any change. This step is to reload the
auth-idp
pod with the latest secrets and configmap values. -
Wait for a minute or two and then check whether the certificate is mounted on the pod.
-
Get the
auth-idp
pods.kubectl -n kube-system get pods | grep auth-idp
-
Check whether the certificate is mounted on the pod.
kubectl -n kube-system exec -it auth-idp-<pod-id> -c platform-auth-service cat /opt/ibm/ldaps/ldaps-ca.crt
-
If you are using the CLI, follow these steps:
- Access the CLI of your master node. You need
kubectl
, the Kubernetes command line tool to complete the following tasks. For more information about installing and configuringkubectl
, see Accessing your cluster from the Kubernetes CLI (kubectl). -
Copy the LDAPS CA certificate secret to a file:
kubectl get secret platform-auth-ldaps-ca-cert -o yaml -n kube-system > platform-auth-ldaps-ca-cert-secret.yaml
-
Copy and paste the base64 certificate to the
platform-auth-ldaps-ca-cert-secret.yaml
file. -
Get the security service DaemonSet YAML file:
kubectl -n kube-system get ds auth-idp -o yaml > auth-idp.yaml
-
Apply the changes:
kubectl apply -f platform-auth-ldaps-ca-cert-secret.yaml
kubectl apply -f auth-idp.yaml
Next, complete the steps in the Connecting to your LDAP directory section.
Connecting to your LDAP directory
Follow these steps to set up your LDAP connection.
- Log on as an administrator.
- From the navigation menu, click Manage > Identity & Access.
- Click Create Connection. The "LDAP connection" page is displayed.
- Enter the following details to set up your LDAP connection.
Note: You can configure multiple LDAP connection instances to the same LDAP server. However, both the Base DN
and connection Name
must be unique.
LDAP connection
Enter connection information.
- Name: A unique name for the LDAP connection. Format: 1 - 50 alphanumeric characters; Special characters that are allowed:
-
_
- Type: A type of LDAP directory that you are connecting to. Select from the list. Format: 1 - 255 alphanumeric characters; white space is allowed; no special characters are allowed.
-
URL: The LDAP directory domain name or IP address, and the LDAP port number. The domain name must begin with
ldap://
. Example URL:ldap://corpldap.abc.com:389
orldap://10.10.10.1:389
.For LDAPS, you must use the domain name and the URL must begin with
ldaps://
. Example URL:ldaps://corpldap.abc.com:636
.Note: If you are unable to connect to your LDAPS server by using the host name, add the IP address and host name of the LDAPS server in your local DNS. The LDAPS server host name must be resolvable from your IBM Cloud Private master node.
LDAP authentication
Enter authentication information.
- Base DN: The distinguished name of the search base. Example: dc=abc,dc=com. Format: 1 - 255 alphanumeric characters; Special characters that are allowed:
=
.
,
-
- Bind DN: The user who is allowed to search the base DN. Example: cn=admin,dc=abc,dc=com. This parameter is optional. If no user is specified in the
Bind DN
parameter, the LDAP connection is established without authentication. Format: 0 - 255 alphanumeric characters; white space is allowed; Special characters that are allowed:=
.
,
-
-
Bind DN password: The password of the user who is mentioned in the
Bind DN
. This parameter is not required if you do not specify a user in the bind DN. A maximum of 255 characters are allowed.Note: The configuration of Base DN and Bind DN values must be set as case-sensitive and must be a full distinguished name (DN) path. The DN path, including spaces, commas, and other characters, must be the same as configured in the LDAP server. See the following example:
Base DN : DC=mycompany,DC=com Bind DN : CN=Administrator,CN=Users,DC=mycompany,DC=com
For
Base DN
, the following values are invalid:- dc=mycompany,dc=com because
DC
is lowercase alphabet. - DC=mycompany, DC=com because there is a space between the parameters.
For
Bind DN
, the following values are invalid:- cn=Administrator,cn=Users,dc=mycompany,dc=com because
CN
andDC
are lowercase alphabets. - CN=Administrator,DC=mycompany,DC=com because
CN=Users
parameter is missing. - CN=Administrator,CN=Users, DC=mycompany,DC=com because there is a space between the parameters.
- CN=administrator,CN=Users,DC=mycompany,DC=com because the
administrator
parameter value starts with a lowercase alphabet.
Note: Microsoft Active Directory server does a strict check of
Base DN
andBind DN
values while it establishes a connection.You can click Test connection to verify whether the LDAP connection details are valid.
LDAP filters
Enter information about the search filters. For default LDAP filters by LDAP type, see Default LDAP filters by LDAP type.
- dc=mycompany,dc=com because
- Group filter: The filter clause for searching groups. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space,
=
;
.
,
&
%
()
{}
<>
|
- Group ID map: The filter to map a group name to an LDAP entry. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space,
*
:
=
;
.
,
&
%
()
{}
- Group member ID map: The filter to map a user to a group. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space,
*
:
=
;
.
,
&
%
()
{}
- User filter: The filter clause for searching users. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space,
=
;
.
,
&
%
()
{}
<>
|
- User ID map: The filter to map a user name to an LDAP entry. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space,
*
:
=
;
.
,
&
%
()
{}
- Click Connect.
Your IBM Cloud Private cluster is now connected with your LDAP directory.
Next, you can add your LDAP users and user groups to your IBM Cloud Private cluster. For more information about adding users, see Add users to a team and Add groups to a team.
Default LDAP filters by LDAP type
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=groupOfUniqueNames)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | groupOfUniqueNames:uniquemember |
userFilter | string | (&(emailAddress=%v)(objectclass=person)) |
userIdMap | string | *:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=groupOfUniqueNames)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | groupOfUniqueNames:uniquemember |
userFilter | string | (&(uid=%v)(objectclass=ePerson)) |
userIdMap | string | *:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=group)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | memberOf:member |
userFilter | string | (&(sAMAccountName=%v)(objectclass=user)) |
userIdMap | string | user:sAMAccountName |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=dominoGroup)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | dominoGroup:member |
userFilter | string | (&(uid=%v)(objectclass=Person)) |
userIdMap | string | person:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)((objectclass=groupOfNames)(objectclass=groupOfUniqueNames))) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | groupOfNames:member;groupOfUniqueNames:uniqueMember |
userFilter | string | (&(uid=%v)(objectclass=ePerson)) |
userIdMap | string | *:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=ldapsubentry)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | nsRole:nsRole |
userFilter | string | (&(uid=%v)(objectclass=inetOrgPerson)) |
userIdMap | string | inetOrgPerson:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)((objectclass=groupOfNames)(objectclass=groupOfUniqueNames))) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | groupOfNames:member;groupOfUniqueNames:uniqueMember |
userFilter | string | (&(uid=%v)(objectclass=inetOrgPerson)) |
userIdMap | string | inetOrgPerson:uid |
Attribute name | Data type | Default value |
---|---|---|
groupFilter | string | (&(cn=%v)(objectclass=groupOfNames)) |
groupIdMap | string | *:cn |
groupMemberIdMap | string | groupOfNames:member |
userFilter | string | (&(cn=%v)(objectclass=Person)) |
userIdMap | string | person:cn |