Using OpenID Connect with Mirantis Kubernetes Engine 3.5.0

Many organizations use external identity providers like Google or Microsoft to manage authentication across their applications — and many may wish to bring this functionality to their cluster management, too. In the upcoming Mirantis Kubernetes Engine 3.5.0, we’ll introduced support for external OpenID Connect (OIDC) providers to help you do just that.

OIDC enables you to authenticate Mirantis Kubernetes Engine (MKE) users with a trusted
third-party login. Using ID tokens issued by your provider, it is now possible to authenticate to the MKE API as well as to Kubernetes clusters managed by MKE.

In this post, we’ll explore how you can get started using OIDC with Mirantis Kubernetes Engine. We’ll walk you through:

• Configuring an OIDC provider
• Signing in with an OIDC provider
• Accessing Kubernetes clusters with ID tokens
• Disabling an OIDC provider

Configuring an OpenID Connect identity provider

In order to configure external OIDC providers, you will need to use a TOML configuration file. As of MKE 3.5.0, there is a new configuration file section [auth.external_identity_provider] that at a minimum requires two parameters:

wellKnownConfigUrl = "https://example.com/.well-known/openid-configuration"
clientId = "client-id-from-your-provider"

However, we highly recommended that you also add a client secret:

clientSecret = "client-secret-from-your-provider"

Refer to MKE configuration file for complete reference documentation.

Signing in to Mirantis Kubernetes Engine with an OpenID Connect provider

After you have configured a provider a new 'Sign in with External Provider' button will appear on the login page:

After pressing this button, a user will be redirected to the provider login page, where they will need to enter credentials and/or consent to permissions. After that, they will be redirected back to MKE Dashboard.

It is also possible to access the MKE API directly with an ID token:

ID_TOKEN=<token_from_provider>
curl --insecure -X GET "https://<MKE_HOST>/id" \
-H "Authorization: Bearer $ID_TOKEN"

For new users, it is important to log in with an ID token at least once (either from the UI or through the API), so that the default role and collection are created and assigned to the user. With the API, you can do this as follows:

ID_TOKEN=<token_from_provider>
curl -X POST 'https://<MKE_HOST>/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "$ID_TOKEN"
}'

Accessing Kubernetes clusters with ID tokens

To access a Kubernetes cluster with kubectl, MKE users typically utilize client bundles. By default, a KUBECONFIG from a client bundle uses public and private key pairs for authorizing requests.

Therefore, Kubernetes users who want client bundles to use OIDC must replace the authorization section therein with the parameters described in the Kubernetes OIDC Authenticator documentation.

Note: While it is sometimes possible to retrieve user info from the UserInfo endpoint with OIDC, MKE only uses ID token claims. Thus, MKE does not use the UserInfo URL to obtain user information.

Disabling OpenID Connect provider

If you wish to remove an OpenID Connect provider for any reason, all you need to do is change your configuration file.

To disable the authentication with an external provider, simply remove the entire [auth.external_identity_provider] section from your TOML config file.

If you’d like to learn more about using external OIDC providers with Mirantis Kubernetes Engine, you can explore the documentation.