Driverless AI OpenID Connect Authentication

This page describes how to set up OpenID Connect (OIDC) authentication in Driverless AI (DAI).

Setting up OIDC authentication

To set up OIDC authentication locally (or in production), the following config.toml options must be specified:

  1. authentication_method = "oidc" - Specifies OIDC as the authentication method

  2. auth_oidc_issuer_url = "https://login.microsoftonline.com/<client_id>/v2.0" - Specifies the URL of the Identity Provider (IDP), which is also used for automatic provider discovery

  3. auth_oidc_identity_source = "id_token" - Specifies whether user identity is retrieved from ID Token or the UserInfo. The available options are ["userinfo", "id_token"]

  4. auth_oidc_username_claim = "preferred_username" - Specifies the Client ID (the application ID assigned to Driverless AI), which is provided by the IDP

  5. auth_openid_client_id = "<client_id>" - Specifies the Client ID, which is provided by the IDP

  6. auth_openid_client_secret = "<client_secret>" - Specifies the Client secret created or given by the IDP

  7. auth_openid_redirect_uri = "http://localhost:12345/oidc/callback" - Specifies a redirection URL so that the IDP can redirect users back to the application after successfully logging in

  8. auth_oidc_post_logout_url = "http://localhost:12345/login" - Specifies the URL the user is directed to after logging out

This basic setup should be sufficient to use an IDP such as Azure AD. However, there are additional configuration options that can be specified, which are needed, for example, when using MLOps / Remote Storage or if specific OIDC scopes are needed.

The following example contains several overrides in addition to the required config.toml options:

# AUTH
authentication_method = "oidc"
auth_oidc_id_token_username_key = "preferred_username"
auth_oidc_identity_source = "id_token"
auth_oidc_issuer_url = "https://login.microsoftonline.com/<client_id>/v2.0"
auth_openid_client_id = "<client_id>"
auth_openid_client_secret = "<client_secret>"
auth_openid_scope = "openid profile email User.Read"
auth_openid_default_scopes = "User.Read"
auth_openid_redirect_uri = "http://localhost:12345/oidc/callback"
auth_oidc_post_logout_url = "http://localhost:12345/login"

In the preceding example, notice the usage of the following OIDC scopes:

  1. auth_openid_scope - Specifies the list of scopes requested at the authorization request

  2. auth_openid_default_scopes - Specifies a set of scopes that are requested when making an access token request

How does OIDC authentication work?

The following sections describe how OIDC authentication is implemented in DAI.

Note

DAI only supports the Authorization Code Flow. As stated on the OpenID website, the Authorization Code Flow returns an Authorization Code to the Client, which can then exchange it for an ID Token and an Access Token directly.

Note

DAI mainly supports the client_secret_basic authentication method.

Identity sources

The DAI OIDC authentication mechanism allows two different methods of retrieving a user identity from IDP.

Note

For both of the following methods, the user must specify the auth_oidc_username_claim config.toml option, which controls which claim is used as a username in DAI.

  • userinfo: Makes a UserInfo endpoint request, which in response returns a set of claims that should contain the preferred username, which will be used as the DAI username.

  • id_token: Uses an ID Token introspection, which is typically acquired during the token exchange, to retrieve the claim holding the preferred username.

Identity Validation

Driverless AI allows two different methods of evaluating whether user (identity) has required privileges to access the DAI application. The validation step is performed after DAI retrieves the user identity from Identity Sources mentioned above.

  • If auth_openid_use_objectpath_match is enabled, then the user must specify auth_openid_use_objectpath_expression, which evaluates ObjectPath against identity (UserInfo response or ID Token)

  • If auth_openid_use_objectpath_match is disabled, then the user may specify auth_openid_userinfo_auth_key and auth_openid_userinfo_auth_value to compare value with given key in identity against the configured value.

Logging in using OIDC

The following steps describe the procedure of logging in using OIDC:

  1. The OIDC Client is initialized at server startup and performs Provider Discovery, which discovers all the Identity Provider (IDP) endpoints.

  2. When a user enters the login page, authorization code flow is initialized and the IDP is requested for an authorization code.

  3. The user is redirected to an OIDC callback URL, which processes the authorization response and retrieves the authorization code.

  4. The OIDC callback handler performs the token exchange using the Token Endpoint and acquires the Access and ID Tokens (and when possible, the Refresh Token).

  5. The responses are verified and validated.

  6. The OIDC callback handler then attempts to retrieve user identity from either UserInfo or ID Token.

  7. After user identity is retrieved, the OIDC callback handler logs the user in and starts a user session using the username acquired from identity.

Logging out

When a user logs out, a request for EndSessionEndpoint is constructed, which redirects the user to the IDP logout page. auth_oidc_post_logout_url needs to be specified in the config.toml file, which by design should point to the absolute DAI login URL.