Authentication and OIDC Configuration

Configuring login providers for Konflux using Dex connectors - GitHub, OpenShift, OIDC, LDAP, and static passwords.

Konflux uses Dex as a federated identity broker and oauth2-proxy to authenticate users against one or more third-party identity providers. The operator manages both components and exposes their configuration through the Konflux CR.

All authentication settings live under spec.ui.spec.dex in the Konflux CR.

Overview

Authentication in Konflux works as follows:

The user’s browser is redirected to Dex.
Dex presents the configured connectors (GitHub, OpenShift, OIDC, LDAP, etc.) as login options.
After the user authenticates with an upstream provider, Dex issues a token to oauth2-proxy.
oauth2-proxy validates the token and grants access to the Konflux UI.

The spec.ui.spec.dex.config section controls which identity providers are available and how Dex is configured.

The static-password configuration included in the default sample CR (and used in local Kind deployments) is intended for development and CI only. Remove staticPasswords and configure an OIDC connector before deploying to production.

GitHub OAuth

GitHub OAuth is the a common connector for Konflux deployments.

Creating a GitHub OAuth App

Create a GitHub OAuth App following the GitHub documentation.

When registering the app, set the Authorization callback URL to:

https://<your-konflux-hostname>/idp/callback

Dex is not exposed at a separate hostname — it runs behind the Konflux proxy at the /idp/ path of your Konflux UI URL. The operator derives this URL automatically from ingress.host (or the OpenShift default ingress domain if not explicitly set).

Once created, note the Client ID and generate a Client Secret — you will need both in the next step.

Creating the Secret

Store the credentials in the konflux-ui namespace where Dex runs:

kubectl create secret generic github-client \
  --namespace konflux-ui \
  --from-literal=clientID="<your-client-id>" \
  --from-literal=clientSecret="<your-client-secret>"

Configuring the Connector

Reference the secret via environment variables in the dex container and add a github connector to the Dex configuration:

apiVersion: konflux.konflux-ci.dev/v1alpha1
kind: Konflux
metadata:
  name: konflux
spec:
  ui:
    spec:
      ingress:
        enabled: true
      dex:
        dex:
          env:
            - name: GITHUB_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: github-client
                  key: clientID
            - name: GITHUB_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: github-client
                  key: clientSecret
        config:
          connectors:
            - type: github
              id: github
              name: GitHub
              config:
                clientID: $GITHUB_CLIENT_ID
                clientSecret: $GITHUB_CLIENT_SECRET

Restricting Access to Specific Organisations

To allow only members of certain GitHub organisations (and optionally specific teams) to log in, add an orgs block to the connector config:

        config:
          connectors:
            - type: github
              id: github
              name: GitHub
              config:
                clientID: $GITHUB_CLIENT_ID
                clientSecret: $GITHUB_CLIENT_SECRET
                orgs:
                  - name: my-org
                    teams:
                      - developers
                      - admins
                  - name: another-org

Refer to the Dex GitHub connector documentation for the full list of available options, including org and team restrictions.

When Konflux is deployed on an OpenShift cluster, the operator can automatically configure a Dex connector that delegates authentication to the cluster’s built-in OAuth server. Users can then log in with any identity provider already configured in OpenShift (LDAP, HTPasswd, GitHub, etc.).

The behaviour is controlled by configureLoginWithOpenShift in spec.ui.spec.dex.config:

Value	Behaviour
`true`	OpenShift connector is added when running on OpenShift
`false`	OpenShift connector is never added, even on OpenShift
(unset)	OpenShift connector is added automatically when running on OpenShift

To explicitly enable OpenShift login:

apiVersion: konflux.konflux-ci.dev/v1alpha1
kind: Konflux
metadata:
  name: konflux
spec:
  ui:
    spec:
      dex:
        config:
          configureLoginWithOpenShift: true

When the operator detects OpenShift and this value is unset or true, it creates a ServiceAccount and Secret in the konflux-ui namespace and registers the cluster’s OAuth server as a Dex connector automatically - no additional secrets or connector configuration is required.

To disable OpenShift login on an OpenShift cluster:

        config:
          configureLoginWithOpenShift: false

Generic OIDC Connector

Any OIDC-compliant identity provider (Google, Keycloak, Azure AD, Okta, etc.) can be added using the oidc connector type.

Example: Google

        config:
          connectors:
            - type: oidc
              id: google
              name: Google
              config:
                clientID: $GOOGLE_CLIENT_ID
                clientSecret: $GOOGLE_CLIENT_SECRET
                issuer: https://accounts.google.com

Refer to the Dex OIDC connector documentation for the full list of available options.

LDAP Connector

Konflux supports authenticating users against an LDAP or Active Directory server through Dex’s built-in LDAP connector.

        config:
          connectors:
            - type: ldap
              id: ldap
              name: LDAP
              config:
                host: ldap.example.com:636
                bindDN: cn=admin,dc=example,dc=com
                bindPW: $LDAP_BIND_PASSWORD
                userSearch:
                  baseDN: ou=Users,dc=example,dc=com
                  filter: "(objectClass=person)"
                  username: uid
                  idAttr: uid
                  emailAttr: mail
                  nameAttr: cn
                groupSearch:
                  baseDN: ou=Groups,dc=example,dc=com
                  filter: "(objectClass=groupOfNames)"
                  nameAttr: cn
                  userMatchers:
                    - userAttr: DN
                      groupAttr: member

Store the bind password in a secret and expose it to the Dex container via an environment variable:

kubectl create secret generic ldap-bind \
  --namespace konflux-ui \
  --from-literal=bindPassword="<your-bind-password>"

      dex:
        dex:
          env:
            - name: LDAP_BIND_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: ldap-bind
                  key: bindPassword
        config:
          connectors:
            - type: ldap
              # ...

Refer to the Dex LDAP connector documentation for the complete reference.

Group Support

Konflux supports group-based access control. When an identity provider returns group memberships, Konflux propagates them through the authentication chain so that Kubernetes RBAC group bindings work as expected.

How It Works

The identity provider (GitHub orgs/teams, LDAP groups, OIDC groups claim, etc.) returns the user’s group memberships to Dex.
Dex includes the groups in the ID token when the groups scope is requested.
oauth2-proxy reads the groups from the token and passes them to the proxy in the X-Auth-Request-Groups header.
The proxy splits the groups and forwards each as a separate Impersonate-Group header to the Kubernetes API, along with the static system:authenticated group.

Enabling Groups

Groups are enabled by default. The proxy requests the groups scope from Dex automatically. For most connectors (GitHub, LDAP, OIDC), groups are returned as long as the connector is configured to fetch them.

For GitHub, teams within configured orgs are returned as groups automatically when orgs are specified in the connector config.

For LDAP, configure a groupSearch section in the connector (see the LDAP Connector section above).

For OIDC, ensure your identity provider includes a groups claim in the ID token and that Dex is configured to request it (most OIDC connectors do this by default).

For static passwords (local development), groups can be set directly on each user entry (requires Dex v2.45.0+):

        config:
          staticPasswords:
            - email: user1@konflux.dev
              hash: "..."
              username: user1
              userID: "..."
              groups:
                - team-alpha
                - team-beta

Limitations

Re-login required after group changes. Group memberships are embedded in the ID token at login time. If a user’s groups change in the identity provider, they must log out and log back in to get a fresh token with the updated groups.

Static Passwords (Local Development Only)

For local development and CI testing, Dex supports a built-in password database. Enable it with enablePasswordDB: true and define users in staticPasswords:

        config:
          enablePasswordDB: true
          passwordConnector: local
          staticPasswords:
            - email: user1@konflux.dev
              # Generate a bcrypt hash: echo password | htpasswd -BinC 10 admin | cut -d: -f2
              hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" # notsecret
              username: user1
              userID: "7138d2fe-724e-4e86-af8a-db7c4b080e20"

Static passwords are stored as bcrypt hashes in the Konflux CR, but the CR itself is visible to anyone with read access to the cluster. Never use this configuration in production. Use an OIDC connector instead.

Combining Multiple Connectors

Multiple connectors can be configured simultaneously. Dex presents all of them on its login page and allows users to choose. The following example enables GitHub, Google, and OpenShift login together:

apiVersion: konflux.konflux-ci.dev/v1alpha1
kind: Konflux
metadata:
  name: konflux
spec:
  ui:
    spec:
      ingress:
        enabled: true
      dex:
        dex:
          env:
            - name: GITHUB_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: github-client
                  key: clientID
            - name: GITHUB_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: github-client
                  key: clientSecret
            - name: GOOGLE_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: google-client
                  key: clientID
            - name: GOOGLE_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: google-client
                  key: clientSecret
        config:
          configureLoginWithOpenShift: true
          connectors:
            - type: github
              id: github
              name: GitHub
              config:
                clientID: $GITHUB_CLIENT_ID
                clientSecret: $GITHUB_CLIENT_SECRET
            - type: oidc
              id: google
              name: Google
              config:
                clientID: $GOOGLE_CLIENT_ID
                clientSecret: $GOOGLE_CLIENT_SECRET
                issuer: https://accounts.google.com

Additional Connectors

Dex supports many more upstream providers including Bitbucket Cloud, GitLab, SAML 2.0, LinkedIn, Microsoft, and more. For the full list of available connectors and their configuration options, refer to the Dex connectors documentation.