Set up Identity Service with the provisioner

This guide describes how to install and configure the Identity Service using the Istari Platform Helm chart. The provisioner included in the chart automatically generates the Identity Service keys and platform service credentials.

1. Configure the identity provider

Follow the setup guide for your identity provider.

For Zitadel, use Zitadel Configurator and add its credential Secret to your values:

istari-values.yaml (excerpt)

identity:
  extraEnvSecrets:
    - zitadel-identity-service-env

Without the Configurator, follow manual Zitadel application registration.

For another provider, use its guide's values and credential Secret.

2. Create the Identity Service Secret

Create the istari-identity Secret with the database connection string and any credentials required by your provider guide. The provisioner generates the platform keys and credentials.

3. Install with the provisioner enabled

Add these settings alongside the provider configuration from step 1:

istari-values.yaml (excerpt)

common:
  mainFqdn: "<customer_istari_fqdn>"
provisioner:
  enabled: true

Merge these values with your existing platform configuration. Leave the Identity Service, client integration, API Gateway, and provisioner enabled.

Download the chart, then install with your complete values file:

helm upgrade --install -f istari-values.yaml istari istari-platform-7.1.0.tgz

For upgrades from chart 6.x, follow the upgrade instructions.

Preserve the provisioner's state and generated Secrets across upgrades.

4. Prepare tenants and people

Follow Tenants and access to verify the Zitadel import or prepare accounts for another provider before users sign in.

If you use Secure Connections, also complete Secure Connection Service agent.

5. Create the first platform administrator

Grant the platform administrator role to the first administrator. They can then appoint other administrators in the Platform Admin Console.

6. Verify the installation

Check the provisioner and service status. Adjust resource names and namespace for your installation:

kubectl get jobs -l app.kubernetes.io/component=provisioner
kubectl rollout status deployment/istari-identity
kubectl rollout status deployment/istari-fileservice
kubectl rollout status deployment/istari-frontend
curl -fsS https://api.<customer_istari_fqdn>/identity/health/readiness
curl -fsS https://api.<customer_istari_fqdn>/identity/.well-known/openid-configuration
curl -fsS https://api.<customer_istari_fqdn>/identity/.well-known/jwks.json

The provisioner Job should complete, the Deployments should be Ready, and the HTTP checks should return 200. If a Secret is missing, check kubectl logs job/<provisioner-job-name>.

Sign in with a prepared account and check its tenant, resource access, and sign-out. Confirm the first administrator can open the Platform Admin Console. Verify client registration for key and agent authentication.

Reference and manual setup

For installations without the provisioner, see Manual setup.

See the configuration reference for overrides and the API Gateway reference for routing. To change providers, see Switching from Zitadel.

Troubleshooting

Zitadel rejects the Registry credential (401, 403, invalid_grant, or invalid_client). Check FILE_SERVICE_ZITADEL_USER_MANAGER_SECRET in the Registry Secret. Replace an expired or invalid key, then restart Registry.

Zitadel Configurator 1.11.0 and later: replace the key in two places

These versions set the Identity Service's ZITADEL_MANAGER_KEY, otherwise a separate key, to this registry key. If you run one of them, put the new key in ZITADEL_MANAGER_KEY too.

Registry reports an Identity Service authentication or agent-provisioning error. Check its provisioner-generated istari-provisioner-registry-credentials Secret, or its manually supplied credential, and the matching public key in Identity Service. Use Verify a Registration to test them. Check the Identity Service logs for other failures.