Skip to content

OidcClient Reference

Overview

An OidcClient represents an OIDC client application that can authenticate users through Kubauth. In OIDC terminology, a client is an application that delegates user authentication to an OIDC server.

API Group: kubauth.kubotal.io/v1alpha1

Kind: OidcClient

Namespaced: Yes (typically kubauth-oidc)

Example

apiVersion: kubauth.kubotal.io/v1alpha1
kind: OidcClient
metadata:
  name: my-app
  namespace: kubauth
spec:
  redirectURIs:
    - "https://myapp.example.com/callback"
  grantTypes:
    - "refresh_token"
    - "authorization_code"
  responseTypes:
    - "code"
    - "id_token"
    - "token"
    - "id_token token"
    - "code id_token"
    - "code token"
    - "code id_token token"      
  scopes:
    - "openid"
    - "profile"
    - "groups"
    - "email"
  description: "My Application"
  displayName: "My App"
  entryURL: "https://myapp.example.com"
  accessTokenLifespan: 1h
  idTokenLifespan: 1h
  refreshTokenLifespan: 8h
  public: false
  secrets:
    - name: oidc-my-app-client-secret
      key: secretRef
      hashed: false

Spec Fields

secrets

[]secretRef - Required if not public

A list of Kubernetes Secret references.

secrets[X].name

string - Required

The name of the referenced Kubernetes Secret.

secrets[X].key

string - Required

The key within the Secret that holds the client secret value.

secrets[X].hashed

boolean - Optional. Default: false

Set to true if the secret value is stored as a bcrypt hash for additional security.

Use the kc hash command to generate a hash from a plain-text secret.

redirectURIs

[]string - Required

List of allowed redirect URIs for the OAuth2 authorization flow. After successful authentication, the authorization server will redirect the user back to one of these URIs.

Example: 

redirectURIs:
  - "https://myapp.example.com/callback"
  - "http://localhost:8080/callback"  # For local development

grantTypes

[]string - Required

List of OAuth2 grant types that this client is allowed to use.

Common values:

  • authorization_code - Standard OAuth2 authorization code flow
  • refresh_token - Allows using refresh tokens to obtain new access tokens
  • password - Resource Owner Password Credentials (ROPC) flow (must be explicitly enabled)

Example: 

grantTypes:
  - "authorization_code"
  - "refresh_token"

responseTypes

[]string - Required

List of response types the client can expect from the authorization endpoint.

Common values:

  • code - Authorization code
  • token - Access token (implicit flow)
  • id_token - ID token
  • id_token token - Both ID token and access token
  • code id_token - Both code and ID token
  • code token - Both code and access token
  • code id_token token - All three

Example: 

responseTypes: [ "id_token", "code", "token", "id_token token", "code id_token", "code token", "code id_token token" ]

scopes

[]string - Required

List of OAuth2 scopes that this client can request.

Standard OIDC scopes:

  • openid - Required for OIDC authentication
  • profile - Access to user profile information
  • email - Access to user email
  • offline / offline_access - Request refresh tokens
  • groups - Access to user group membership

Example: 

scopes:
  - "openid"
  - "profile"
  - "groups"
  - "email"
  - "offline_access"

public

boolean - Optional. Default: false

Indicates whether this is a public client. Public clients do not require a client secret.

Use for: Browser-based applications, native mobile apps, CLI tools

Example: 

public: true

forceOpenIdScope

boolean - Optional. Default: false

Force openid scope even if not requested by the client application.

postLogoutURL

boolean - Optional. Default: false

Where to redirected user on logout.

  • Will take precedence on the same global configuration value.
  • May be overridden by a query parameter on the logout url

displayName

string - optional

A user-friendly name for the application. This is displayed on the Kubauth index page and logout page.

Example: 

displayName: "Employee Portal"

description (string)

Optional

A short description of the client application. This is displayed on the Kubauth index page and logout page.

Example: 

description: "Corporate application for employee management"

entryURL

string - optional

The main entry URL for the application. Used to provide a link to the application on the Kubauth index page and logout page.

Note: Requires displayName and description to be set for the application to appear in the application list.

Example: 

entryURL: "https://portal.example.com"

accessTokenLifespan

duration - optional - default: 1 Hour

The lifespan of access tokens issued to this client.

Format: Duration string (e.g., 1m0s, 1h, 30m)

Example: 

accessTokenLifespan: 15m

idTokenLifespan

duration - optional - default: 1 Hour

The lifespan of ID tokens issued to this client.

Format: Duration string (e.g., 1m0s, 1h, 30m)

Example: 

idTokenLifespan: 1h

refreshTokenLifespan

duration - optional - default: 30 days

The lifespan of refresh tokens issued to this client.

Format: Duration string (e.g., 1h, 8h, 24h)

Example: 

refreshTokenLifespan: 8h

Status Fields

The OidcClient resource does not currently expose status fields. The resource is ready to use immediately after creation.

Usage Notes

Client ID

The client ID is derived from the resource name in the metadata section. This is what client applications use to identify themselves to the OIDC server.

Namespacing

OidcClient resources are typically created in the kubauth-oidc namespace, though this can be configured via Helm chart values.

Security Considerations

Public vs Confidential Clients:

  • Use public: true for applications that cannot securely store a secret (browsers, mobile apps, CLIs)
  • Use hashedSecret for server-side applications that can securely store credentials

Token Lifespans:

  • Shorter access token lifespans increase security but may impact performance
  • Balance security requirements with user experience
  • For kubectl integration, consider very short access tokens (1-5 minutes) with longer refresh tokens

Grant Types:

  • Only enable the grant types your application actually needs
  • The password grant type is deprecated and disabled by default - use only for specific use cases

Application List Display

For an application to appear on the Kubauth index page (https://kubauth.example.com/index) and logout page, all three of the following fields must be set:

  • displayName
  • description
  • entryURL

Examples

Public Client (Browser/CLI)

apiVersion: kubauth.kubotal.io/v1alpha1
kind: OidcClient
metadata:
  name: public
  namespace: kubauth-oidc
spec:
  redirectURIs:
    - "http://127.0.0.1:9921/callback"
  grantTypes:
    - "refresh_token"
    - "authorization_code"
  responseTypes:
    - "id_token"
    - "code"
  scopes:
    - "openid"
    - "profile"
    - "groups"
    - "email"
    - "offline_access"
  description: "Test public client"
  public: true

Confidential Client (Server Application)

apiVersion: kubauth.kubotal.io/v1alpha1
kind: OidcClient
metadata:
  name: webapp
  namespace: kubauth-oidc
spec:
  hashedSecret: "$2a$12$..."
  redirectURIs:
    - "https://webapp.example.com/callback"
  grantTypes:
    - "refresh_token"
    - "authorization_code"
  responseTypes:
    - "code"
  scopes:
    - "openid"
    - "profile"
    - "groups"
    - "email"
    - "offline_access"
  description: "Corporate Web Application"
  displayName: "Corporate Portal"
  entryURL: "https://webapp.example.com"
  accessTokenLifespan: 30m
  refreshTokenLifespan: 24h

Kubernetes kubectl Client

apiVersion: kubauth.kubotal.io/v1alpha1
kind: OidcClient
metadata:
  name: k8s
  namespace: kubauth-oidc
spec:
  hashedSecret: "$2a$12$..."
  description: "For kubernetes kubectl access"
  grantTypes:
    - "refresh_token"
    - "authorization_code"
    - "password"
  redirectURIs:
    - "http://localhost:8000"
    - "http://localhost:18000"
  responseTypes:
    - "id_token"
    - "code"
  scopes:
    - "openid"
    - "offline"
    - "profile"
    - "groups"
    - "email"
    - "offline_access"
  accessTokenLifespan: 1m
  idTokenLifespan: 1m
  refreshTokenLifespan: 30m