Single Sign-On (SSO) EN

Troi supports SSO using the Security Assertion Markup Language (SAML) 2.0 standard, an open standard for exchanging authentication and authorization data between parties. This provides a high level of security and significantly simplifies user access.

Troi acts as the Service Provider (SP). Your organization provides the Identity Provider (IdP).

How SSO with Troi Works

The login flow is as follows:

1. The user tries to access Troi.

2. Troi redirects the login request to your IdP.

3. The IdP authenticates the user and returns a SAML response.

4. Troi reads this response, identifies the user, and logs them in – optionally assigning them to the right group.

Implementation Steps

1. Configure your IdP with the required attributes and (optionally) the user group, language, and client claims

2. Send us your SAML metadata file (metadata.xml), including the Entity ID, SSO URL, and certificate.

3. Provide a list of email addresses (as used in your IdP) for existing Troi users so we can convert local usernames to SSO accounts.

4. We schedule a short activation session to enable SSO and perform a live login test with you.

SAML Attributes Overview

Once you're ready to configure your IdP, you will need the following:

Attributes & Handling

General Attributes

• The email address (urn:oid:1.2.840.113549.1.9.1) is the unique user identifier.

• If a user does not exist yet in Troi, they will be automatically created on first login. No manual pre-creation of users is necessary, as long as the SAML login is successful and the required attributes are included.

• If a user already exists in Troi with a local username, we will automatically update that account to use the email address from the SAML login. This switch is handled by us during the SSO activation. The old username will no longer be used after that.

User groups

Troi supports automatic assignment of users to internal user groups during SSO login, based on identity provider attributes or fallback logic.

Supported Attributes

Troi uses the following attribute for group assignment:

• troi:group
  A string value that matches an internal user group’s SSO mapping (defined in the group settings)

Assignment Options

Option 1: Automatic Group Assignment

• The Identity Provider (IdP) sends the troi:group claim during login.

• Troi attempts to match the received value to an internal user group mapping.

• If a match is found, the user is automatically assigned to that group.

Example (Microsoft Entra): The attribute is set in "Attributes & Claims" with the name troi:group.

Option 2: Default Group Fallback

If the IdP does not send the troi:group attribute:

• Troi assigns the user to a default user group.

• This default group is configured within Troi.

• Admins can manually reassign the user to a different group later if needed.

Open

 

Language

Clients

Troi supports SSO-based client assignment, similar to group-based assignment via troi:group.

Each client can be configured with:

• A preferred language (used during login)

• An SSO mapping key for automated assignment

Supported Attributes

Troi uses the following attributes for client assignment:

• troi:main_client
  A unique string matching a client’s SSO mapping key (defined in the client details)

• troi:clients
  Can be provided as either:

  • A comma-separated string, e.g. "troi1-mandant, troi2-mandant"

  • An array of strings, e.g. ["troi1-mandant", "troi2-mandant"]
    (same format as used for troi:groups)

Behavior

If the identity provider provides no client assignment:

• The user will be assigned to the default SSO client.

Open

Updating Existing Users

Authentication behavior differs between first login and subsequent logins:

First Login

On a user's very first login (if they do not yet exist in Troi):

• The user is created automatically.

• All attributes provided by the IdP take highest priority.

  • For example, troi:main_client is used if present. If this attribute is missing, the configured default client is assigned.

  • The same applies to troi:group and urn:oid:2.16.840.1.113730.3.1.39 (preferred language) — attributes override defaults.

• If the attributes are missing, the default values configured in Troi for group, client, and language are used instead.

Subsequent Logins

From the second login onward:

• First name, last name, and username are synchronized with the IdP values at every login.

• User group (troi:group) is reassigned at every login, provided the attribute is sent by the IdP.

• Email address is only synchronized if the option is enabled for the client. (systemsettings)

• Client assignment (troi:main_client, troi:clients) and language are not reapplied from IdP attributes after the initial login.

• Changes to these values made internally in Troi (e.g., by an administrator) remain unchanged.

This behavior ensures that manual adjustments in Troi are not overwritten by later IdP logins.

FAQ

Once SSO has been activated – can direct Troi accounts still be used in parallel?

No. When SSO is activated, direct Troi accounts can no longer be used.
SSO is an either/or system, meaning you either use SSO or direct Troi accounts – but not both at the same time.

Setup Examples

Setup on Microsoft Entra (Microsoft Azure)

1. Create the Application:

   1. Application → Enterprise applications → New application → Create your own application

      1. What's the name of your app? → Example: Troi SAML SSO

      2. What are you looking to do with your application? → Integrate any other application you don't find in the gallery

2. Open the Application

3. Click on Properties

   1. Enabled for users to sign-in? → Yes

4. Click on Single sign-on

   1. Basic SAML Configuration

      1. Identifier (Entity ID) → https://<domain>.troi.software

      2. Reply URL → https://<domain>.troi.software/site/login.php?page=login&action=authenticatorExternal

   2. Attributes & Claims

      1. Add a group claim (optional):

         • Which groups associated with the user should be returned in the claim? → All groups

         • Source attribute → Group ID

         • Advanced options → Customize the Name of the group Claim → Name → troi:group

      2. Add new claims:

         • Email Address

           • Name: urn:oid:1.2.840.113549.1.9.1

           • Namespace: empty

           • Source: Attribute

           • Source attribute: user.mail

         • Family Name

           • Name: urn:oid:2.5.4.4

           • Namespace: empty

           • Source: Attribute

           • Source attribute: user.surname

         • Given Name

           • Name: urn:oid:2.5.4.42

           • Namespace: empty

           • Source: Attribute

           • Source attribute: user.givenname

5. General

   1. Ensure that users are granted access to the Troi application within Microsoft Entra. (API permissions)

Setup on Ping Identity

1. Connections → Applications → New Application

2. Web App

3. ACS URLs → https://<customer>.troi.software/site/login.php?page=login&action=authenticatorExternal

4. SIGNING KEY → Signing Algorithm → RSA_SHA256

5. Entity ID → https://<customer>.troi.software

6. SLO Binding → Post

7. Subject NameID Format → urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

8. Save

9. Switch to Attribute Mappings

10. Add new ones:

    • troi:group → Group Names

    • urn:oid:1.2.840.113549.1.9.1 → EMail Address

    • urn:oid:2.5.4.4 → Family Name

    • urn:oid:2.5.4.42 → Given Name