Frequently Asked Questions¶

Pre-configuration Preparation¶

Not sure whether your company should use SAML or OIDC, how to choose?

First, confirm your Identity Provider (IdP) type:

• If it's a standard enterprise identity management product like Azure AD, Okta, OneAuth, Keycloak, etc., it usually supports both. It is recommended to prioritize SAML as its configuration is simpler (just upload the metadata XML).

• If it's a self-built system or a developer platform (like Authing, Auth0), it might only support OIDC. Choose OIDC in this case.

• If you are unsure, contact your IT administrator to confirm the protocol types supported by your IdP.

The IdP requires providing the SP's Entity ID and callback URL first to create the application, but Guance requires uploading the IdP metadata first. What should I do?

Use temporary addresses for initial configuration:

• Entity ID: https://auth.guance.com/saml/metadata.xml

• Assertion Consumer Service URL (ACS URL): https://auth.guance.com/saml/assertion

Enter these temporary addresses in your IdP, download the metadata XML, then create the identity provider in Guance. After successful creation, obtain the real Entity ID and ACS URL, and go back to your IdP to replace the temporary ones.

During Configuration¶

After uploading the IdP metadata, Guance shows "Parsing failed" or "Format error".

Check the following points:

1. Confirm you downloaded the SAML metadata XML, not a certificate file or other format.

2. Check if the XML file is complete. Sometimes files downloaded from the IdP might be truncated by the browser. It is recommended to download using the "Save As" method.

3. Confirm that the Entity ID and ACS URL are properly configured in the IdP. Metadata from blank configurations might lack critical fields.

4. If you are using a self-signed certificate, ensure the certificate is not expired.

During OIDC configuration, what should I fill in for the "Identity Provider URL"?

Fill in the IdP's Issuer URL (service discovery address). Common formats:

• Keycloak: https://keycloak.example.com/realms/<realm-name>

• Authing: https://<app-id>.authing.cn/oidc

• Auth0: https://<tenant>.auth0.com/

• Self-built OIDC: https://auth.example.com

After filling it in, Guance will automatically discover the .well-known/openid-configuration endpoint. If you get a "Failed to fetch configuration" prompt, it might be due to an incorrect URL or the IdP not enabling the discovery service. In this case, you need to switch to Non-standard OIDC configuration and manually fill in the endpoints.

In OIDC mapping configuration, what should I fill in for the "Username" field?

This depends on the field name returned in the user information from your IdP. Common correspondences:

If unsure, you can test fetching user information in your IdP and check the returned JSON field names.

When configuring role mapping, how do I fill in the "Attribute Field" and "Attribute Value"?

This depends on the attributes returned by your IdP during user authentication. For example:

Scenario: Assigning roles by department

• IdP returns user attributes: {"department": "Tech Dept", "role": "admin"}

• Guance configuration:

  • Attribute Field: department

  • Attribute Value: Tech Dept

  • Assigned Role: Standard Member

Scenario: Assigning roles by user group

• IdP returns user attributes: {"groups": ["admin", "developer"]}

• Guance configuration:

  • Attribute Field: groups

  • Attribute Value: admin (Supports multiple values separated by commas, e.g., admin,developer)

  • Assigned Role: Administrator

The attribute field name must exactly match (case-sensitive) what is returned by the IdP.

Login Issues¶

Can successfully redirect to the IdP login page, but after logging in, returning to Guance prompts "Failed to fetch user information" (OIDC)?

Check the following points:

1. Mapping field error: Confirm the "Email" mapping field matches the actual field name returned by the IdP (a common error is filling in mail while the IdP returns email).

2. Missing Scope: Ensure email is included in the authorization request Scope, and the IdP agrees to return email information.

3. Incorrect User Info Endpoint: For non-standard OIDC, check if the userinfo_endpoint in the configuration is correct.

4. Token parsing failure: Confirm the IdP uses the HS256 signing algorithm. Guance currently does not support RS256.

SAML login successful, but user role is incorrect.

Check the role mapping configuration:

1. Confirm the role mapping feature is enabled (switch status).

2. Check if the user's attributes are correctly returned by the IdP (you can view the SAML assertion via browser developer tools or use a SAML debugging tool).

3. Confirm the "Attribute Field" and "Attribute Value" exactly match those in the assertion.

4. If a user should match multiple rules, confirm if the highest permission role is assigned as expected.

After SSO login, the user can see multiple workspaces, but switching prompts "No permission"?

This is because:

1. The user logged into Workspace 1 via IdP A.

2. Workspace 2 is also configured with the same IdP A, but the role mapping rules are different.

3. When the user switches to Workspace 2, Guance re-validates the role mapping and finds the user doesn't match Workspace 2's rules.

In this case, ensure that the role mapping rules for the same IdP are consistent across all workspaces, or configure generic mapping rules (like a unified user group identifier) for cross-workspace users.

User Management¶

After an employee leaves, how to completely prevent them from logging into Guance via SSO?

You need to delete in both places:

1. IdP side: Delete or disable the employee's account so they cannot pass enterprise authentication.

2. Guance side: Go to Manage > Member Management > SSO Management, click the SSO member count, find the user and delete them.

If you only delete on the Guance side, the employee can still log in via SSO (a new account will be automatically recreated). If you only delete on the IdP side, the employee might still retain the Guance login session until it expires.

How can SSO users modify their username displayed in Guance?

The username for SSO users is determined by the mapping field returned by the IdP and cannot be modified directly on the Guance side. To modify it:

1. Modify the corresponding user attribute (e.g., preferred_username or name) in the IdP.

2. The user logs into Guance again to sync the update.

If you need to display a different name in Guance, it's recommended to contact the IdP administrator to adjust the attribute mapping, or when enabling role mapping in Guance, use fields that don't affect the display name (like user groups) for permission control.

Can some employees log in via SSO while others use regular account passwords?

Yes. Guance supports hybrid login mode:

• Configure the IdP and domain restrictions in SSO Management.

• Users whose email domains don't match the SSO domain can still log in via Guance account password or mobile verification code.

• Users whose email domains match the SSO domain will be directed to the IdP for login.

Note that the same email cannot use both methods. If an email is already bound to SSO, it cannot be used to register a local Guance account.

Multiple IdPs & Cross-workspace¶

The company acquired another company with two different Azure ADs. Can both be configured in the same Guance workspace?

Yes. A single Guance workspace supports up to 10 IdPs. Configuration method:

1. Add the two Azure ADs as separate identity providers.

2. Configure their respective email domains (e.g., @company-a.com and @company-b.com).

3. Configure role mapping rules for each IdP (the rules can be different).

When users log in, Guance automatically matches the corresponding IdP based on the email domain.

Can true single sign-on "login once, access multiple workspaces" be achieved?

Yes, but the following conditions must be met:

1. Multiple workspaces are configured with the same IdP (or trusted multiple IdPs).

2. The user's session in the IdP remains valid (not expired).

3. The user has a valid role in each workspace (assigned via role mapping or default role).

Once these conditions are met, after logging into any workspace, the user can directly switch to other workspaces via the top Workspace Switcher within the valid session period without re-entering the password.

Security & Compliance¶

How to audit SSO user login behavior?

Guance provides the following auditing capabilities:

1. SSO Member List: View the list of members logged in via each IdP and their last login time.

2. Operation Audit: View user operation records (including login, logout, key operations) in Manage > Audit Events.

3. Notification Mechanism: Owners and Administrators receive email notifications when SSO configuration changes.