Skip to main content

Setup Wizard Validation

When you configure Symphony for the first time, the setup wizard runs a series of validation checks against your DNS and OIDC configuration before allowing you to start the instance. This page explains each check, what causes it to fail, and how to resolve it.

Checks report one of four statuses:

  • Pass — the check succeeded.
  • Info — the check passed but has a suggestion (e.g. a client secret that could not be verified automatically).
  • Warning — the check could not fully confirm the configuration, but setup can proceed. You should investigate the cause.
  • Fail — the check found a configuration error that should be corrected before proceeding. You can override failures, but the instance may not work correctly.

All validation checks are logged to the Symphony container logs at the appropriate level (info, warn, error) with full diagnostic detail, including resolution guidance. A summary line at the end of each validation reports the count of pass, warn, fail, and info results.

A copy diagnostics button (clipboard icon) appears in the OIDC section header after validation runs. It copies all check results—including passes—to the clipboard in a text format suitable for sharing with support or including in bug reports.

DNS Checks​

The DNS validation confirms that the hostname you entered resolves correctly and routes back to this specific Symphony instance.

DNS Resolution​

What it checks: Whether the hostname resolves to at least one IP address via DNS.

Common causes of failure:

  • No DNS record exists for the hostname.
  • The DNS record was recently created and has not propagated yet.
  • The hostname is misspelled.
  • (Docker Compose) The hostname is listed in the host's /etc/hosts but not in DNS, and the symphony container cannot inherit the host file. The shipped Docker bundle automatically aliases EXTERNAL_HOSTNAME to the nginx service inside the compose network so this scenario is handled out-of-the-box; if you have customised the compose file, ensure the alias is preserved.

How to resolve:

  1. Create a DNS A record (or CNAME record) pointing the hostname to the IP address of the server or load balancer where Symphony is running.
  2. Verify the record from the server itself: 
    nslookup <hostname>
  3. If you recently created the record, wait for DNS propagation (typically a few minutes, but up to the TTL of any cached negative response).
  4. (Docker Compose) Confirm the nginx service includes ${EXTERNAL_HOSTNAME} under networks.symphony.aliases in your docker-compose.yml (or that you have not removed it).

DNS Connectivity​

What it checks: Whether the resolved IP address accepts HTTPS connections on port 443 and responds with a valid Symphony response.

Common causes of failure:

  • The reverse proxy (nginx) is not running or not listening on port 443.
  • A firewall is blocking inbound HTTPS traffic to the resolved address.
  • A load balancer is not forwarding traffic to this instance.
  • The reverse proxy returned an unexpected HTTP status code (e.g. 502 Bad Gateway).

How to resolve:

  1. Verify that nginx (or your reverse proxy) is running: 
    systemctl status nginx     # Linux
    docker ps                  # Docker
    kubectl get pods           # Kubernetes
  2. Test connectivity from the server to itself: 
    curl -sk https://<hostname>/api/v1/nonce
  3. Check firewall rules to ensure port 443 is open for inbound traffic.
  4. If using a load balancer, verify that it has a healthy target pointing to this instance.

Wrong Instance​

What it checks: Whether the hostname routes to this specific Symphony instance (not a different server at the same address).

Common causes of failure:

  • The DNS record points to a different server running on the same host or IP.
  • A load balancer is distributing traffic across multiple instances, and the validation request reached a different one.
  • A CDN or proxy is caching or intercepting responses.

How to resolve:

  1. Verify that the DNS record points to the correct IP address for this instance.
  2. If using a load balancer with multiple backends, ensure that all backends are Symphony instances in the same deployment, or configure the load balancer to route to a single instance during setup.
  3. If a CDN or caching proxy is in front of Symphony, ensure it is configured to pass through API requests without caching.

OIDC Checks​

The OIDC validation contacts your identity provider and verifies that it meets the requirements for Symphony authentication. For provider-specific setup instructions, see the OIDC Configuration guide.

Discovery Endpoint​

What it checks: Whether the OIDC discovery document at <issuer>/.well-known/openid-configuration is reachable and contains valid JSON.

Common causes of failure:

  • The issuer URL is incorrect or misspelled.
  • The issuer URL includes the https:// scheme prefix (Symphony adds this automatically — enter only the domain and path).
  • The identity provider is not reachable from this server's network.
  • In Docker or Kubernetes, the provider's public hostname does not resolve from inside the container.
  • (Docker Compose) The OIDC provider hostname is listed in the host's /etc/hosts but is not in DNS. Containers do not inherit the host file, so the lookup fails inside the symphony container.

How to resolve:

  1. Test the discovery URL manually from the server: 
    curl -s https://<issuer>/.well-known/openid-configuration | head -20
  2. Verify the issuer URL format for your provider:
    • Keycloak: auth.example.com/realms/<realm>
    • Auth0: <tenant>.auth0.com/ (trailing slash required)
    • Okta: <org>.okta.com/oauth2/<server-id>
    • Entra ID: login.microsoftonline.com/<tenant-id>/v2.0
  3. If the provider uses a different internal address (e.g. a Kubernetes service name), set the OIDC_INTERNAL_BASE_URL environment variable: 
    OIDC_INTERNAL_BASE_URL=http://keycloak-service:8080/realms/symphony
  4. (Docker Compose) For an external OIDC provider whose hostname is only in the host's /etc/hosts, add a mapping inside the symphony container by copying docker-compose.override.yml.example to docker-compose.override.yml and adding a host:ip entry under services.symphony.extra_hosts. See Docker Compose installation.

Required Endpoints​

What it checks: Whether the discovery document contains the three endpoints required by Symphony: authorization_endpoint, token_endpoint, and jwks_uri.

Common causes of failure:

  • The identity provider realm or tenant is not fully configured.
  • The discovery document was served by a non-OIDC endpoint.

How to resolve:

  1. Inspect the discovery document to see which endpoints are present: 
    curl -s https://<issuer>/.well-known/openid-configuration | \
      jq '{authorization_endpoint, token_endpoint, jwks_uri}'
  2. If endpoints are missing, check your identity provider's realm or tenant configuration. Most providers include these endpoints automatically when a realm is properly set up.

Issuer Match​

What it checks: Whether the issuer field in the discovery document exactly matches the configured issuer URL.

Common causes of failure:

  • A trailing slash mismatch (e.g. https://auth.example.com/ vs https://auth.example.com).
  • A path mismatch (e.g. missing /realms/<realm> for Keycloak).
  • The provider returns a different hostname than expected.

How to resolve:

  1. Fetch the discovery document and check the issuer field: 
    curl -s https://<issuer>/.well-known/openid-configuration | jq .issuer
  2. Enter the issuer URL exactly as returned, minus the https:// prefix.
  3. Note that some providers require trailing slashes (Auth0) while others do not (Keycloak). Match exactly what the provider returns.

RS256 Signing​

What it checks: Whether the provider supports the RS256 algorithm for signing ID tokens and access tokens.

Common causes of failure:

  • The provider is configured to use a different algorithm (e.g. HS256, ES256).
  • The signing algorithms are not advertised in the discovery document.

How to resolve:

  1. If RS256 is not listed, configure your identity provider to sign tokens with RS256:
    • Keycloak: Under Realm Settings → Keys, ensure an RSA key provider is active.
    • Auth0: Under APIs → Settings, set Signing Algorithm to RS256.
    • Okta: RS256 is the default; verify under Security → API → Authorization Server → Access Policies.
  2. If the provider does not advertise algorithms but defaults to RS256 (shown as a warning), setup can proceed — verify after first login.

PKCE Support​

What it checks: Whether the provider supports Proof Key for Code Exchange (PKCE) with the S256 challenge method.

Common causes of failure:

  • PKCE is not enabled for the client in the identity provider.
  • The provider supports PKCE but does not advertise it in the discovery document.

How to resolve:

  1. Enable PKCE in your provider's client configuration:
    • Keycloak: Client → Advanced Settings → Proof Key for Code Exchange Code Challenge Method → S256.
    • Auth0: PKCE is enabled by default for SPA clients.
    • Okta: PKCE is enabled by default for SPA clients.
    • Entra ID: PKCE is supported automatically for SPA platforms.
  2. If PKCE is shown as a warning (not advertised), setup can proceed — most providers support it even when not listed.

Scopes​

What it checks: Whether the provider supports the openid and offline_access scopes.

Common causes of failure:

  • The authorization server does not have these scopes enabled.
  • The scopes are restricted by a policy or access rule.
  • Google Workspace does not support offline_access (use access_type=offline instead).

How to resolve:

  1. Verify available scopes in your provider's admin console:
    • Keycloak: Client Scopes page in the realm.
    • Auth0: APIs → Permissions / Scopes.
    • Okta: Security → API → Authorization Server → Scopes.
  2. If offline_access is not available, users may need to re-authenticate more frequently but the system will still function.

JWKS Endpoint​

What it checks: Whether the JWKS (JSON Web Key Set) endpoint is reachable and contains at least one signing key.

Common causes of failure:

  • The JWKS endpoint URL in the discovery document is unreachable from this server.
  • The identity provider has no signing keys configured.
  • Network issues between this server and the JWKS endpoint.

How to resolve:

  1. Test the JWKS endpoint directly: 
    curl -s <jwks_uri> | jq '.keys | length'
  2. If the endpoint is unreachable but the discovery endpoint works, the JWKS may be on a different host or port. Ensure network access.
  3. If the key set is empty, generate or import an RSA signing key in your provider's key management settings.

Authorization Code Flow​

What it checks: Whether the provider supports response_type=code, which is required for the authorization code flow used by the browser UI.

Common causes of failure:

  • The Standard flow (authorization code) is not enabled for the client.
  • The provider only supports implicit flow or other grant types.

How to resolve:

  1. Enable the authorization code flow in your provider's client settings:
    • Keycloak: Client → Settings → enable Standard flow.
    • Auth0: SPA applications use authorization code by default.
    • Okta: Ensure the application type is Single-Page Application.
    • Entra ID: Add a Single-page application platform.

Userinfo Endpoint​

What it checks: Whether the discovery document includes a userinfo_endpoint.

Common causes of failure:

  • Some minimal OIDC providers do not implement the userinfo endpoint.

How to resolve:

This is a non-critical warning. The userinfo endpoint provides user profile information (display name, email) that improves the UI experience. If your provider does not offer one, user information will be derived from the ID token claims instead.

Grant Type​

What it checks: Whether the provider supports the authorization_code grant type.

Per the OpenID Connect Discovery specification, grant_types_supported is an optional field. When a provider omits it (as Auth0 does), the specification defines the default as ["authorization_code", "implicit"], so this check passes automatically.

A warning is only shown when the provider explicitly lists its grant types and authorization_code is not among them.

Common causes of failure:

  • The provider explicitly advertises grant types but does not include authorization_code.

How to resolve:

  1. Enable the authorization_code grant type in your provider's client settings. This is usually labelled "Standard flow" (Keycloak) or "Authorization Code" (Auth0, Okta).

CA Certificate​

What it checks: When the OIDC_CA_CERT environment variable is set, this check verifies that the file exists, is readable, and contains valid PEM-encoded certificates. This check only appears when OIDC_CA_CERT is configured.

Common causes of failure:

  • The file path is incorrect or the file does not exist.
  • The process does not have read permission on the file.
  • The file is not in PEM format (must begin with -----BEGIN CERTIFICATE-----).

How to resolve:

  1. Verify the file path and permissions.
  2. Ensure the file contains one or more PEM-encoded CA certificates.

TLS Certificate​

What it checks: Whether a valid TLS certificate is presented by the identity provider, and whether it expires within the next 30 days. When TLS verification fails, the error detail includes the certificate's subject, issuer, and expiry date to help identify the problematic certificate.

This check is skipped when an internal base URL is configured (since TLS is handled by the internal network) or when TLS verification is disabled.

Common causes of failure:

  • The identity provider uses a self-signed certificate.
  • The certificate is issued by a private CA not trusted by this server.
  • The certificate is nearing expiration.

How to resolve:

  1. Self-signed or private CA: Set the OIDC_CA_CERT environment variable to the file path of the CA certificate (PEM format): 
    OIDC_CA_CERT=/etc/symphony/certs/oidc-ca.pem
  2. Expiring certificate: Renew the certificate on the identity provider before it expires. Expired certificates will prevent authentication.
  3. Disable TLS verification: Use the Disable TLS Verification switch next to the OIDC Issuer field in the setup wizard. This setting is saved to the configuration and applies to subsequent operation. This is less secure and should only be used in development or test environments.

Identity Scopes​

What it checks: Whether the provider supports the email and profile scopes, which provide user identity claims in tokens.

Common causes of failure:

  • The scopes are not enabled in the authorization server.
  • The provider supports only one of the two scopes.

How to resolve:

  1. Enable both scopes in your provider's configuration. Without them, user display names and email addresses may not appear in the UI.
  2. If only one scope is available, the system will still function but with reduced user profile information.

Client ID​

What it checks: Whether the OAuth Client ID and UI Client ID are recognized by the identity provider, and optionally whether client secrets are valid.

This check works by sending a client_credentials probe to the provider's token endpoint. When the provider responds with an error indicating the grant type is not allowed for the client (such as unsupported_grant_type or unauthorized_client), it confirms the client exists. When the provider responds with invalid_client or access_denied, it indicates the client ID was not recognized.

When a client secret is provided:

  • If the provider supports client_credentials and returns a 200 with a JWT access token, the credentials are confirmed valid.
  • If the provider rejects the grant type before checking the secret (common with SPA clients), the secret cannot be verified automatically and an info hint is shown on the field.
  • If the provider returns invalid_client, the secret is likely incorrect.

Common causes of warning:

  • The client ID is misspelled.
  • The client has not been created in the identity provider.
  • The client was created in a different realm or tenant.
  • A client secret was provided but is incorrect.

How to resolve:

  1. Verify the client ID in your identity provider's admin console:
    • Keycloak: Clients page in the correct realm.
    • Auth0: Applications page.
    • Okta: Applications → Applications list.
    • Entra ID: App registrations page.
  2. Ensure you have created two client registrations — a public UI client and a confidential API client. See OIDC Configuration for details.
  3. Copy the client ID exactly from the provider — avoid extra spaces or invisible characters.
  4. If a client secret is required (e.g. Auth0 Machine-to-Machine apps), enter it in the Client Secret field next to the Client ID.
Keycloak note

During validation, the client_credentials probe generates CLIENT_LOGIN_ERROR entries in Keycloak's event log. These are expected and harmless — the probe intentionally uses a grant type that public clients cannot serve in order to confirm the client is registered. No action is needed for these log entries.

API Audience​

What it checks: Whether the identity provider will issue JWT access tokens (rather than opaque tokens) for the expected API audience.

This check runs when a Client ID with a secret is provided and the external hostname is set. It sends a client_credentials request with audience=https://<hostname>/api/v1 and checks whether the returned access token is a JWT (three dot-separated parts).

When the audience cannot be verified automatically (because the client does not support client_credentials), an info hint provides provider-specific guidance on configuring the audience.

Common causes of failure:

  • No API or resource server is registered in the identity provider with the expected audience identifier.
  • The client application is not authorized for the API.
  • The provider is issuing opaque tokens instead of JWTs (common when using the wrong authorization server in Okta, or when no API is registered in Auth0).

How to resolve:

  1. Auth0: Go to Applications → APIs, create an API with identifier https://<hostname>/api/v1, and authorize your client application under the Machine to Machine Applications tab.
  2. Okta: Go to Security → API → your authorization server → Settings and set the Audience field to https://<hostname>/api/v1. You must use a custom authorization server (e.g. default)—the org authorization server issues opaque tokens that cannot be validated.
  3. Entra ID: Go to your App Registration → Expose an API and set the Application ID URI to https://<hostname>/api/v1. Under API permissions on the UI client, add a permission for that API.
  4. Keycloak: No audience configuration is needed—Keycloak uses the client ID as the audience by default.
  5. Other providers: Ensure the API or resource server is registered with the correct audience identifier and that the provider is configured to issue JWT (not opaque) access tokens.

See Also​