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 new 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 use the set parameter to configure properties for your cluster.

Creating a Cluster

To create an 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 parameters 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 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 parameters 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 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.

Configuring User-Based Authorizations

Setting a kubeconfig Environment Variable

For the next commands, set a environment variable to print the kubeconfig file.

To set the KUBECONFIG variable, run the following command:

Request sample

$ 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

To grant rights to users using the OIDC provider, you must define role-based authorizations.

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

Request sample

$ kubectl --kubeconfig $KUBECONFIG auth whoami

Response sample

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

To give the cluster-admin role to an email address used to log in to GitLab, use the kubectl create clusterrolebinding command:

Rolebinding sample

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

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

kubeconfig: The path to the kubeconfig file to use for CLI requests.
clusterrole: The ClusterRole that this ClusterRoleBinding should reference.
user: The usernames to bind to the ClusterRole. This option can be repeated to add multiple users.

You can use an username prefix such as oidc: in front of the email address. This can be modified through the cluster or through the kubeconfig file.

Enabling OIDC Authentication for kubectl

To enable OIDC Authentication for kubectl, use kubectl config set-credentials 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

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

kubeconfig file sample

...
users:
- name: cluster-admin
  user:
    client-certificate-data: CERT_ITSELF=
    client-key-data: CERT_KEY=
- 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 the Cluster

Set the context user to oidc or to cluster-admin to enforce OIDC identification when you log in to the cluster by using the kubectl config set-context command:

Request sample

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

This command contains the following options that you may 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 kubeconfig.

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

Request sample

$ kubectl get secrets -A

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

Sharing Access to Your Cluster

To share access to your cluster, you can share the current kubeconfig file after removing the users from it.

To delete users, 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

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
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: CLUSTER_CERT==
    server: https://test-133.123123123.project.eu-west-2.oks.outscale.com:6443
  name: test-133
contexts:
- context:
    cluster: test-133
    user: oidc
  name: oidc@test-133
current-context: oidc@test-133
kind: Config
preferences: {}
users:
- name: oidc
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=https://gitlab.mydomain.net
      - --oidc-client-id=123123123123123123123123123123123123123123123123
      - --oidc-extra-scope=email
      command: kubectl
      env: null
      interactiveMode: Never
      provideClusterInfo: false

Disabling OIDC Authentication

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

Request sample

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

Related Pages

Corresponding API Methods