lastupdated: "2024-09-25"

Configuring mutual TLS authentication between IM and LDAP server

From foundational services version 4.9, you can enable mutual TLS authentication between Identity Management (IM) and LDAP server when you configure LDAP connection based on the backend LDAP registry configuration. You need to configure TLS/SSL to enable mutual authentication.

To enable mutual TLS authentication for LDAP server, you need to add the ldap_tls_verify_client parameter in the IdP V3 API when you create LDAP connection. The values of the ldap_tls_verify_client parameter are try and demand.

Note: It is not recommended to configure a non-mutual TLS LDAP server as a mutual TLS LDAP connection on the IM side.

You can configure mutual TLS authentication using IdP v3 API with one of the following methods:

Mutual TLS configuration for LDAP servers
Configuring mutual TLS authentication with try mTLS SSL profile
Configuring mutual TLS authentication with demand mTLS SSL profile
- Configuring demand mTLS SSL with default IM certificates
- Configuring demand mTLS SSL with custom certificates

Mutual TLS configuration for LDAP servers

You configure mutual TLS for the following LDAP servers:

PingDirectory
SDS (Secure Data Store) or ISVD (Identity and Access Management for Virtual Desktop) LDAP
OpenLDAP

Configuring mutual TLS for PingDirectory

You can use try mTLS SSL method to configure mutual TLS for PingDirectory. Complete the following steps:

Set ssl-client-auth-policy to optional on the PingDirectory server.
Configure the IdP configuration with the try mTLS SSL method on the foundational services side.

The following is the sample curl command:
Set the use-ssl and allow-start-tls parameters to true and false. You need to enable the connection handler to configure LDAP support.

For more information on try mTLS SSL method, see Configuring mutual TLS authentication with try mTLS SSL profile.

Configuring mutual TLS for SDS (Secure Data Store) or ISVD (Identity and Access Management for Virtual Desktop)

ISVD LDAP server does not support Try mutual TLS method. You can use demand mutual TLS method for ISVD (Server and client authentication method). If the client presents a null size certificate to the LDAP server, an error is shown and the handshake is rejected.

To configure mutual TLS for SDS or ISVD LDAP, see Setting server client mTLS communication in SDS/ISVD LDAP.

For more information on try mTLS SSL method, see Configuring mutual TLS authentication with try mTLS SSL profile.

Configuring mutual TLS for openLDAP

You can use try mTLS SSL or demand mTLS SSL method to configure mutual TLS for openLDAP server.

Set the LDAP_TLS_VERIFY_CLIENT environment variable with try or demand to enable mutual TLS when you create a server on the openLDAP.

--env LDAP_TLS_VERIFY_CLIENT=try/demand

For more information on try mTLS SSL and demand mTLS SSL methods, see Configuring mutual TLS authentication with try mTLS SSL profile and Configuring mutual TLS authentication with demand mTLS SSL profile.

Configuring mutual TLS authentication with `try mTLS SSL` profile

Specify the ldap_tls_verify_client parameter with try to enable mutual TLS authentication with try mTLS SSL profile when you create the LDAP connection. You can use try mTLS SSL profile for LDAP connection when the import of an IM client certificate is not required in the LDAP server. If you enable try mTLS SSL profile, IM prevents the passing of the client certificate for the LDAP mutual TLS/SSL authentication.

The following curl command is an example to create LDAP connection with try mTLS SSL profile:

$ export ACCESS_TOKEN= $BEARER-TOKEN
$ export CP_CONSOLE_URL=$CP_CONSOLE_URL_ROUTE
$ curl -k -X POST \
   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
   -H "content-type: application/json" \
   "https://${CP_CONSOLE_URL}/idprovider/v3/auth/idsource" \
   -d '{
      "name": "openLDAP",
      "description": "description 1",
       "protocol": "ldap",
       "type": "Custom",
       "idp_config": {
         "ldap_url": "ldaps://ldaps.example.com:636",
         "ldap_basedn": "dc=ibm,dc=com",
         "ldap_bindpassword": "<base64 encoded password>",
         "ldap_binddn": "cn=admin,dc=ibm,dc=com",
         "ldap_userfilter": "(&(uid=%v)(objectclass=person))",
         "ldap_groupfilter": "(&(cn=%v)(objectclass=groupOfUniqueNames))",
         "ldap_useridmap": "*:uid",
         "ldap_groupidmap": "*:cn",
         "ldap_groupmemberidmap": "groupOfUniqueNames:uniquemember",
         "ldap_tls_verify_client":"try"
       }
}'

Ensure that you specify the base64-encoded password in the ldap_bindpassword parameter.

Configuring mutual TLS authentication with `demand mTLS SSL` profile

Specify the ldap_tls_verify_client parameter with demand to enable mutual TLS authentication with demand mTLS SSL profile when you create the LDAP connection. If you set the ldap_tls_verify_client parameter with demand, the LDAP server requests the CA certificate from IM, and a valid certificate need to be provided for TLS authentication. If the certificate is invalid, the session stops immediately.

You can configure the demand mTLS SSL with one of the following methods:

Configuring demand mTLS SSL with default IM certificates
Configuring demand mTLS SSL with custom certificates

Configuring `demand mTLS SSL` with default IM certificates

You must obtain a certificate authority (CA) certificate of IM and import it to the truststore of the LDAP server to enable mutual TLS authentication with demand mTLS SSL profile.

Complete the following steps to enable mutual TLS authentication with demand mTLS SSL profile:

Get the CA certificate of IM with the following command:

oc get secret identity-provider-secret -o jsonpath='{.data.ca\.crt}' | base64 –decode

Import the CA certificate of IM in the PEM format to the truststore of the LDAP server. Contact your LDAP team to upload the CA certificate to the truststore of your LDAP server.

Set the ldap_tls_verify_client parameter with demand when you create the LDAP connection.

The following curl command is an example to create LDAP connection with demand mTLS SSL profile:

$ export ACCESS_TOKEN= $BEARER-TOKEN
$ export CP_CONSOLE_URL=$CP_CONSOLE_URL_ROUTE
$ curl -k -X POST \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "content-type: application/json" \
    "https://${CP_CONSOLE_URL}/idprovider/v3/auth/idsource" \
    -d '{
        "name": "openLDAP",
        "description": "description 1",
        "protocol": "ldap",
        "type": "Custom",
        "idp_config": {
            "ldap_url": "ldaps://ldaps.example.com:636",
            "ldap_basedn": "dc=ibm,dc=com",
            "ldap_bindpassword": "<base64 encoded password>",
            "ldap_binddn": "cn=admin,dc=ibm,dc=com",
            "ldap_userfilter": "(&(uid=%v)(objectclass=person))",
            "ldap_groupfilter": "(&(cn=%v)(objectclass=groupOfUniqueNames))",
            "ldap_useridmap": "*:uid",
            "ldap_groupidmap": "*:cn",
            "ldap_groupmemberidmap": "groupOfUniqueNames:uniquemember",
            "ldap_tls_verify_client":"demand"

        }
}'

Configuring `demand mTLS SSL` with custom certificates

You can provide the CA bundle (CA key and certificate pair) of the LDAP server when you create LDAP connection to configure mutual TLS authentication with custom certificates. Ensure that you specify the CA key and certificate pair of the LDAP server in the ldap_tls_client_key and ldap_tls_client_cert parameters.

Note: Contact your LDAP admin to get the ldap_tls_client_key and ldap_tls_client_cert details parameters.