Tutorial: Setting Up an OIDC Provider for Authentication

OKS supports OpenID Connect (OIDC) authentication of users via kubectl. You can configure your OKS cluster to enable the OIDC authentication protocol.

This authentication strategy is additional to the default certificate-based authentication used for OKS clusters. Certificate-based access is used in the initial steps to add role-based access control (RBAC) authorizations for users connected via OIDC.

This feature is available for OKS CLI versions 1.20 or above.

Preparing Your OIDC Provider

Before you begin:

Install the latest version of OKS CLI, and kubectl. For more information, see Installing and Configuring OKS CLI.
Install the kubelogin plugin.

In this example, we will be using GitLab as an OIDC identity provider.

On Gitlab, navigate to your applications: https://gitlab.<DOMAIN.NAME>/-/user_settings/applications.
Click Add new application to add an authentication provider.
A configuration section appears.
In the Name field, enter a name for your application.
In the Redirect URI field, enter http://localhost:8000, and disable the Confidential option.
In the Scopes list, select openid, profile, and email, then click Save application.

Your OIDC application is created, and GitLab displays its application ID and its secret.

Configuring OIDC for Your Cluster

To enable OIDC support and display usernames as email addresses rather than IDs, you need to define the properties of the OIDC application for your cluster by using the set option.

Creating a Cluster

To create a new cluster, use the cluster create command following this syntax:

Request sample

$ oks-cli cluster create \
  --cluster-name <NAME_OF_CLUSTER> \
  --set auth.oidc.client-id=<APPLICATION_ID> \
  --set auth.oidc.issuer-url=https://gitlab.<DOMAIN.NAME> \
  --set auth.oidc.username-claim=email

This command contains the following options that you need to specify:

cluster-name: The name of the cluster, with a maximum length of 40 alphanumeric characters and dashes (-). This name must start with a lowercase letter and must not end with a dash. It must be unique within the project.
set: Allows you to define properties.
- auth.oidc.client-id: The client ID provided by the OIDC provider. This will be used by the cluster to connect to the server.
- auth.oidc.issuer-url: The server URL of the OIDC provider, using the HTTPS protocol (https://).
- auth.oidc.username-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. By default, email. This will be used to retrieve the GitLab login email on the Kubernetes side.

The cluster now supports logging in with OIDC via https://gitlab.<DOMAIN.NAME>, in addition to certificate-based logins.

Updating a Cluster

To update an existing cluster, use the cluster update command following this syntax:

Request sample

$ oks-cli cluster update \
  --cluster-name <NAME_OF_CLUSTER> \
  --set auth.oidc.client-id=<APPLICATION_ID> \
  --set auth.oidc.issuer-url=https://gitlab.<DOMAIN.NAME> \
  --set auth.oidc.username-claim=email

This command contains the following options that you need to specify:

cluster-name: The name of the cluster that you want to update.
set: Allows you to define properties.
- auth.oidc.client-id: The client ID provided by the OIDC provider. This will be used by the cluster to connect to the server.
- auth.oidc.issuer-url: The server URL of the OIDC provider, using the HTTPS protocol (https://).
- auth.oidc.username-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. By default, email. This will be used to retrieve the GitLab login email on the Kubernetes side.

The cluster now supports logging in with OIDC via https://gitlab.<DOMAIN.NAME>, in addition to certificate-based logins.

Managing Accesses to Your Cluster

Setting the kubeconfig Environment Variable

To allow kubectl to authenticate and configure the cluster, you need to export the path to the kubeconfig file as an environment variable. To do so, use the export command following this syntax:

$ export KUBECONFIG=`oks-cli cluster kubeconfig \
  --cluster-name <NAME_OF_CLUSTER> \
  --print-path \
  --refresh`

The KUBECONFIG environment variable is set to be kept up-to-date.

Defining Access Roles for OKS Users

To give an access role to a login email address used for your OIDC provider, you must modify the kubeconfig file of your cluster. For more information about access management, see Managing Accesses For OKS Users.

You can check your current user on the OKS side by using the kubectl whoami command:

Request sample

$ kubectl --kubeconfig $KUBECONFIG auth whoami

Result sample

ATTRIBUTE                                           VALUE
Username                                            cluster-admin
Groups                                              [system:authenticated]
Extra: authentication.kubernetes.io/credential-id   [X509SHA256=6c6ba4b6bd76414bd84ccb02c394478aeb68c465b5ac58febb78d8941df5991f]

In this example, we will attribute the default cluster-admin role to a user, using a ClusterRoleBinding. This resource grants the permissions defined in a role to a user or set of users. To do so, use the kubectl create clusterrolebinding command:

CLusterRoleBinding sample

$ kubectl --kubeconfig $KUBECONFIG create clusterrolebinding oidc-cluster-admin \
  --clusterrole=cluster-admin \
  --user='oidc:<EMAIL_ADDRESS>'

This command contains the following options that you need to specify:

kubeconfig: The path to the kubeconfig file to use for CLI requests.
clusterrole: The role that this ClusterRoleBinding should reference.
user: The usernames to bind to the ClusterRole. Here, we will add the oidc: prefix so that we can use it later when configuring kubectl. This option can be repeated to add multiple users.

A prefix can be modified through the cluster or through the kubeconfig file.

Allowing Access for Other Users

To allow all users of your OIDC provider to access your cluster, you need to modify its kubeconfig file to remove OKS users.

To delete OKS users from the kubeconfig file, use kubectl config delete-user with the following syntax:

Request sample

$ kubectl --kubeconfig $KUBECONFIG config delete-user cluster-admin

Result sample

deleted user cluster-admin from $KUBECONFIG

You can now share this kubeconfig file to allow users to access your cluster.

With shared access, every user must authenticate through the OIDC provider and will have access rights defined by RBAC.

Request sample: Printing the Shareable kubeconfig File

$ cat $KUBECONFIG

Result Sample

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: CLUSTER_CERTIFICATE==
    server: https://example-domain.123123123.project.eu-west-2.oks.outscale.com:6443
  name: NAME_OF_CLUSTER
contexts:
- context:
    cluster: NAME_OF_CLUSTER
    user: cluster-admin
  name: cluster-admin@NAME_OF_CLUSTER
current-context: cluster-admin@NAME_OF_CLUSTER
kind: Config
preferences: {}
users:
- name: oidc
  user: {}

Enabling OIDC Authentication With kubectl

To enable OIDC Authentication, use the kubectl config set-credentials command with the following syntax:

Request sample

$ kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=Never \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg="--oidc-issuer-url=https://gitlab.<DOMAIN.NAME> " \
  --exec-arg="--oidc-client-id=<APPLICATION_ID>" \
  --exec-arg="--oidc-extra-scope=email" --kubeconfig=$KUBECONFIG

Result sample

User "oidc" set.

The following elements are added to the users section of the kubeconfig file.

kubeconfig file sample

users:
- name: oidc
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=https://gitlab.<DOMAIN.NAME>
      - --oidc-client-id=<APPLICATION_ID>
      - --oidc-extra-scope=email
      command: kubectl
      env: null
      interactiveMode: Never
      provideClusterInfo: false
...

Enforcing OIDC Identification When Logging In to Your Cluster

To enforce OIDC identification when you log in to the cluster, you need to set the context user. Use the kubectl config set-context command with the previously added user prefix (oidc:):

Request sample

$ kubectl --kubeconfig $KUBECONFIG config set-context \
  --current \
  --user=oidc

This command contains the following options that you need to specify:

kubeconfig: The path to the kubeconfig file to use for CLI requests.
current: Allows you to modify the current context.
user: The user for the context entry in the kubeconfig file.

You can test the updated configuration by using the kubectl get secrets command:

Request sample

$ kubectl get secrets -A

Your browser opens on the login page of your OIDC provider. Once logged in, you will be able to access the list of your cluster’s secrets.

Disabling OIDC Authentication for Your Cluster

To disable OIDC authentication for your cluster, use the cluster update command following this syntax:

Request sample

$ oks-cli cluster update \
  --cluster-name <NAME_OF_CLUSTER> \
  --set auth={}

Related Pages

Corresponding API Methods