Sign-in clients

coming The provisioner’s first release is coming, and the product charts run it from their next releases. Until then, register each product’s clients by hand as its guide describes.

Every product that signs people in needs a client at the identity provider: a client id, a secret, the addresses the provider may send people back to, and its roles. A product that calls another product, such as TinyConductor reading from TinyVault, needs a machine client too.

How it works

 chart values ──► what the product needs ──► provision Job ──► identity provider
                                                  │            clients, roles, groups
                                                  ▼
                                    Secret <product>-oidc-<client>
                                    (client-id, client-secret, issuer)
                                                  │
                                                  ▼
                                        the product's pods read it

1. When you install or upgrade a product, its chart first runs the database migration, then the provisioning Job, and only then the product’s pods.
2. The Job creates what is missing at the identity provider, corrects what was changed by hand, and removes what this release no longer needs.
3. It writes one Secret per client, for example tinyconductor-oidc-console, with the keys client-id, client-secret and issuer. A machine client’s Secret also has token-url and audience.

The product reads only that Secret. Whether the provisioner wrote it or you did, the product works the same.

If the Job fails, the upgrade stops before any new pod starts, and the running pods keep serving. Read why with kubectl -n <namespace> logs job/<product>-provision.

What you set

Provisioning is on by default. It needs the issuer and a credential that may register clients:

kubectl -n tinyblox create secret generic guard-provisioning \
  --from-file=credential=./provisioning-key.txt

publicUrl: conductor.example.com
identity:
  issuer: https://guard.example.com/auth/v1
  provisioning:
    provider: tinyguard               # tinyguard or keycloak
    credential:
      existingSecret: guard-provisioning

Every product chart has the same identity block:

Key	Default	Meaning
identity.issuer		The identity provider’s issuer address.
identity.clients.<name>.extraRedirectUris		More addresses people may be sent back to after sign-in.
identity.clients.<name>.enabled	true	false: do not register this client.
identity.groups	[]	Groups to create. Prefer the access file for people and their permissions.
identity.provisioning.enabled	true	false: you register the clients and create the Secrets yourself.
identity.provisioning.provider	tinyguard	tinyguard or keycloak.
identity.provisioning.adminUrl	the issuer’s address	Where the provider’s administration API is reached from inside the cluster.
identity.provisioning.credential.existingSecret		The Secret holding the credential. Required while provisioning is on.
identity.provisioning.deleteOnUninstall	true	Remove the product’s clients and Secrets on helm uninstall.
identity.provisioning.waitTimeoutSeconds	300	How long to wait for an identity provider that is still starting.

To see exactly what will be registered, render the chart: helm template … --show-only templates/provision.yaml.

The credential

Give it only the rights it needs. provision describe --whoami checks a credential and fails when it may do more.

TinyGuard: an API key in the tenant the product signs in to, stored as <name>$<secret> under the key credential, with exactly these rights:

Area	Rights
clients	read, create, update, delete
secrets	read, update
roles	read, create, update, delete
groups	read, create, update, delete

Never tenants, api_keys or users. Give it an expiry date.

Keycloak: a confidential client with service accounts enabled, in the product’s realm, with the realm-management roles view-clients and manage-clients (plus query-groups, view-users and manage-users only when you create groups or bind roles to them). Store its id and secret under client-id and client-secret.

Registering clients by hand

Use this when you have no administrator rights at your identity provider, or it is not TinyGuard or Keycloak.

1. Switch provisioning off:

   identity:
     issuer: https://login.example.com/realms/acme
     provisioning:
       enabled: false

2. Register each client the product’s guide lists, with its redirect addresses, grant types and scopes.

3. Create one Secret per client:

   kubectl -n tinyblox create secret generic tinyconductor-oidc-console \
     --from-literal=issuer=https://login.example.com/realms/acme \
     --from-literal=client-id=tinyconductor \
     --from-file=client-secret=./client-secret.txt

To switch provisioning on later, delete these Secrets first: the provisioner never overwrites a Secret it did not write.

Rotating a client secret

Client secrets change only when you ask:

provision rotate console --overlap-hours 4

With TinyGuard the old secret keeps working for the overlap you give (1 to 24 hours), so the product has time to pick up the new one from its Secret before the old one stops working. Keycloak replaces the secret at once, with no overlap. See Commands for running it.