OidcClient
An OidcClient resource registers an OAuth2/OIDC application with the Nauthera operator. Each client belongs to the namespace of the application it represents, enabling application teams to self-service their own OAuth2 client registrations without needing access to cluster-wide security resources.
Example
apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
metadata:
name: my-webapp
namespace: my-app-dev
spec:
displayName: "My Awesome Web App"
redirectUris:
- "https://my-webapp.dev.example.com/callback"
scopes:
- openid
- profile
- email
- "api:read"Spec Reference
spec.displayName
Type: string | Optional
A human-readable display name for this client. This value is shown in the Nauthera admin UI and in consent screens if enabled. If omitted, the resource name is used.
spec:
displayName: "My Awesome Web App"spec.redirectUris
Type: []string | Required
The list of allowed redirect URIs for authorization code flows. The redirect_uri parameter in an authorization request must exactly match one of these values.
spec:
redirectUris:
- "https://my-webapp.dev.example.com/callback"
- "https://my-webapp.staging.example.com/callback"spec.scopes
Type: []string | Required
The list of OAuth2 scopes this client is permitted to request. The applicable ClusterAuthPolicy and/or namespace-scoped AuthPolicy may further restrict which scopes are actually granted at token issuance time.
spec:
scopes:
- openid
- profile
- email
- "api:read"spec.grantTypes
Type: []string | Optional
The OAuth2 grant types this client is permitted to use. Defaults to ["authorization_code", "refresh_token"].
spec:
grantTypes:
- authorization_code
- refresh_token
- client_credentialsSupported grant types:
| Grant Type | Description |
|---|---|
authorization_code | Standard authorization code flow (recommended for web apps) |
refresh_token | Exchange a refresh token for a new access token |
client_credentials | Machine-to-machine authentication without a user context |
urn:ietf:params:oauth:grant-type:token-exchange | RFC 8693 token exchange |
spec.tokenEndpointAuthMethod
Type: string | Optional
The client authentication method used at the token endpoint. Defaults to client_secret_basic.
spec:
tokenEndpointAuthMethod: client_secret_basic| Value | Description |
|---|---|
client_secret_basic | Client ID and secret in the Authorization header (HTTP Basic) |
client_secret_post | Client ID and secret in the request body |
private_key_jwt | JWT signed with the client's private key (for confidential clients using asymmetric key authentication) |
none | No authentication — PKCE required (for public/native clients) |
spec.pkce
Type: object | Optional
Controls PKCE (Proof Key for Code Exchange, RFC 7636) requirements.
spec:
pkce:
required: true
allowPlainMethod: false| Field | Default | Description |
|---|---|---|
required | false | If true, all authorization code requests must include a code_challenge |
allowPlainMethod | false | If true, allow code_challenge_method=plain (not recommended) |
spec.postLogoutRedirectUris
Type: []string | Optional
Allowed redirect URIs for RP-initiated logout flows.
spec:
postLogoutRedirectUris:
- "https://my-webapp.dev.example.com/logged-out"spec.credentialsSecretName
Type: string | Optional
The name of the Secret the operator will create or update with the generated credentials. Defaults to {metadata.name}-oidc-credentials.
spec:
credentialsSecretName: my-webapp-oidc-secretspec.configMapName
Type: string | Optional
The name of the ConfigMap the operator will create with the OIDC discovery endpoints. Defaults to {metadata.name}-oidc-config.
spec:
configMapName: my-webapp-oidc-configProvisioned Resources
When you create an OidcClient, the operator provisions two resources in the same namespace: a Secret with sensitive credentials and a ConfigMap with non-sensitive OIDC endpoint configuration. Together they contain everything an application needs to integrate with Nauthera — no hardcoded URLs or manual discovery required.
The operator sets owner references on both resources, linking them to the OidcClient. Deleting the OidcClient also deletes the Secret and ConfigMap.
Secret
Contains the sensitive credentials. The operator will only update Secrets it owns — it will not overwrite a pre-existing Secret that was not originally created by the operator.
apiVersion: v1
kind: Secret
metadata:
name: my-webapp-oidc-credentials
namespace: my-app-dev
ownerReferences:
- apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
name: my-webapp
type: Opaque
data:
client_id: <base64>
client_secret: <base64>ConfigMap
Contains the OIDC endpoint URLs and non-sensitive client metadata. Applications and resource servers can mount this ConfigMap to discover all endpoints without calling the discovery endpoint at startup.
apiVersion: v1
kind: ConfigMap
metadata:
name: my-webapp-oidc-config
namespace: my-app-dev
ownerReferences:
- apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
name: my-webapp
data:
issuer_url: "https://auth.example.com"
authorization_endpoint: "https://auth.example.com/oauth2/authorize"
token_endpoint: "https://auth.example.com/oauth2/token"
userinfo_endpoint: "https://auth.example.com/oauth2/userinfo"
revocation_endpoint: "https://auth.example.com/oauth2/revoke"
jwks_uri: "https://auth.example.com/.well-known/jwks.json"
end_session_endpoint: "https://auth.example.com/oauth2/logout"
client_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
scopes: "openid profile email api:read"Note: The
client_idis present in both the Secret and the ConfigMap. The ConfigMap copy is for convenience — it is not a secret value and can safely be exposed to sidecar containers, init scripts, or other non-sensitive consumers.
Using the Resources in a Pod
Mount both the Secret and ConfigMap as environment variables for a complete OIDC integration with zero hardcoded values:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-webapp
namespace: my-app-dev
spec:
template:
spec:
containers:
- name: app
image: myregistry/my-webapp:latest
envFrom:
# Non-sensitive OIDC config (issuer, endpoints, scopes)
- configMapRef:
name: my-webapp-oidc-config
# Sensitive credentials (client_id, client_secret)
- secretRef:
name: my-webapp-oidc-credentialsThis injects all keys as environment variables. Your application can read them directly:
| Environment Variable | Source | Example Value |
|---|---|---|
issuer_url | ConfigMap | https://auth.example.com |
authorization_endpoint | ConfigMap | https://auth.example.com/oauth2/authorize |
token_endpoint | ConfigMap | https://auth.example.com/oauth2/token |
userinfo_endpoint | ConfigMap | https://auth.example.com/oauth2/userinfo |
revocation_endpoint | ConfigMap | https://auth.example.com/oauth2/revoke |
jwks_uri | ConfigMap | https://auth.example.com/.well-known/jwks.json |
end_session_endpoint | ConfigMap | https://auth.example.com/oauth2/logout |
client_id | Secret + ConfigMap | a1b2c3d4-... |
client_secret | Secret | (sensitive) |
scopes | ConfigMap | openid profile email api:read |
For selective mounting, use individual valueFrom references:
env:
- name: OIDC_ISSUER
valueFrom:
configMapKeyRef:
name: my-webapp-oidc-config
key: issuer_url
- name: OIDC_CLIENT_ID
valueFrom:
secretKeyRef:
name: my-webapp-oidc-credentials
key: client_id
- name: OIDC_CLIENT_SECRET
valueFrom:
secretKeyRef:
name: my-webapp-oidc-credentials
key: client_secretResource Server Pattern
Resource servers (APIs that validate tokens) only need the ConfigMap — they verify tokens using the JWKS endpoint and don't need client credentials:
containers:
- name: api
image: myregistry/api-server:latest
env:
- name: OIDC_ISSUER
valueFrom:
configMapKeyRef:
name: my-webapp-oidc-config
key: issuer_url
- name: OIDC_JWKS_URI
valueFrom:
configMapKeyRef:
name: my-webapp-oidc-config
key: jwks_uriStatus
status:
clientId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
ready: true
phase: Active
conditions:
- type: Ready
status: "True"
reason: ClientRegistered
lastTransitionTime: "2024-01-01T00:00:00Z"
- type: CredentialsProvisioned
status: "True"
reason: SecretCreated
lastTransitionTime: "2024-01-01T00:00:00Z"
- type: ConfigProvisioned
status: "True"
reason: ConfigMapCreated
lastTransitionTime: "2024-01-01T00:00:00Z"Conditions
| Condition | Description |
|---|---|
Ready | The client is registered with the operator and operational |
CredentialsProvisioned | The credentials Secret has been created in the client namespace |
ConfigProvisioned | The OIDC configuration ConfigMap has been created in the client namespace |
Multi-Environment Pattern
A common pattern is to create one OidcClient per environment namespace:
# my-app-dev namespace
apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
metadata:
name: my-webapp
namespace: my-app-dev
spec:
redirectUris:
- "https://my-webapp.dev.example.com/callback"
scopes: [openid, profile, email]
---
# my-app-prod namespace
apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
metadata:
name: my-webapp
namespace: my-app-prod
spec:
redirectUris:
- "https://my-webapp.example.com/callback"
scopes: [openid, profile, email]Related Resources
- ServiceAccount — For machine-to-machine authentication without a user context.
- AuthPolicy — The policies governing what this client can do.
- Quick Start — Step-by-step guide to creating your first client.