mTLS Authentication Example

Driverless AI supports Mutual TLS authentication (mTLS) by setting a specific verification mode along with a certificate authority file, an SSL private key, and an SSL certificate file. The diagram below is a visual representation of the mTLS authentication process.

mTLS Authentication

Description of Configuration Attributes

Use the following configuration options to configure 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, provided by your organization. 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_key_file: Specifies your web server private key file. This is normally created by your organization’s sys admin.

  • ssl_crt_file: Specifies your web server public certificate file. This is normally created by your organization’s sys admin.

  • ssl_client_key_file: Required if ssl_client_verify_mode = "CERT_REQUIRED". Specifies the private key file that Driverless AI uses to authenticate itself. This is normally created by your organization’s sys admin.

  • ssl_client_crt_file: Required if ssl_client_verify_mode = "CERT_REQUIRED". Specifies the private client certificate file that Driverless AI will use to authenticate itself. This is normally created by your organization’s sys admin.

  • auth_tls_crl_file: Specifies the path to the certificate revocation list file that will be used to verify the client certificate. This file contains a list of revoked user IDs.

Configuration Scenarios

The table below describes user certificate behavior for mTLS authentication based on combinations of the configuration options described above.

config.toml settings

User does not have a certificate

User has a correct and valid certificate

User has a revoked certificate

ssl_client_verify_mode='CERT_NONE'

User certs are ignored

User certs are ignored

User revoked certs are ignored

ssl_client_verify_mode='CERT_OPTIONAL'

User certs are ignored

User certs are set to Driverless AI but are not used for validating the certs

User revoked certs are not validated

ssl_client_verify_mode='CERT_REQUIRED'

Not allowed

User provides a valid certificate used by Driverless AI but does not authenticate the user

User revoke lists are not validated

sl_client_verify_mode='CERT_REQUIRED'

AND

authentication_method='tls_authentication'

Not allowed

User provides a valid certificate. The certificate is used for connecting to the Driverless AI server as well as for authentication.

User revoked certs are validated and the revoked file is provided in AUTH_TLS_CRL_FILE

Enabling mTLS Authentication in Docker Images

To enable mTLS authentication in Docker images, specify the authentication environment variable that you want to use. Each variable must be prepended with DRIVERLESS_AI_. 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_ENABLE_HTTPS=true \
  -e DRIVERLESS_AI_SSL_KEY_FILE=/etc/dai/private_key.pem \
  -e DRIVERLESS_AI_SSL_CRT_FILE=/etc/dai/cert.pem \
  -e DRIVERLESS_AI_AUTHENTICATION_METHOD=tls_certificate \
  -e DRIVERLESS_AI_SSL_CLIENT_VERIFY_MODE=CERT_REQUIRED \
  -e DRIVERLESS_AI_SSL_CA_FILE=/etc/dai/rootCA.pem \
  -e DRIVERLESS_AI_SSL_CLIENT_KEY_FILE=/etc/dai/client_config_key.key \
  -e DRIVERLESS_AI_SSL_CLIENT_CRT_FILE=/etc/dai/client_config_cert.pem \
  -v /user/log:/log \
  -v /user/tmp:/tmp \
  -v /user/certificates/server_config_key.pem:/etc/dai/private_key.pem \
  -v /user/certificates/server_config_cert.pem:/etc/dai/cert.pem \
  -v /user/certificates/client_config_cert.pem:/etc/dai/client_config_cert.pem \
  -v /user/certificates/client_config_key.key:/etc/dai/client_config_key.key \
  -v /user/certificates/rootCA.pem:/etc/dai/rootCA.pem \
  h2oai/dai-centos7-x86_64:TAG

Note: When certificate verification is required, use the Docker parameter --hostname to ensure that the certificate hostname is resolvable from within the Docker container to the container’s IP address.

Enabling mTLS 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 mTLS authentication.

  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.

# 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"

# 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"

# 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"

# 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"

  1. Start (or restart) Driverless AI.