## Introduction

OpenID Connect (OIDC) allows Kubernetes users to authenticate using an external identity provider instead of static certificates or manually managed credentials.

With OIDC authentication, you can log into your clusters managed by Syself Autopilot using existing organizational accounts while Kubernetes delegates authentication to a trusted identity provider.

This approach simplifies access management and improves security for production Kubernetes environments.

## Choosing an OIDC provider

Before configuring Kubernetes OIDC authentication, you need an identity provider that supports OpenID Connect.

Common options include:

- Microsoft Entra ID (Azure AD)
- Google Workspace
- Keycloak
- Okta
- Authentik

For self-hosted environments, Syself commonly recommends [Authentik](https://goauthentik.io/). It provides OpenID Connect support, user management, group synchronization, and Single Sign-On capabilities in a modern self-hosted platform.

The identity provider is responsible for authenticating users and issuing the tokens Kubernetes uses for authentication and authorization.

## Implementing OIDC Authentication

To enable OIDC authentication and authorization for your cluster, you need to set a couple of flags in the Kubernetes' API Server.

To do this, set the variables below under `spec.topology.variables` in your Cluster resource:

```yaml
- name: oidcIssuerUrl
  value: https://your.oidc-issuer.com
- name: oidcClientID
  value: 123456789098765432@cluster-1
- name: oidcUsernameClaim
  value: sub
```

## Create and bind roles

You are now ready to configure Cluster Roles. Below is a sample role providing read-write access to pods and services:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: my-role
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
```

And bind this role to a group in your OIDC provider:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cluster-admins-binding
subjects:
  - kind: Group
    name: my-group
roleRef:
  kind: ClusterRole
  name: my-role
  apiGroup: rbac.authorization.k8s.io
```

## Accessing the cluster

Kubernetes does not automatically perform browser-based OIDC authentication for clients, such as kubectl.

To simplify the authentication flow, we recommend using `kubelogin`, which handles token retrieval and automatically refreshes credentials when needed.

You can use one of the following commands to install `kubelogin`

{% tabs #package-managers %}

{% tab title="Krew" %}

```shell
/// macOS, Linux, Windows, and ARM
kubectl krew install oidc-login
```

{% /tab %}

{% tab title="Chocolatey" %}

```shell
/// Windows
choco install kubelogin
```

{% /tab %}

{% /tabs %}

Alternatively, you can install it from a Github release. Then you need to make sure that it is in your path as `kubectl-oidc_login`.

Now you need to change your `kubeconfig` file to authenticate using it `kubelogin`. Add the snippet below to it:

```yaml
users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://your.oidc-issuer.com
          - --oidc-client-id=123456789098765432@cluster-1
        command: kubectl
```

The next time you run `kubectl` you'll be prompted to authenticate with your OIDC provider.

## Need help integrating OIDC into your environment?

Designing Kubernetes authentication and RBAC strategies can become complex, especially in multi-team or production environments.

The Syself team can help with:

- Kubernetes SSO integration
- OIDC provider selection
- RBAC design and hardening
- Multi-cluster authentication
- Authentik deployments
- Enterprise Kubernetes access management

If you want help integrating OIDC into your Kubernetes environment, [contact the Syself team](/demo).