# Self-Hosting Keycloak as an Identity Provider

> Octelium documentation. Canonical page: <https://octelium.com/docs/octelium/latest/management/guide/service/homelab/keycloak-helm-self-host>.

This is a quick guide on how to deploy [Keycloak](https://www.keycloak.org/), an open source, self-hosted identity provider (IdP) on the same underlying Kubernetes cluster that is running the Octelium *Cluster* and use it as an OpenID Connect *IdentityProvider* (read more about *IdentityProviders* [here](https://octelium.com/docs/octelium/latest/management/core/identity-providers.md)) to be able to login to the *Cluster*.

In this guide we use [Helm](https://helm.sh/) to install Keycloak. First, we need to create a `values.yaml` YAML file for the Keycloak Helm chart (see the chart [here](https://github.com/bitnami/charts/tree/main/bitnami/keycloak)) as follows:

```yaml
auth:
  adminPassword: <YOUR_PASSWORD>
extraStartupArgs: "--proxy-headers=forwarded --http-enabled=true --hostname=https://idp.<DOMAIN> --hostname-debug=true"
```

Now deploy Keycloak on the Kubernetes cluster using our `values.yaml` file as follows:

```bash
helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak -f </PATH/TO/VALUES.YAML> --set image.repository=bitnamilegacy/keycloak --set global.security.allowInsecureImages=true --set postgresql.image.repository=bitnamilegacy/postgresql --namespace keycloak --create-namespace --version 25.2.0
```

> **Note:**
>
> If you installed the *Cluster* via the quick installation guide, you can simply use the command `export KUBECONFIG="/etc/rancher/k3s/k3s.yaml"` in your *Cluster* VM/VPS before running the helm commands above.

Now create an Octelium *Service* for the Keycloak web server as follows:

```yaml
kind: Service
metadata:
  name: idp
spec:
  mode: HTTP
  config:
    upstream:
      url: http://keycloak.keycloak.svc
    http:
      header:
        forwardedMode: TRANSPARENT
        host:
          preserve: true
  isPublic: true
  isAnonymous: true
```

Now you can apply the creation of the *Service* via the `octeliumctl apply` command (read more [here](https://octelium.com/docs/octelium/latest/management/core/overview.md)) as follows:

```bash
octeliumctl apply /PATH/TO/SERVICE.YAML
```

> **Note:**
>
> Notice that we created the *Service* as `isAnonymous` since we need to access it anonymously in order to login to the *Cluster*. You can read more about anonymous *Services* [here](https://octelium.com/docs/octelium/latest/management/core/service/anonymous-access.md).

Now we visit the *Service* via the web browser at the URL `https://idp.<DOMAIN>` and use the user `user` and the password `<YOUR_PASSWORD>` set in the Helm `values.yaml` set above to login.

Now that you are logged in and inside the Keycloak dashboard, you can create an OpenID Connect client application and use it to create an *IdentityProvider* in Octelium as follows:

1. Go to the list of **Clients** and then click on **Create client**.
2. In **General Settings** set the **Client ID** to `octelium` and press **Next**.
3. In **Capability config** set **client authentication** to **ON**.
4. In **Login settings** set the **root URL** to `https://<DOMAIN>` and **Valid redirect URIs** to `https://<DOMAIN>/callback` and then click on **save**.
5. Now you're back in your `octelium` client page. Go to the **Credentials** tab and then copy the \*\*Client Secret
   \*\* and then create a *Secret* for the client's client secret as follows:

```bash
octeliumctl create secret keycloak-client
```

Now create an OpenID Connect *IdentityProvider* using the application's client id, the client secret's *Secret* and the issuer URL as follows:

```yaml
kind: IdentityProvider
metadata:
  name: keycloak
spec:
  displayName: Login with Keycloak
  oidc:
    clientID: octelium
    clientSecret:
      fromSecret: keycloak-client
    issuerURL: https://idp.<DOMAIN>/realms/master
```

Now you can apply the creation of the *IdentityProvider* via the `octeliumctl apply` command as follows:

```bash
octeliumctl apply /PATH/TO/IDENTITY_PROVIDER.YAML
```