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

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

    nvidia-docker run \
                --pid=host \
                --init \
                --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_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-ubi8-x86_64:1.11.0-cuda11.8.0.xx

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.