Zitadel

Prerequisites

Complete the preparation checklist.

Application setup

Use Zitadel Configurator 1.11.1 or later with configurator.identity_service_base_url: https://api.<platform-host>/identity. It registers https://api.<platform-host>/identity/callback, creates the management credential, and writes zitadel-identity-service-env. Add that Secret to identity.extraEnvSecrets.

Without the Configurator, follow Manual registration.

Collected values

With the Configurator, the application Client ID, issuer, application key, and management key are already in zitadel-identity-service-env. You do not need to copy or re-encode them. The application key authenticates the browser-login application; the separate management key reads organizations, people, and grants. From Configurator 1.11.0, that key belongs to the Registry service's Zitadel user, RegistryServiceMachineUser. Add it to each organization to import as described in Setting up a new organization.

Installation configuration

For a Configurator installation, add only its Secret and retain the provisioner:

istari-values.yaml (excerpt)

provisioner:
  enabled: true
identity:
  extraEnvSecrets:
    - zitadel-identity-service-env

The Secret supplies the OIDC settings. Leave identity.idpMigration.enabled unset to retain the automatic import.

Account preparation

The Zitadel import reconciles organizations, people, and tenant administrators on every install and upgrade. Check the import log and resulting tenants.

See account import commands and administrator setup.

Verification

Check that an organization's imported people sign in to its tenant, that tenant administrators receive their local roles, and that repeated imports retain principal IDs. Test refresh and the discovered upstream logout endpoint as well as local session revocation.

Limitations

Only organizations the management user belongs to are imported. Missing credentials or partial reads can leave an incomplete import without failing the upgrade; see Checking the import.

Manual registration

Without the Configurator, register the application yourself:

1. In the Zitadel console, open the Istari project and create a new application:
   • Type: Web
   • Authentication method: Private Key JWT (recommended; Basic with a client secret is also supported — see OIDC_CLIENT_AUTH_METHOD)
   • Grant types: Authorization Code and Refresh Token
   • Redirect URI: https://api.<customer_istari_fqdn>/identity/callback
   • Post-logout redirect URIs: https://<customer_istari_fqdn> and any additional approved frontend addresses
2. Record the generated Client ID — this becomes ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_CLIENT_ID.
3. On the application's Keys tab, add a new key of type JSON and download the key file; base64-encode it verbatim — this becomes ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_PRIVATE_KEY:

base64 < identity-service-app-key.json | tr -d '\n'

4. Create the management key for organization imports:

   1. Create a machine user in your Zitadel organization.
   2. Give the machine user ORG_OWNER_VIEWER membership in each organization to import, including its own.
   3. Create a JSON key for the machine user and base64-encode the file, as you did for the application key in step 3. It becomes ISTARI_DIGITAL_IDENTITY_SERVICE_ZITADEL_MANAGER_KEY.

   If you turn the import off and skip this step, administrators cannot manage keys for a person the Identity Service has no record of, such as someone who has never signed in.

Without the Configurator, add these values to the istari-identity secret (Identity Service Secret):

Key	Value
ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_CLIENT_ID	The Client ID from step 2
ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_PRIVATE_KEY	The encoded key from step 3
ISTARI_DIGITAL_IDENTITY_SERVICE_ZITADEL_MANAGER_KEY	The encoded key from step 4, unless you turn the import off
ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_ISSUER	https://zitadel.<customer_istari_fqdn>
ISTARI_DIGITAL_IDENTITY_SERVICE_BASE_URL	https://api.<customer_istari_fqdn>/identity

Set identity.extraEnvSecrets: [] if all upstream settings are in istari-identity; retain any other required Secrets. Continue with Create the Identity Service Secret.

Finding your Zitadel organization ID

Several steps need the organization ID — a long numeric identifier (typically 18 digits), not a name and not a project resource ID.

• In the Zitadel console, switch to the instance view and open Organizations: the list shows each organization's Id column — that's the value.
• Definitive check via API, using any PAT or service-account token for a user in that organization:

curl -s -H "Authorization: Bearer <token>" https://zitadel.<customer_istari_fqdn>/management/v1/orgs/me

Read org.id from the response. Use it to identify an imported tenant in administrator commands.