Deployment Guide: kube-oidc-proxy

[chintansakhiya]

Follow the steps below to build and deploy the kube-oidc-proxy.

Step 1: Build the Binary

Run the following command to build the binary for this repository:

go build -o ./proxy ./cmd/.

This command generates a binary file named proxy.

Step 2: Run the Proxy

Execute the binary with the appropriate flags as shown below:

./proxy \
  --clusters-config=<path to>/clusterConfig.yaml \              # Path to the clusters configuration file containing a list of cluster names and kubeconfig paths.
  --oidc-issuer-url=https://<server-url>/realms/<realm-name> \  # OIDC provider URL. For Keycloak, use the realm-specific URL.
  --oidc-client-id=<client-id> \                               # OIDC client ID.
  --oidc-ca-file=<path to oidc provider CA file> \             # CA file to verify the OpenID server's certificate. If not provided, the host's root CA set is used.
  --oidc-signing-algs=<alg-name> \                             # Comma-separated list of allowed JOSE signing algorithms (default: `RS256`).
  --tls-cert-file=<path to TLS cert file> \                    # Path to the TLS certificate file.
  --tls-private-key-file=<path to TLS private key file> \      # Path to the TLS private key file.
  --oidc-groups-claim=groups \                                 # Claim used to retrieve groups from the OIDC token.
  --role-config=<path to role-config file>                     # Path to the role configuration file containing roles, roleBindings, clusterRoles, and clusterRoleBindings, with an additional cluster name field.

Description of Flags

• --clusters-config: Points to a configuration file listing cluster names and their corresponding kubeconfig paths.
• --oidc-issuer-url: URL of the OIDC provider. For Keycloak, use the format https://<server-url>/realms/<realm-name>.
• --oidc-client-id: OIDC client ID used for authentication.
• --oidc-ca-file: File path for the certificate authority (CA) file. If omitted, the system's root CA will be used.
• --oidc-signing-algs: Specify allowed JOSE signing algorithms. The default is RS256.
• --tls-cert-file: Path to the TLS certificate file. If omitted, a self-signed certificate is generated and saved.
• --tls-private-key-file: Path to the TLS private key file. If omitted, a self-signed key is generated and saved.
• --oidc-groups-claim: The token claim that maps to user groups. Default is groups.
• --role-config: File path to the role configuration mapper containing roles, roleBindings, clusterRoles, clusterRoleBindings, and the associated cluster name.

---

By following these steps, you should have the kube-oidc-proxy built and running successfully.

[chintansakhiya]

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: kube-oidc-proxy
  namespace: kube-oidc-proxy
spec:
  chart:
    spec:
      chart: polymorphic-app
      reconcileStrategy: ChartVersion
      version: 2.2.1
      sourceRef:
        kind: HelmRepository
        name: improwised
        namespace: flux-system
  interval: 10m0s
  values:
    prefixWithReleaseName:
      enabled: false
    services:
      - name: kube-oidc-proxy
        image:
          repository: <imageRepo>/kube-oidc-proxy  # {"$imagepolicy": "kube-oidc-proxy"}
          tag: latest # {"$imagepolicy": "kube-oidc-proxy:latest"}
        imagePullSecrets:
          - name: <name>
        healthcheck:
          enabled: true
          type: httpGet
          path: /ready
          port: health
        ports:
          - name: http
            containerPort: 6443
          - name: health
            containerPort: 8080
        service:
          enabled: true
          ports:
            - name: http
              port: 6443
              targetPort: http
        command: ["/bin/sh", "-c"]
        args: ["./proxy",
          "--clusters-config=<file path>",
          "--oidc-issuer-url=<issuer url>",
          "--oidc-client-id=<client id>",
          "--oidc-ca-file=<file path>",
          # if tls-cert-file and tls-private-key-file are not provided, it will generate self-signed certificate
          "--tls-cert-file=<file path>",
          "--tls-private-key-file=<file path>",

          "--oidc-signing-algs=RS256",
          "--oidc-groups-claim=groups",
          "--oidc-username-claim=email",

          # ops-dashboard host part
          "--audit-webhook-server=<webhook server>",]
        ingress:
          enabled: true
          className: nginx
          hosts:
            - host: kube-oidc-proxy.com
              paths:
                - path: /
                  pathType: Prefix
                  servicePort: http

[chintansakhiya]

How to generate oidc client ID and secret.

• The redirect URL must match the one configured in Gangway's environment variables.

Screencast.From.2025-01-08.10-06-51.mp4

[chintansakhiya]

How to create a client scopes and mapper

Screencast.From.2025-01-10.12-34-57.mp4

[chintansakhiya]

How to create and assign role

Screencast.From.2025-01-20.10-59-43.mp4