Skip to content

oidc command group

oidc manages the global administrator OIDC endpoint of {{ product_name }}. This is the single OpenID Connect configuration created during one-time bootstrap with init; the commands here let you inspect it, apply partial updates, and move it between environments through binary backups.

The introspection client secret is never displayed or written to a backup. oidc view reports only whether a secret is configured, and oidc backup redacts it server-side. A new secret is supplied only through oidc update --oidc-introspection-client-secret, where the backend seals it before persistence.

Remote gRPC client

Every command in this group talks to a remote server. Before running them, create a host profile with profile hosts create and authenticate with profile authn login. Use the global -p/--profile option (default default-admin), placed before the command path, to select a host profile for a single invocation.

Commands in this group

Command Purpose
oidc view Display the administrator OIDC configuration
oidc update Apply a partial update to the OIDC configuration
oidc backup Back up the OIDC configuration to a binary .pb file
oidc restore Restore the OIDC configuration from a binary .pb backup

Group help

bin/admin.sh oidc --help

oidc view

Displays the current administrator OIDC configuration. The introspection client secret is never shown; the reply reports only whether one is configured.

Syntax

bin/admin.sh oidc view [options]

Required options

This command has no command-specific required options.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh oidc view -f json

oidc update

Applies a partial update to the administrator OIDC configuration. The command first reads the current configuration, applies only the options you supply on top (read-modify-write), and sends the merged configuration back. Any option left unset preserves its stored value. Supplying --oidc-introspection-client-secret replaces the secret (sealed server-side); omitting it keeps the stored secret unchanged.

Syntax

bin/admin.sh oidc update [options]

Required options

This command has no command-specific required options. Supply only the fields you want to change.

Optional options

Show optional options
Option Default Description
--oidc-issuer-claim unchanged OpenID issuer claim
--oidc-audience-claim unchanged OpenID audience claim
--oidc-token-mode unchanged Token validation mode: OIDC_TOKEN_MODE_JWT_LOCAL, OIDC_TOKEN_MODE_JWT_USERINFO, OIDC_TOKEN_MODE_OPAQUE_INTROSPECT, or OIDC_TOKEN_MODE_AUTO
--[no-]oidc-use-discovery unchanged Use OIDC discovery
--[no-]oidc-allow-user-info-fallback unchanged Allow OIDC UserInfo fallback
--[no-]oidc-allow-introspection-fallback unchanged Allow OIDC token introspection fallback
--oidc-clock-skew-seconds unchanged Clock skew allowance in seconds
--oidc-connect-timeout-ms unchanged Connect timeout in milliseconds
--oidc-read-timeout-ms unchanged Read timeout in milliseconds
--oidc-discovery-url-override unchanged OpenID discovery URL override
--oidc-jwks-url-override unchanged OpenID JWKS URL override
--oidc-user-info-url-override unchanged OpenID UserInfo URL override
--oidc-introspection-url-override unchanged OpenID introspection URL override
--oidc-introspection-client-id unchanged OpenID introspection client id
--oidc-introspection-client-secret unchanged OpenID introspection client secret (plaintext; sealed server-side)
-f, --out-format YAML Output format: JSON or YAML

Validation rules

  • Every option is optional. Options you omit leave the corresponding stored field unchanged.
  • Boolean toggles use picocli negation: pass --oidc-use-discovery to enable or --no-oidc-use-discovery to disable (and likewise for the two fallback toggles).
  • --oidc-introspection-client-secret is carried as plaintext for the backend to seal; when it is omitted the stored secret is preserved, never cleared.
  • --oidc-token-mode accepts only the four enum values listed above.

Example (rotate token mode and timeouts)

bin/admin.sh oidc update \
  --oidc-token-mode OIDC_TOKEN_MODE_JWT_LOCAL \
  --oidc-connect-timeout-ms 5000 \
  --oidc-read-timeout-ms 10000 \
  --oidc-clock-skew-seconds 60 \
  -f json

Example (set introspection client and disable discovery)

bin/admin.sh oidc update \
  --no-oidc-use-discovery \
  --oidc-introspection-url-override https://idp.example.com/oauth2/introspect \
  --oidc-introspection-client-id alpine-admin \
  --oidc-introspection-client-secret 's3cr3t' \
  --oidc-allow-introspection-fallback \
  -f yaml

oidc backup

Backs up the administrator OIDC configuration to a binary protobuf (.pb) payload. The backup never contains the introspection client secret (it is redacted server-side). The payload can be written to a file or printed to the console as Base64.

Syntax

bin/admin.sh oidc backup [options]

Required output mode options (choose exactly one)

Option Description Example
-o, --output-file Write the binary .pb backup to a file (creates or truncates) -o ./admin-oidc.pb
-s, --print-to-screen Print the backup to the console as Base64 -s true

Validation rules

  • The output destination is a required argument group with multiplicity 1: supply exactly one of -o/--output-file or -s/--print-to-screen.
  • File output is raw binary protobuf; console output is Base64-encoded so it can be captured from the terminal.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format for error reporting: JSON or YAML

Example

bin/admin.sh oidc backup -o ./admin-oidc.pb

oidc restore

Restores the administrator OIDC configuration from a binary protobuf (.pb) backup produced by oidc backup. The stored introspection client secret is preserved unless the backup carries one.

Syntax

bin/admin.sh oidc restore [options]

Required options

Option Description Example
-i, --input-file Binary .pb backup file to restore -i ./admin-oidc.pb

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh oidc restore -i ./admin-oidc.pb -f json

Standard CLI options are documented in Global options.

Typical workflow

  1. Inspect the current endpoint with oidc view.
  2. Apply targeted changes with oidc update (only the supplied fields change).
  3. Capture a portable snapshot with oidc backup -o ./admin-oidc.pb.
  4. Promote the snapshot into another environment with oidc restore -i ./admin-oidc.pb.

FAQ

Does oidc view show the introspection client secret?

No. The secret is never displayed. oidc view reports only whether a secret is configured.

Will oidc update erase fields I do not pass?

No. oidc update performs a partial merge: it reads the current configuration and changes only the options you supply, leaving every unset field unchanged.

What format does oidc backup produce?

A binary protobuf (.pb) payload. With -o/--output-file it is written as raw binary; with -s/--print-to-screen it is printed to the console as Base64. The introspection client secret is redacted from every backup.

How do I rotate the introspection client secret?

Run oidc update --oidc-introspection-client-secret with the new plaintext value. The backend seals it before persistence. Omitting the option keeps the stored secret unchanged.