Skip to content

PocketIDOIDCClient

PocketIDOIDCClient is the Schema for the pocketidoidcclients API

PocketIDOIDCClient.spec

PocketIDOIDCClientSpec defines the desired state of PocketIDOIDCClient

Validation rules:

  • clientID is immutable
  • clientSecretRotation cannot be enabled when secret.storeClientSecret is false
  • clientPermissions and clientAccess require a confidential client (isPublic must be false)
  • clientSecretRef requires a confidential client (isPublic must be false)
  • clientSecretRotation cannot be enabled when clientSecretRef is set
  • clientID must be at most 128 characters unless it is a client ID metadata document URL
  • name, callbackUrls, logoutCallbackUrls, backchannelLogoutUrl, federatedIdentities, isPublic, and pkceEnabled are owned by the client ID metadata document and must not be set on a CIMD client
  • a CIMD client is always public and has no client secret, so clientSecretRef and clientSecretRotation are not supported
  • clientPermissions and clientAccess require a confidential client, and a CIMD client is always public
  • clientSecretOverlap must not exceed clientSecretRotation.interval
  • clientSecretOverlap requires a confidential client (isPublic must be false)
Field Type Required Default Description
name string Name of the oidc client to create in Pocket ID. If omitted, defaults to metadata.name of the oidcclient resource.
description string Description is an optional description for the client
MaxLength: 150
instanceSelector LabelSelector InstanceSelector selects the PocketIDInstance to reconcile against.
If omitted, the controller expects exactly one instance in the cluster.
clientID string ClientID is the optional OIDC client ID to use instead of a generated one. The Client ID is immutable and cannot be changed once the oidc client is created.
An https:// URL marks the client as an OAuth Client ID Metadata Document (CIMD) client, which the operator adopts but never creates and only partially manages.
MaxLength: 512
MinLength: 2
callbackUrls string array Callback URLs for the client.
logoutCallbackUrls string array Logout callback URLs for the client.
backchannelLogoutUrl string Back-channel logout URL Pocket-ID notifies when a user's session for the client ends.
launchUrl string Launch URL for the client. Used in the "apps" dashboard in the Pocket-ID ui.
logoUrl string Deprecated: Use spec.logo.logoUrl instead.
darkLogoUrl string Deprecated: Use spec.logo.darkLogoUrl instead.
logo object Logo configures logo URLs for the OIDC client with template support.
isPublic boolean false Indicates if the client is public (no client secret).
pkceEnabled boolean false Enables PKCE for the client.
requiresReauthentication boolean false Requires reauthentication on login.
requiresPushedAuthorizationRequests boolean false Requires the client to use pushed authorization requests (PAR).
skipConsent boolean false Skips the consent screen on initial authorization for this client.
accessTokenDurationMinutes integer 60 How long access tokens issued to this client stay valid, in minutes.
Maximum: 525600
Minimum: 1
refreshTokenDurationMinutes integer 43200 How long refresh tokens issued to this client stay valid, in minutes.
Maximum: 525600
Minimum: 1
federatedIdentities []object FederatedIdentities configures JWT assertion identities.
allowedUserGroups []object AllowedUserGroups restricts access to the listed user groups.
Each entry names either a PocketIDUserGroup CR or, for groups managed outside this cluster, an existing Pocket-ID group by name or ID.
apiAccess []object APIAccess grants this client permission to request scoped access on the referenced PocketIDAPIs.
secret object Secret defines how OIDC client credentials should be stored in a Kubernetes Secret.
scim object SCIM configures SCIM provisioning for this OIDC client. Pocket ID will push user/group changes to the configured endpoint.
clientSecretRotation object ClientSecretRotation configures automatic, scheduled regeneration of the client secret.
When unset the secret is only regenerated on create/adopt, on self-heal, or when the regenerate-client-secret annotation is set.
clientSecretRef SecretKeySelector ClientSecretRef references a Kubernetes Secret key holding the client secret to set in Pocket-ID, instead of letting the operator generate one. The value must be at least 16 printable ASCII characters.
While set, the operator never generates or rotates the secret.
clientSecretOverlap Duration ClientSecretOverlap is how long the client-secret a replacement supersedes stays valid in Pocket-ID, giving consumers time to rollout and pick up the new one.
When unset or zero the previous secret is deleted as soon as the replacement is stored, so exactly one secret is ever valid.
Must not exceed 168h, nor clientSecretRotation.interval if set.

↩ PocketIDOIDCClient.spec

OIDCClientLogoSpec configures logo URLs for the OIDC client. Logo URLs support template substitution with {{name}} replaced by the resolved logo name (nameOverride, or metadata.name).

Field Type Required Default Description
autoGenerate boolean AutoGenerate controls whether to auto-generate logo URLs from templates when logoUrl/darkLogoUrl are not explicitly set in this struct.
If not set, defaults to the AUTOGENERATE_LOGOS env var on the operator, which defaults to true.
nameOverride string NameOverride overrides the logo name used in template substitution.
Defaults to metadata.name.
logoUrl string LogoURL is the URL template for the light logo. Use {{name}} as a placeholder for the logo name.
Defaults to the DEFAULT_LOGO_URL env var on the operator.
darkLogoUrl string DarkLogoURL is the URL template for the dark logo. Use {{name}} as a placeholder for the logo name.
Defaults to the DEFAULT_DARK_LOGO_URL env var on the operator.

PocketIDOIDCClient.spec.federatedIdentities[]

↩ PocketIDOIDCClient.spec

OIDCClientFederatedIdentity defines a federated identity for OIDC client credentials.

Field Type Required Default Description
issuer string Issuer is the OIDC issuer for the identity.
subject string Subject is the subject for the identity.
audience string Audience is the audience for the identity.
jwks string JWKS is the URL of the identity's JWKS. Defaults to the issuer's /.well-known/jwks.json.
publicKeys []object PublicKeys are the keys that verify the identity's assertions, used instead of a JWKS URL.
replayProtection boolean false ReplayProtection requires client assertions to carry a jti and rejects replays.

PocketIDOIDCClient.spec.federatedIdentities[].publicKeys[]

↩ PocketIDOIDCClient.spec.federatedIdentities[]

OIDCClientPublicKey is a public key given inline or read from a ConfigMap or Secret.

Validation rules:

  • exactly one of value or valueFrom must be set
Field Type Required Default Description
value JSON Value is a JWK.
Type: object
valueFrom object ValueFrom reads a JWK, or a JWKS whose keys are all used, from a ConfigMap or Secret.
It is re-read on every reconcile, so key rotation is picked up on the next resync.

PocketIDOIDCClient.spec.federatedIdentities[].publicKeys[].valueFrom

↩ PocketIDOIDCClient.spec.federatedIdentities[].publicKeys[]

OIDCClientPublicKeySource selects the ConfigMap or Secret key holding a JWK or JWKS.

Validation rules:

  • exactly one of configMapKeyRef or secretKeyRef must be set
Field Type Required Default Description
configMapKeyRef ConfigMapKeySelector
secretKeyRef SecretKeySelector

PocketIDOIDCClient.spec.allowedUserGroups[]

↩ PocketIDOIDCClient.spec

NamespacedUserGroupReference selects a Pocket-ID user group, either by the PocketIDUserGroup CR that manages it or, for groups managed outside this cluster, by their name or ID in Pocket-ID.

Validation rules:

  • exactly one of name, groupName, or groupID must be set
  • namespace may only be set together with name
Field Type Required Default Description
name string Name is the name of the PocketIDUserGroup CR
MaxLength: 253
MinLength: 1
namespace string Namespace is the namespace of the PocketIDUserGroup CR.
Defaults to the PocketIDOIDCClient namespace.
MaxLength: 63
MinLength: 1
groupName string GroupName is the name of an existing user group in Pocket-ID, for groups not managed by a PocketIDUserGroup in this cluster.
MaxLength: 255
MinLength: 2
groupID string GroupID is the Pocket-ID ID of an existing user group, for groups not managed by a PocketIDUserGroup in this cluster.
MaxLength: 64
MinLength: 1

PocketIDOIDCClient.spec.apiAccess[]

↩ PocketIDOIDCClient.spec

OIDCClientAPIAccess grants a client scoped permissions on a referenced PocketIDAPI. Permissions are referenced by their key and the operator resolves them to Pocket-ID permission IDs via the PocketIDAPI status. The access flags grant a flow that selects no permissions, so setting one to false alongside a permission list is rejected rather than silently ignoring the list.

Validation rules:

  • delegatedAccess: false conflicts with delegatedPermissions; drop the permissions to revoke the flow, or remove the flag to grant them
  • clientAccess: false conflicts with clientPermissions; drop the permissions to revoke the flow, or remove the flag to grant them
Field Type Required Default Description
apiRef object yes APIRef references the PocketIDAPI granting access.
delegatedPermissions string array DelegatedPermissions are permission keys granted for the user-delegated (authorization code) flow, where the client acts on behalf of a user.
clientPermissions string array ClientPermissions are permission keys granted for the client-credentials (machine-to-machine) flow. These require a confidential client.
delegatedAccess boolean DelegatedAccess grants the user-delegated flow even with no permissions selected, e.g. a client requesting a resource that doesn't need any scopes.
Defaults to true when delegatedPermissions is non-empty.
clientAccess boolean ClientAccess grants the client-credentials flow even with no permissions selected.
Defaults to true when clientPermissions is non-empty, and requires a confidential client.

PocketIDOIDCClient.spec.apiAccess[].apiRef

↩ PocketIDOIDCClient.spec.apiAccess[]

NamespacedAPIReference references a PocketIDAPI by name and namespace.

Field Type Required Default Description
name string yes Name is the name of the PocketIDAPI CR.
namespace string Namespace is the namespace of the PocketIDAPI CR.
Defaults to the referencing resource's namespace.

PocketIDOIDCClient.spec.secret

↩ PocketIDOIDCClient.spec

OIDCClientSecretSpec defines how credentials should be stored in a Secret.

Field Type Required Default Description
enabled boolean true Enabled controls whether to create a secret with OIDC client credentials.
If false, no secret will be created. Defaults to true.
name string Name is the name of the secret to create. Defaults to metadata.name + "-oidc-credentials"
storeClientSecret boolean true StoreClientSecret controls whether the operator manages the client secret.
When false, a client created by the operator still gets its initial secret minted and stored, while an adopted client keeps its externally-managed secret and the Secret omits the client_secret key.
keys object Keys allows customization of the secret keys for each credential field.
additionalLabels object (keys:string, values:string) AdditionalLabels allows setting custom labels on the secret created by the PocketIDOIDCClient custom resource
additionalAnnotations object (keys:string, values:string) AdditionalAnnotations allows setting custom annotations on the secret created by the PocketIDOIDCClient custom resource.
Operator-managed annotations take precedence and cannot be overridden.

PocketIDOIDCClient.spec.secret.keys

↩ PocketIDOIDCClient.spec.secret

OIDCClientSecretKeys defines customizable keys for secret data fields.

Field Type Required Default Description
clientID string client_id ClientID is the key name for the OIDC client ID.
clientSecret string client_secret ClientSecret is the key name for the OIDC client secret.
issuerUrl string issuer_url IssuerURL is the key name for the OIDC issuer URL.
callbackUrls string callback_urls CallbackURLs is the key name for the callback URLs.
logoutCallbackUrls string logout_callback_urls LogoutCallbackURLs is the key name for the logout callback URLs.
discoveryUrl string discovery_url DiscoveryURL is the key name for the OIDC discovery URL.
authorizationUrl string authorization_url AuthorizationURL is the key name for the OIDC authorization endpoint URL.
tokenUrl string token_url TokenURL is the key name for the OIDC token endpoint URL.
userinfoUrl string userinfo_url UserinfoURL is the key name for the OIDC userinfo endpoint URL.
jwksUrl string jwks_url JwksURL is the key name for the OIDC JWKS (JSON Web Key Set) endpoint URL.
endSessionUrl string end_session_url EndSessionURL is the key name for the OIDC end session (logout) endpoint URL.
resource string resource Resource is the key name for the audience to request tokens for, taken from the APIs in apiAccess. It also prefixes the per-API key "_".
scopes string scopes Scopes is the key name for the space-delimited scopes apiAccess grants the client-credentials flow. It also prefixes the per-API key "_".

PocketIDOIDCClient.spec.scim

↩ PocketIDOIDCClient.spec

SCIMSpec configures SCIM provisioning for the OIDC client. Pocket ID will push user/group changes to the given endpoint.

Field Type Required Default Description
endpoint string yes Endpoint is the URL of the external SCIM service provider.
tokenSecretRef SecretKeySelector TokenSecretRef references a Kubernetes Secret key containing the bearer token used to authenticate with the SCIM endpoint.
If omitted, no Authorization header is sent.

PocketIDOIDCClient.spec.clientSecretRotation

↩ PocketIDOIDCClient.spec

ClientSecretRotation configures automatic, scheduled regeneration of the OIDC client secret. When enabled, a rotation trigger is required: set interval, window (secret rotates once per window opening), or both (interval-driven, confined to the window). Instance-wide min-spacing is honored in every mode.

Validation rules:

  • enabled rotation requires interval, window, or both
  • window.closesAfter must not exceed interval
Field Type Required Default Description
enabled boolean yes false Enabled controls whether automatic rotation is active.
interval Duration Interval is the minimum time between rotations (e.g. "720h" for 30 days). Must be between 1h and 8760h. When omitted, rotation is driven entirely by window (which then becomes required) and the secret rotates once per window opening.
window object Window restricts rotations to a recurring maintenance window. When interval is set, rotations fire as soon as the interval and global min-spacing are satisfied, confined to the window when one is configured.
When interval is omitted, the window opening is the trigger and the secret rotates once per opening subject to min-spacing.

PocketIDOIDCClient.spec.clientSecretRotation.window

↩ PocketIDOIDCClient.spec.clientSecretRotation

RotationWindow restricts rotations to a recurring time window.

Field Type Required Default Description
opens string yes Opens is a standard 5-field cron expression (e.g. "0 1 * * *" for 1am daily, local TZ).
closesAfter Duration yes ClosesAfter is how long the window stays open after each cron fire. Minimum 5m.

PocketIDOIDCClient.status

PocketIDOIDCClientStatus defines the observed state of PocketIDOIDCClient.

Field Type Required Default Description
clientID string ClientID is the ID assigned by Pocket-ID.
name string Name is the resolved name from Pocket-ID.
clientType string ClientType is how the client was registered in Pocket-ID: "standard" or "cimd".
For a "cimd" client the operator manages only the fields Pocket-ID persists on an admin update; the rest are owned by its OAuth Client ID Metadata Document.
createdAt string CreatedAt is the creation timestamp from Pocket-ID
callbackUrls string array CallbackURLs are the current callback URLs from Pocket-ID
logoutCallbackUrls string array LogoutCallbackURLs are the current logout callback URLs from Pocket-ID
allowedUserGroupIDs string array AllowedUserGroupIDs are the resolved group IDs assigned to the client
managedAPIPermissionIDs string array ManagedAPIPermissionIDs are the Pocket-ID API permission IDs the operator last pushed as this client's API access (both delegated and client-credentials).
managedAPIs string array ManagedAPIs are the Pocket-ID API IDs the operator last granted this client.
cimdGrantedAPIs string array CIMDGrantedAPIs are the resources of APIs reachable through their cimdAccess setting rather than this client's own grant; revoke it on the PocketIDAPI, not via spec.apiAccess. Only populated for cimd clients.
pkceSupported boolean PKCESupported indicates Pocket-ID observed the client using PKCE during an authorization flow while spec.pkceEnabled is false, signalling PKCE can be enabled.
logoUrl string LogoURL is the light logo URL the operator last successfully applied to Pocket-ID.
logoReachable boolean LogoReachable reports whether Pocket-ID could fetch and store the light logo from the URL the spec resolves to.
darkLogoUrl string DarkLogoURL is the dark logo URL the operator last successfully applied to Pocket-ID.
darkLogoReachable boolean DarkLogoReachable reports whether Pocket-ID could fetch and store the dark logo from the URL the spec resolves to.
scimProviderID string SCIMProviderID is the pocket-id ID of the SCIM service provider for this client, if configured.
conditions Condition array Conditions represent the current state of the PocketIDOIDCClient resource.
lastRotatedAt Time LastRotatedAt is the time the client secret was last regenerated by the operator. Used to determine when the next scheduled rotation is due.
clientSecretSourceVersion string ClientSecretSourceVersion identifies the spec.clientSecretRef source last pushed to Pocket-ID. Pocket-ID stores the secret hashed and never returns it, so this is how the operator detects that the referenced Secret changed and needs pushing again.