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_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_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.)

  • auth_tls_ldap_authorization_lookup_filter: (Optional) Specifies an additional search filter that is performed after the user is found. For example, this can be used to check whether that user is a member of a particular group.

  • auth_tls_ldap_authorization_search_base: Specifies the base DN to start the authorization lookup from. Used when the above option is specified.

Enabling Client Certificate Authentication in Docker Images

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 example below enables Client Certification authentication and uses LDAP_LOOKUP for the TLS user lookup method. Replace TAG below with the image tag.

nvidia-docker run \
  --pid=host \
  --init \
  --rm \
  --shm-size=256m \
  -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-centos7-x86_64:TAG

Enabling Client Certificate Authentication in the config.toml File for Native Installs

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

  1. 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"
  1. 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))"
  1. Start (or restart) Driverless AI.