FAQ¶

Before Configuration¶

Not sure whether to use SAML or OIDC? How should we choose?

First confirm the type of identity provider (IdP) you use:

• If you use Azure AD, Okta, OneAuth, Keycloak, or other standard enterprise identity management products, they usually support both. In that case, SAML is recommended, as it is simpler to configure (just upload the metadata XML);

• If you have a self-built system or developer platform (such as Authing or Auth0), it may only support OIDC. In that case, choose OIDC;

• If you are not sure, ask your IT administrator which protocols the IdP supports.

The IdP asks me to provide the SP's Entity ID and callback URL before creating the application, but TrueWatch requires uploading the IdP metadata first. What should I do?

Use temporary addresses to configure it first:

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

• Assertion URL (ACS URL): https://auth.truewatch.com/saml/assertion

Enter the temporary addresses above in the IdP, download the metadata XML, and then create the identity provider in TrueWatch. After creation, obtain the real Entity ID and assertion URL, return to the IdP, and replace the temporary values.

During Configuration¶

After uploading the IdP metadata, TrueWatch reports "parsing failed" or "format error".

Check the following:

1. Make sure the file downloaded is the SAML metadata XML, not a certificate file or another format;

2. Check whether the XML file is complete. Files downloaded from the IdP may sometimes be truncated by the browser. It is recommended to download the file using "Save As";

3. Make sure the Entity ID and ACS URL are configured in the IdP. Metadata from a blank configuration may lack key fields;

4. If you are using a self-signed certificate, make sure the certificate has not expired.

In OIDC configuration, what should I enter for "Identity Provider URL"?

Enter 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 entering it, TrueWatch automatically discovers the .well-known/openid-configuration endpoint. If it reports "unable to fetch configuration", the URL may be incorrect, or the IdP has not enabled the discovery service. In that case, switch to non-standard OIDC configuration and fill in the endpoints manually.

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

It depends on the user information field names returned by your IdP. Common mappings:

If you are not sure, test fetching user information in the IdP and inspect the returned JSON field names.

When configuring role mapping, what should I enter in "Attribute" and "Attribute Value"?

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

Scenario: Assign roles by department

• IdP returns the user attribute: {"department": "技术部", "role": "admin"}

• Configure in TrueWatch:

  • Attribute: department

  • Attribute Value: 技术部

  • Assigned role: Standard Member

Scenario: Assign roles by user group

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

• Configure in TrueWatch:

  • Attribute: groups
  • Attribute Value: admin (multiple values can be separated by commas, e.g., admin,developer)
  • Assigned role: Administrator

Attribute names must be exactly the same as those returned by the IdP (case-sensitive).

Login Issues¶

I can successfully redirect to the IdP login page, but after logging in, TrueWatch reports "unable to obtain user information" (OIDC)?

Check the following:

1. Incorrect mapping field: make sure the "Email" mapping field matches the field name actually returned by the IdP (a common mistake is entering mail when the IdP returns email);

2. Missing scope: make sure email is included in the authorization request scope and that the IdP agrees to return the email address;

3. Incorrect user info endpoint: for non-standard OIDC, check whether userinfo_endpoint in the configuration file is correct;

4. Token parsing failed: confirm the signing algorithm used by the IdP is HS256. TrueWatch currently does not support RS256.

SAML login succeeds, but the user's role is incorrect

Check the role mapping configuration:

1. Make sure role mapping is enabled (toggle state);

2. Check whether the user's attributes are correctly returned by the IdP (you can inspect the SAML assertion with browser developer tools or use a SAML debugging tool);

3. Make sure the "Attribute" and "Attribute Value" exactly match what is in the assertion;

4. If the user should match multiple rules, confirm that the highest-privilege role is assigned as expected.

After SSO login, users can see multiple workspaces, but get a "no permission" message when switching?

This is because:

1. The user signed in to Workspace 1 through 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, TrueWatch re-evaluates the role mapping and finds that the user does not match the rules of Workspace 2.

In this case, make sure the role mapping rules for the same IdP are consistent across all workspaces, or configure common mapping rules for cross-workspace users (such as a unified user group identifier).

User Management¶

After an employee leaves, how can I completely prevent them from logging in to TrueWatch through SSO?

They need to be deleted in both places:

1. On the IdP side: delete or disable the employee's account so they can no longer pass enterprise authentication;

2. On the TrueWatch side: go to Management > Member Management > SSO Management, click the SSO member count, find the user, and delete them.

If you only delete the user on the TrueWatch side, the employee can still log in via SSO (the account will be automatically recreated). If you only delete the user on the IdP side, the employee may keep the TrueWatch login session until it expires.

How can SSO users change the username displayed in TrueWatch?

The username of an SSO user is determined by the mapping field returned by the IdP and cannot be modified directly on the TrueWatch side. To change it:

1. Modify the corresponding attribute in the IdP (such as preferred_username or name);

2. When the user logs in to TrueWatch again, the change is synchronized.

If a different name needs to be displayed in TrueWatch, contact the IdP administrator to adjust the attribute mapping, or, when enabling role mapping in TrueWatch, use a field that does not affect the display name (such as a user group) for permission control.

Can SSO users set or change their own phone numbers?

Yes. Go to Account Settings > User Info to set or change the phone number. No operation in the IdP is required.

If the account already has a phone number, subsequent SAML logins will retain that number. It will not be overwritten even if the IdP returns a different number, and it will not be cleared if the IdP does not return a phone number. For specific rules, see phone number write rules.

If the IdP does not return a phone number, will it affect SAML login or voice notifications?

It does not affect SAML login. In SAML attribute mapping, username and email are required, and phone number is optional.

Voice (IVR) notifications use the phone number saved in the account. If the account already has a number, that number can still be used to receive notifications. If the account does not have a number, add one in Account Settings first.

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

Yes. TrueWatch supports hybrid login mode:

• Configure the IdP and domain restrictions in SSO Management;

• Users who do not match an SSO domain can still log in with a TrueWatch account password or phone number verification code;

• Users who match an SSO domain are redirected to the IdP for login.

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

Multiple IdPs and Cross-Workspace¶

Our company acquired another company, and we have two different Azure AD directories. Can both be configured in the same TrueWatch workspace?

Yes. A single TrueWatch workspace supports up to 10 IdPs. To configure:

1. Add the two Azure AD directories as separate identity providers;

2. Configure their respective email domains (such as @company-a.com and @company-b.com);

3. Configure role mapping rules for the two IdPs separately (the rules can be different).

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

Can true single sign-on with "one login, access multiple workspaces" be implemented?

Yes, but the following conditions must be met:

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

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

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

Once these conditions are met, after logging in to any workspace, users can use the workspace switcher at the top to jump directly to other workspaces while the session is valid, without entering their password again.

Security and Compliance¶

How can I audit the login activity of SSO users?

TrueWatch provides the following auditing capabilities:

1. SSO member list: view the list of members who logged in through each IdP and their last login times;

2. Operation audit: view user operation records (including login, logout, and key operations) in Management > Audit Events;

3. Notification mechanism: when SSO configuration changes, the Owner and Administrator receive email notifications.