Skip to main content

Troubleshoot ZITADEL

You will find some possible error messages here, what the problem is and what some possible solutions can be.

Didn't find an answer?

Join or Chat or open a Discussion.

User agent does not correspond​

This error appeared for some users as soon as they were redirected to the login page of ZITADEL. ZITADEL uses some cookies to identify the browser/user agent of the user, so it is able to store the active user sessions. By blocking the cookies the functions of ZITADEL will be affected.

We only found this issue with iPhone users, and it was dependent on the settings of the device.

Go to the settings of the app Safari and check in the "Experimental WebKit Features" if SameSite strict enforcement (ITP) is disabled Also check if "block all cookies" is active. If so please disable this setting.

To make sure, that your new settings will trigger, please restart your mobile phone and try it again.

Settings > Safari > Advanced > Experimental Features > disable: „SameSite strict enforcement (ITP)“

Same Site Strict Enforvement

Settings > Safari > disable: "Block All cookies" Block all cookies

Do you still face this issue? Please contact us, and we will help you find out what the problem is.

Invalid audience​

invalid audience (APP-Zxfako)

This error message refers to the audience claim (aud) of your token. This claim identifies the audience, i.e. the resource server, that this token is intended for. If a resource server does not identify itself with a value in the "aud" claim when this claim is present, then the must be rejected (see RFC7519 for more details).

You might encounter this error message from ZITADEL, typically when you authenticated with a client in one project and trying to access an application in another project. You need add a specific reserved scope to add the projectID to the audience of the access token.

The two scenarios should help you troubleshoot this issue:

Frontend to Backend​

You have one project for your frontend application and one project for your backend application. End-users authenticate to an application in your frontend project. The frontend then sends requests to the backend, validates the token with ZITADEL's introspection endpoint, and returns a payload to the frontend. The backend returns the error invalid audience (APP-Zxfako).

You must add the scope urn:zitadel:iam:org:project:id:{projectId}:aud to the auth request that is send from the front end. Replace projectId with the projectId of your backend.

Accessing ZITADEL's APIs​

You have a project for a frontend application. The application should also access the API of your ZITADEL, for example to pull a list of all users and display them on a user page. End-users authenticate to the application in the frontend project, but when calling the management API you get the error invalid audience (APP-Zxfako).

You must add the scope urn:zitadel:iam:org:project:id:zitadel:aud to the auth request that is send from the front end.

When accessing your ZITADEL instance's APIs they act as a resource server. You can check the Console or via API and see that when you open your default organization there exists a project "ZITADEL" that contains different applications for each API and the Console. Like in the scenario above the access token requires to have an aud claim that includes the "ZITADEL" project. Instead of urn:zitadel:iam:org:project:id:zitadel:aud you could also use urn:zitadel:iam:org:project:id:{projectId}:aud, where projectId is the projectId of the Project "ZITADEL".

WebFinger requirement for Tailscale​

The WebFinger requirement and setup is a step a user has to take outside of their IdP set-up. WebFinger is a protocol which supports the ability for OIDC issuer discovery, and we use it to prove that the user has administrative control over the domain and to retrieve the issuer. This is a requirement we have in place for all users, regardless of their IdP, who use custom OIDC with Tailscale.

On their custom domain, e.g example.com, users need to host a WebFinger endpoint at https://example.com/.well-known/webfinger. When queried, this endpoint returns a JSON response detailing the issuer. Users would need to host the endpoint with the link to the ZITADEL issuer. Tailscale only looks up this endpoint once when a user signs up, and will only look up this endpoint again if the user needs to make a configuration change to their identity provider.

The requirements and a set up guide is detailed in the Tailscale documentation.

Login not possible. The organization of the user must be granted to the project​

Organization must be granted Error

ZITADEL is not only capable of handling authentication but also authorization. This error message tells you, that a project grant is missing from the owner organization to the organization of the authenticating user.

You do have two organizations, an owner (Organization A) and a customer (Organization B). The Organization A owns a Project, and has to grant it to Organization B, so users are allowed to authenticate. The error message is shown to users of Organization B that the permission is required, but the project is not granted to Organization B. Project Grant Missing

You do have two possibilities.

  1. Disable the permission check
  2. Give the permission to the organization

Disable the permission check​

  1. Go to the organization, who owns the project, where the user tries to authenticate.
  2. Navigate to the general settings of the needed project
  3. Disable "Check for Project on Authentication"

Project Settings

Give the needed permission to the organization​

  1. Go to the organization, who owns the project, where the user tries to authenticate.
  2. Navigate to the grants page of the needed project
  3. Click on the "New" button
  4. Search for the organization to which you want to grant the project (e.g Organization B)
  5. Select the roles you want to grant
  6. Click save

Project Grant for Organization B