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