Security

OIDCProvider

Defines an OIDC identity provider for the Lattice auth proxy. Validates JWT tokens from users connecting to clusters. The controller discovers the provider's JWKS endpoint via .well-known/openid-configuration and periodically refreshes signing keys.

group: lattice.dev version: v1alpha1 scope: namespaced

When an OIDCProvider is created, the controller fetches .well-known/openid-configuration from the issuer URL to discover the JWKS endpoint. Incoming JWT tokens are validated against the cached JWKS keys, and the configured claims are extracted for username and group mapping.

Examples

okta.yaml

apiVersion: lattice.dev/v1alpha1
kind: OIDCProvider
metadata:
  name: okta-prod
spec:
  issuerUrl: https://myorg.okta.com/oauth2/default
  clientId: "0oa1b2c3d4e5f6g7h8i9"
  clientSecret:
    name: okta-oidc-secret
    namespace: lattice-system
  usernameClaim: email
  groupsClaim: groups
  usernamePrefix: "oidc:"
  groupsPrefix: "okta:"
  audiences:
    - api://lattice
    - 0oa1b2c3d4e5f6g7h8i9
  requiredClaims:
    - name: email_verified
      value: "true"
  jwksRefreshIntervalSeconds: 1800
  propagate: true
  allowChildOverride: false

minimal.yaml

apiVersion: lattice.dev/v1alpha1
kind: OIDCProvider
metadata:
  name: dev-idp
spec:
  issuerUrl: https://accounts.google.com
  clientId: "123456789.apps.googleusercontent.com"

Spec

OIDCProvider spec fields
Field	Type	Description
`issuerUrl`	string	OIDC issuer URL. Must serve a `.well-known/openid-configuration` endpoint.
`clientId`	string	OIDC client ID registered with the identity provider.
`clientSecret`	SecretRef?	Optional client secret for token introspection. References a Kubernetes Secret.
`usernameClaim`	string	JWT claim to use as the username. Default: `"sub"`.
`groupsClaim`	string	JWT claim to extract group memberships from. Default: `"groups"`.
`usernamePrefix`	string?	Prefix added to usernames to avoid collisions (e.g., `"oidc:"`).
`groupsPrefix`	string?	Prefix added to group names to avoid collisions.
`audiences`	[]string	Allowed audiences for token validation. Tokens must contain at least one matching `aud` claim.
`requiredClaims`	[]RequiredClaim	Claims that must be present in the token. Tokens missing any required claim are rejected.
`caBundle`	string?	PEM-encoded CA certificate bundle for verifying the IdP's TLS certificate. Use for self-signed or internal CAs.
`jwksRefreshIntervalSeconds`	u32	Interval in seconds between JWKS key refreshes. Default: `3600`.
`propagate`	bool	Propagate this OIDCProvider to child clusters. Default: `true`.
`allowChildOverride`	bool	Allow child clusters to override this provider's configuration. Default: `false`.

SecretRef

SecretRef fields
Field	Type	Description
`name`	string	Name of the Kubernetes Secret.
`namespace`	string	Namespace of the Kubernetes Secret.

RequiredClaim

RequiredClaim fields
Field	Type	Description
`name`	string	Name of the JWT claim that must be present.
`value`	string?	If set, the claim must have this exact value. If omitted, only presence is checked.

Status

OIDCProvider status fields
Field	Type	Description
`phase`	OIDCProviderPhase	Current phase of the OIDC provider.
`message`	string?	Human-readable status message.
`lastJwksFetch`	string?	ISO 8601 timestamp of the last successful JWKS fetch.
`jwksUri`	string?	JWKS endpoint URL discovered from the issuer's OpenID configuration.

OIDCProviderPhase

Pending Waiting to discover OIDC configuration and fetch JWKS keys.

Ready OIDC discovery complete and JWKS keys cached. Tokens can be validated.

Failed OIDC discovery or JWKS fetch failed. Check the issuer URL and network connectivity.