Fixing Pangolin & Zitadel Integration: A Missing Step?

Integrating Pangolin with Zitadel can sometimes present unexpected challenges. This article delves into a specific issue encountered during the integration process, focusing on a missing step in the documentation that can lead to authentication failures. We will explore the problem, its workaround, and potential solutions to ensure a smooth integration experience.

The Integration Issue: User Identifier Not Found

When following the official Pangolin documentation for integrating with Zitadel, users may encounter an error message stating, "There was a problem connecting to Paettern Identity. Please contact your administrator. User identifier not found in the ID token." This error arises even after meticulously following the documented steps. This issue indicates that Pangolin is unable to retrieve the necessary user identifier from the ID token provided by Zitadel. The ID token is a crucial component of the authentication process, containing information about the authenticated user.

The root cause of this problem lies in a specific setting within Zitadel's project configuration. By default, Zitadel might not include the user's roles in the ID token. Although the setting is labeled "Include user's roles in the ID Token," its description states that it "Enables clients to retrieve profile, email, phone, and address claims from ID token." This discrepancy between the title and the description can be misleading, causing users to overlook this crucial setting.

Understanding the Error

The error message "User identifier not found in the ID token" indicates that Pangolin, after a successful authentication against Zitadel, could not find the user's unique identifier within the information Zitadel provided back. This identifier is essential for Pangolin to correctly associate the user with their permissions and roles within the Pangolin system. Without it, Pangolin cannot authorize access to resources, leading to the error. The user identifier typically maps to a unique attribute within Zitadel, which Pangolin expects to find in a specific claim within the ID token.

Why This Happens

The reason this occurs is that, by default, Zitadel might not be configured to include the necessary user profile information within the ID token. This can be due to a variety of reasons, including security considerations or simply the default configuration settings. The setting "Include user's roles in the ID Token" acts as a gatekeeper for including this extra user information. Even though the setting implies it's just for roles, it also governs the inclusion of other user profile attributes, which often include the user identifier.

The Workaround: Enabling User Roles in the ID Token

The immediate solution to this issue involves enabling the "Include user's roles in the ID Token" setting within the Zitadel project configuration. This setting, found under Zitadel -> Project -> Pangolin (App name) -> Token Settings, ensures that Zitadel includes the necessary user information, including the user identifier, in the ID token. Once this checkbox is selected, Pangolin can successfully retrieve the user identifier and authorize access to resources.

Step-by-Step Guide to the Workaround

1. Log in to your Zitadel instance: Access your Zitadel administration console.
2. Navigate to your Project: Find the project you created for the Pangolin integration. This is the project where you configured the OAuth application for Pangolin.
3. Select the Pangolin Application: Within the project, locate the specific application you created for Pangolin. This application represents the connection between Pangolin and Zitadel.
4. Go to Token Settings: Within the application settings, find the section labeled "Token Settings".
5. Enable "Include user's roles in the ID Token": Check the box next to this setting. This will instruct Zitadel to include the user's roles and other relevant profile information in the ID token.
6. Save the Changes: Ensure you save the changes to the application configuration.
7. Test the Integration: Attempt to access a resource in Pangolin that requires authentication via Zitadel. You should now be able to authenticate successfully.

Implications of Enabling the Setting

Enabling the "Include user's roles in the ID Token" setting has implications for the size and content of the ID token. The token will now include additional claims related to the user's profile, such as email, phone number, and address. This can increase the size of the token, which might have performance implications in certain scenarios. However, for most use cases, the increase in size is negligible.

Potential Solutions and Improvements

While the workaround resolves the immediate issue, there are several potential solutions and improvements that could prevent this problem from occurring in the first place.

Documentation Update

The most straightforward solution is to update the Pangolin documentation to explicitly mention the need to enable the "Include user's roles in the ID Token" setting when integrating with Zitadel. This will prevent users from encountering the error in the first place. The documentation should also clarify the discrepancy between the setting's title and its description.

Zitadel Configuration Adjustment

Alternatively, Zitadel could be configured to include the preferred_username claim in the ID token by default, regardless of whether the "Include user's roles in the ID Token" setting is enabled. This would ensure that Pangolin always has access to the user identifier without requiring users to manually enable the setting.

Pangolin Code Modification

Pangolin could be modified to be more flexible in how it retrieves the user identifier from the ID token. Instead of relying on a specific claim, such as preferred_username, Pangolin could be configured to search for the user identifier in a variety of claims. This would make Pangolin more resilient to different Zitadel configurations.

Clarifying the "Roles" Setting in Zitadel

The naming and description of the "Include user's roles in the ID Token" setting in Zitadel could be improved to better reflect its actual functionality. The description should explicitly state that the setting also controls the inclusion of user profile information, not just roles. This would prevent users from being misled by the setting's title.

Environment Details

The issue was reproduced in the following environment:

• Zitadel Version: v4.6.5
• OS Type & Version: Ubuntu 24.04.3 LTS
• Docker Engine: 29.0.0
• Pangolin Version: 1.12.2
• Gerbil Version: 1.2.2
• Traefik Version: v3.6

These details are important for understanding the context in which the issue was observed. Different versions of Zitadel or Pangolin might behave differently, so it's essential to consider the specific environment when troubleshooting integration issues.

Reproducing the Issue

To reproduce the issue, follow these steps:

1. Deploy Pangolin and Zitadel.
2. Configure the OAuth application in Zitadel for Pangolin, using the Code method with Basic/Authorization Code as the Auth Method/Grant Types.
3. Follow the official Pangolin documentation for integrating with Zitadel: https://docs.pangolin.net/manage/identity-providers/zitadel.
4. Do not enable the "Include user's roles in the ID Token" setting in Zitadel.
5. Attempt to access a resource in Pangolin with a user provisioned for the Zitadel IdP.
6. You should encounter the error message: "There was a problem connecting to Paettern Identity. Please contact your administrator. User identifier not found in the ID token."

This reproduction procedure confirms that the issue is reproducible and provides a clear set of steps for others to verify the problem.

Expected Behavior

The expected behavior is that Pangolin should be able to retrieve the user identifier from the ID token provided by Zitadel, regardless of whether the "Include user's roles in the ID Token" setting is enabled. This could be achieved through one of the following solutions:

• The documentation should be updated to explicitly mention the need to enable the "Include user's roles in the ID Token" setting.
• Zitadel should send the preferred_username claim in the ID token by default.
• Pangolin should be able to pull the correct user name from the token that Zitadel sends when the checkbox mentioned above is not checked.

Achieving the expected behavior ensures a seamless integration experience and prevents users from encountering authentication errors.

Conclusion

Integrating Pangolin with Zitadel requires careful attention to detail, particularly regarding the "Include user's roles in the ID Token" setting. By understanding the issue, its workaround, and potential solutions, users can ensure a smooth and successful integration. Addressing the documentation discrepancy and considering code modifications can further enhance the integration experience.

For more information on configuring identity providers with Zitadel, refer to the official Zitadel documentation on configuring identity providers.