Client Certificate Authentication Example¶

This section describes how to configure client certificate authentication in Driverless AI.

Client Certificate and SSL Configuration Options¶

The following options can be specified when configuring client certificate authentication.

SSL Configuration Options¶

Mutual TLS authentication (mTLS) must be enabled in order to enable Client Certificate Authentication. Use the following configuration options to configure mTLS. Refer to the mTLS Authentication topic for more information on how to enable mTLS.

ssl_client_verify_mode: Sets the client verification mode. Choose from the following verification modes:

CERT_NONE: The client will not need to provide a certificate. If it does provide a certificate, any resulting verification errors are ignored.

CERT_OPTIONAL: The client does not need to provide a certificate. If it does provide a certificate, it is verified against the configured CA chains.

CERT_REQUIRED: The client needs to provide a certificate for verification. Note that you will need to configure the ssl_client_key_file and ssl_client_crt_file options when this mode is selected in order for Driverless to be able to verify it’s own callback requests.

ssl_ca_file: Specifies the path to the certification authority (CA) certificate file. This certificate will be used to verify the client certificate when client authentication is enabled. If this is not specified, clients are verified using the default system certificates.
ssl_client_key_file: Required if ssl_client_verify_mode = "CERT_REQUIRED". Specifies the HTTPS settings path to the private key that Driverless AI uses to authenticate itself.
ssl_client_crt_file: Required if ssl_client_verify_mode = "CERT_REQUIRED". Specifies the HTTPS settings path to the client certificate that Driverless AI will use to authenticate itself.

Client Certificate Options¶

auth_tls_crl_file: The path to the certificate revocation list (CRL) file that is used to verify the client certificate.
auth_tls_user_lookup: Specifies how a user’s identity is obtained. Choose from the following:
- REGEXP_ONLY: Uses auth_tls_subject_field and auth_tls_field_parse_regexp to extract the username from the client certificate.
- LDAP_LOOKUP: Uses the LDAP server to obtain the username. (Refer to the LDAP Authentication Example section for information about additional LDAP Authentication configuration options.)

Used with LDAP_LOOKUP:

auth_tls_ldap_server: Specifies the LDAP server hostname or IP address.
auth_tls_ldap_port: Specifies the LDAP server port number. This is 389 by default.
auth_tls_ldap_use_ssl: Specifies whether to enable (True) or disable (False) SSL when connecting to the LDAP server.
auth_tls_ldap_tls_file: Specifies the path to the SSL certificate.
auth_tls_ldap_bind_dn: Specifies the complete DN of the LDAP bind user.
auth_tls_ldap_bind_password: Specifies the password for the LDAP bind.
auth_tls_subject_field: The subject field that is used as a source for a username or other values that provide further validation.
auth_tls_field_parse_regexp: The regular expression that is used to parse the subject field in order to obtain the username or other values that provide further validation.
auth_tls_ldap_search_base: Specifies the location in the Directory Information Tree (DIT) where the search will start.
auth_tls_ldap_search_filter: Specifies an LDAP search filter that is used to find a specific user with LDAP_LOOKUP when using the tls_certificate authentication method. This can be dynamically built by using the named capturing groups from auth_tls_field_parse_regexp for substitution:
auth_tls_field_parse_regexp = "\w+ (?P<id>\d+)" auth_tls_ldap_search_filter = "(&(objectClass=person)(id={{id}}))
auth_tls_ldap_username_attribute: Specifies the LDAP record attribute that is used as a username.
auth_tls_ldap_authorization_lookup_filter: (Optional) Specifies an additional search filter that is performed after the user is found. This is useful for checking whether a user is a member of a specific group in LDAP schemas where group membership is defined within group entries as opposed to individual user entries. (Refer to the Lookup Filter Example section that follows to see an example of how this option can be used.)
auth_tls_ldap_authorization_search_base: Specifies the base distinguished name (DN) to start the authorization lookup from. Required when auth_tls_ldap_authorization_lookup_filter is specified.

Lookup Filter Example¶

The following example uses the auth_tls_ldap_authorization_lookup_filter option to determine whether individual users are members of the chemists group in an LDAP schema where group (organizational unit) membership is defined within group entries.

# Specify to use email as username
auth_tls_ldap_username_attribute = "mail"
# Specify search string
auth_tls_ldap_search_filter = "(&(objectClass=inetOrgPerson)(uid={{username}}))"
# Specify the base DN to start the search from
auth_tls_ldap_authorization_search_base="dc=example,dc=com"
# Filter the results of the search to determine which users are members of a specific group
auth_tls_ldap_authorization_lookup_filter = "(&(objectClass=groupOfUniqueNames)(uniqueMember=uid={{uid}},dc=example,dc=com)(ou=chemists))"

Enabling Client Certificate Authentication¶

To enable Client Certificate authentication in Docker images, specify the authentication environment variable that you want to use. Each variable must be prepended with DRIVERLESS_AI_. The following example enables Client Certification authentication and uses LDAP_LOOKUP for the TLS user lookup method.

     nvidia-docker run \
       --pid=host \
       --rm \
       --shm-size=2g --cap-add=SYS_NICE --ulimit nofile=131071:131071 --ulimit nproc=16384:16384 \
       -p 12345:12345 \
       -u `id -u`:`id -g` \
       -e DRIVERLESS_AI_ENABLED_FILE_SYSTEMS="file,s3,hdfs" \
       -e DRIVERLESS_AI_ENABLE_HTTPS="true" \
       -e DRIVERLESS_AI_SSL_KEY_FILE="/etc/pki/dai-server.key" \
       -e DRIVERLESS_AI_SSL_CRT_FILE="/etc/pki/dai-server.crt" \
       -e DRIVERLESS_AI_SSL_CA_FILE="/etc/pki/ca.crt" \
       -e DRIVERLESS_AI_SSL_CLIENT_VERIFY_MODE="CERT_REQUIRED" \
       -e DRIVERLESS_AI_SSL_CLIENT_KEY_FILE="/etc/pki/dai-self.key" \
       -e DRIVERLESS_AI_SSL_CLIENT_CRT_FILE="/etc/pki/dai-self.cert" \
       -e DRIVERLESS_AI_AUTHENTICATION_METHOD="tls_certificate" \
       -e DRIVERLESS_AI_AUTH_TLS_SUBJECT_FIELD="CN" \
       -e DRIVERLESS_AI_AUTH_TLS_CRL_FILE="/etc/pki/crl.pem" \
       -e DRIVERLESS_AI_AUTH_TLS_FIELD_PARS_REGEXP="(?P<di>.*)" \
       -e DRIVERLESS_AI_AUTH_TLS_USER_LOOKUP="LDAP_LOOKUP" \
       -e DRIVERLESS_AI_LDAP_SERVER="ldap.forumsys.com" \
       -e DRIVERLESS_AI_LDAP_BIND_DN="cn=read-only-admin,dc=example,dc=com" \
       -e DRIVERLESS_AI_LDAP_BIND_PASSWORD="password" \
       -e DRIVERLESS_AI_LDAP_SEARCH_BASE="dc=example,dc=com" \
       -e DRIVERLESS_AI_LDAP_USER_NAME_ATTRIBUTE="uid" \
       -e DRIVERLESS_AI_LDAP_SEARCH_FILTER="(&(objectClass=inetOrgPerson)(uid={{id}}))" \
       -e DRIVERLESS_AI_AUTH_TLS_LDAP_AUTHORIZATION_SEARCH_BASE="dc=example,dc=com" \
       -e DRIVERLESS_AI_AUTH_TLS_LDAP_AUTHORIZATION_LOOKUP_FILTER="(&(objectClass=groupOfUniqueNames)(uniqueMember=uid={{uid}},dc=example,dc=com)(ou=chemists))" \
       -v `pwd`/data:/data \
       -v `pwd`/log:/log \
       -v `pwd`/license:/license \
       -v `pwd`/tmp:/tmp \
       h2oai/dai-ubi8-x86_64:1.11.1-cuda11.8.0.xx

Native installs include DEBs, RPMs, and TAR SH installs. The following example shows how to edit the config.toml file to enable Client Certification authentication and uses the LDAP_LOOKUP for the TLS user lookup method.

Export the Driverless AI config.toml file or add it to ~/.bashrc. For example:

# DEB and RPM
export DRIVERLESS_AI_CONFIG_FILE="/etc/dai/config.toml"

# TAR SH
export DRIVERLESS_AI_CONFIG_FILE="/path/to/your/unpacked/dai/directory/config.toml"

Open the config.toml file and edit the following authentication variables. The config.toml file is available in the etc/dai folder after Driverless AI is installed.

# https settings
enable_https = true

# https settings
# Path to the SSL key file
#
ssl_key_file = "/etc/pki/dai-server.key"

# https settings
# Path to the SSL certificate file
#
ssl_crt_file = "/etc/pki/dai-server.crt"

# https settings
# Path to the Certification Authority certificate file. This certificate will be
# used when to verify client certificate when client authentication is turned on.
# If this is not set, clients are verified using default system certificates.
#
ssl_ca_file = "/etc/pki/ca.crt"

# https settings
# Sets the client verification mode.
# CERT_NONE: Client does not need to provide the certificate and if it does any
# verification errors are ignored.
# CERT_OPTIONAL: Client does not need to provide the certificate and if it does
# certificate is verified agains set up CA chains.
# CERT_REQUIRED: Client needs to provide a certificate and certificate is
# verified.
# You'll need to set 'ssl_client_key_file' and 'ssl_client_crt_file'
# When this mode is selected for Driverless to be able to verify
# it's own callback requests.
#
ssl_client_verify_mode = "CERT_REQUIRED"

# https settings
# Path to the private key that Driverless will use to authenticate itself when
# CERT_REQUIRED mode is set.
#
ssl_client_key_file = "/etc/pki/dai-self.key"

# https settings
# Path to the client certificate that Driverless will use to authenticate itself
# when CERT_REQUIRED mode is set.
#
ssl_client_crt_file = "/etc/pki/dai-self.crt"

# Enable client certificate authentication
authentication_method = "tls_certificate"

# Subject field that is used as a source for a username or other values that provide further validation
auth_tls_subject_field = "CN"

# Path to the CRL file that will be used to verify client certificate.
auth_tls_crl_file = "/etc/pki/crl.pem"

# Sets up the way how user identity would be obtained
# REGEXP_ONLY: Will use 'auth_tls_subject_field' and 'auth_tls_field_parse_regexp'
# to extract the username from the client certificate.
# LDAP_LOOKUP: Will use LDAP server to lookup for the username.
# 'ldap_server', 'ldap_use_ssl', 'ldap_tls_file', 'ldap_bind_dn',
# 'ldap_bind_password' options are used to establish
# the connection with the LDAP server.
# 'auth_tls_subject_field' and 'auth_tls_field_parse_regexp'
# options are used to parse the certificate.
# 'ldap_search_base', 'ldap_search_filter', and
# 'ldap_username_attribute' options are used to do the lookup.
# 'ldap_search_filter' can be built dynamically using the named
# capturing groups from the 'auth_tls_field_parse_regexp' for
# substitution.
# Example:
# auth_tls_field_parse_regexp = "\w+ (?P<id>\d+)"
# ldap_search_filter = "(&(objectClass=person)(id={{id}}))"
auth_tls_user_lookup = "LDAP_LOOKUP"

# Regular expression that is used to parse the subject field in order to
# obtain the username or other values that provide further validation
auth_tls_field_parse_regexp = "\w+ (?P<id>\d+)"

# ldap server domain or ip
ldap_server = "ldap.forumsys.com"

# Complete DN of the LDAP bind user
ldap_bind_dn = "cn=read-only-admin,dc=example,dc=com"

# Password for the LDAP bind
ldap_bind_password = "password"

# the location in the DIT where the search will start
ldap_search_base = "dc=example,dc=com"

# specify key to find user name
ldap_user_name_attribute = "uid"

# A string that describes what you are searching for. You can use Python
# substitution to have this constructed dynamically.
# (only {{DAI_USERNAME}} is supported)
ldap_search_filter = "(&(objectClass=inetOrgPerson)(uid={{id}}))"

# Base DN where to start the Authorization lookup. Used when
# 'auth_tls_ldap_authorization_lookup_filter' is set.
auth_tls_ldap_authorization_search_base="dc=example,dc=com"

# Sets optional additional lookup filter that is performed after the
# user is found. This can be used for example to check whether the is member of
# particular group.
# Filter can be built dynamically from the attributes returned by the lookup.
# Authorization fails when search does not return any entry. If one ore more
# entries are returned authorization succeeds.
# Example:
# auth_tls_field_parse_regexp = "\w+ (?P<id>\d+)"
# ldap_search_filter = "(&(objectClass=person)(id={{id}}))"
# auth_tls_ldap_authorization_lookup_filter = "(&(objectClass=group)(member=uid={{uid}},dc=example,dc=com))"
# If this option is empty no additional lookup is done and just a successful user
# lookup is enough to authorize the user.
#
auth_tls_ldap_authorization_lookup_filter = "(&(objectClass=groupOfUniqueNames)(uniqueMember=uid={{uid}},dc=example,dc=com)(ou=chemists))"

Start (or restart) Driverless AI.