Configure the Single sign-on (SSO)

Owned by Oksana Vishchuk
Last updated: Oct 28, 2024 by Kinga Foryś
12 min read

General architecture

The general purpose of the XTRF SSO feature is to delegate user authentication to a 3rd party Identity Provider (IdP) implementing an OpenID Connect standard: https://openid.net/specs/openid-connect-core-1_0.html

The feature can be activated and configured independently for all three XTRF portals:

  • Home Portal

  • Vendor Portal

  • Client Portal

XTRF also supports MFA (Multi-Factor Authentication) as part of SSO (Single Sign-On) for all portals.

The portals can share the same SSO provider or be associated with different ones.

You may get familiar with the concept by studying the below example: https://doubleoctopus.com/security-wiki/federation-and-sso/single-sign-on/

The integrated SSO provider (Identity Provider) authenticates a user so they can access the XTRF TMS instance (Service Provider).

The authentication process on the XTRF side may be extended by post-authentication actions, including further (i.e., user-related) information requests and updating the XTRF database (i.e., user profile, group assignments, etc.) based on the received OAuth Access Token, using custom Groovy scripts.

General XTRF SSO configuration architecture

The XTRF feature toggle in the License activates this feature. To activate it, contact the XTRF Support Team.

Compatibility

XTRF SSO internally uses Google API's Client Library to communicate with the provider over the OAuth 2.0 protocol. The authorization flow is compatible with OpenID Connect Core specification on top of OAuth 2.0.

XTRF SSO uses Authorization Code Flow from OpenID Connect specification, which means you need to configure both the Authorization Endpoint URL and Token Endpoint URL on the XTRF configuration page.

SSO Provider configuration

On the SSO identity provider side, you must register XTRF as a client application.

Instructions for Google

Instructions for Microsoft Azure

Instructions for GitHub

The most important part of this process is configuring the Callback URL (you can find the correct value on the XTRF configuration page). At the end of the process, you will receive a Client ID and a Client Secret. These values should be copied and then set up on the XTRF configuration site.

Azure AD Example

  1. To configure SSO using Azure AD, please go to the Azure Active Directory menu and select App Registrations.

     

  2. Click New registration and fill the form with your application name and Redirect URL:

     

  3. Go to Certificates & secrets and add a New client secret:

     

  4. You will receive an ID and secret value for the XTRF configuration.

For another approach, see https://docs.pivotal.io/p-identity/1-11/azure-oidc/config-azure.html.

Additional resources:

Basic SSO configuration

Configure XTRF

  1. In the XTRF Home Portal, go to   Configuration menu > General Configuration > Security.

  2. Go to the  Home Portal / Vendor Portal / Client Portal tab.

  3. In the Single Sign-On (SSO) card, provide the following data from Identity Provider:

    1. Auth URL - the endpoint for the authorization server. It is used to obtain the authorization code (e.g., https://id.yourdomain.com/adfs/oauth2/authorize).

    2. Access Token URL - the endpoint for the authorization server. It is used to exchange the authorization code for an access token (e.g., https://id.yourdomain.com/adfs/oauth2/token).

    3. Client ID you received after registering with the Identity Provider.

    4. Client Secret you received after registering with the Identity Provider.

    5. Scopes - the scopes of the access request used during advanced configuration (e.g., for Google: “openid email”; for ActiveDirectory: “openid”).

Home Portal - Sign in

Requirements

Home Portal SSO will allow existing users to sign in to the XTRF System. It is crucial to remember that users will be initially mapped by e-mail address. Therefore, user email addresses must be unique. After the first sign-in, the user will be matched by a key consisting of two fields: Subject and Issuer.

Possible troublesome cases

In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:

  1. If a user matched by Subject and Issuer has a different e-mail address in XTRF than the one received from SSO, signing in will be impossible. To prevent this, XTRF removes SSO linkage when changing the user's e-mail address.

  2. If the user in XTRF is inactive and SSO sign-in action is performed. 

  3. If there are no free licenses on the XTRF Instance. 

  4. If there is no user in XTRF with the same e-mail address as received from the SSO provider, two actions can be performed (configurable with a custom script):

    1. Not allow signing in.

    2. Create (provision) a user in XTRF (requires advanced coding skills for custom solutions).

Sign-in scenario

 

Groovy Script example

import org.json.JSONObject
import com.radzisz.xtrf.model.partner.Gender
       

def user = userHolder.getUser()
println("user is " + user)

JSONObject userInfo = oAuth2Helper
.getDataFromProvider("https://www.googleapis.com/oauth2/v3/userinfo")

if (user == null) {
println("user is null so create a new one")

user = oAuth2Helper.createUser(userInfo.getString("given_name"),
    userInfo.getString("family_name"),
        Gender.MALE,
    userInfo.getString("email"), //email
    userInfo.getString("email"), //login
        "Administrators")
userHolder.setUser(user)
}

Vendor & Client Portal - Sign in

Introduction & Requirements

Vendor Portal and Client Portal are two completely different applications, but in the context of SSO, the sign-in mechanism and flow are very similar and can be described in one chapter. In this section, Vendor Portal and Client Portal are referred to as Partner Portal. Likewise, vendors and clients will be referred to as partners. 

Signing in to a Partner Portal using a Partner account is impossible. The real users are Partners' Contact Persons; therefore, the SSO user will be linked to them.

Possible troublesome cases

In some difficult cases, signing in with SSO will be impossible:

  1. If a Contact Person matched by 'Subject' and 'Issuer' has a different e-mail address in a Portal than the one received from SSO, then signing in will be impossible. To prevent this, XTRF removes the possibility of changing the e-mail in the Contact Person's profile.

  2. If a Contact Person of a Partner is inactive, and an SSO sign-in action is performed. There are two possible outcomes:

    • Access is denied

    • Contact Person and/or Partner is activated, and sign-in is allowed.

  3. If a Contact Person of one Partner has the same e-mail address as a Contact Person of another Partner. This issue needs to be fixed in the XTRF System by the administrator.

  4. If there is no Partner or Contact Person in XTRF with the same e-mail address as received from the SSO provider, two actions can be performed (configurable with a custom script):

    1. Not allow signing in

    2. Create a Partner and a Contact Person (requires advanced coding skills for custom solutions).

Sign-in scenario

Advanced SSO configuration - post login actions

The general purpose of the advanced configuration is to allow some basic elements of user provisioning functionality. The advanced configuration is optional and includes a configurable Groovy script that is run as a post-authentication action. The script can be used to synchronize certain pieces of user data between the XTRF database and SSO provider, including user profile details or group assignments (and thus the user rights). This requires advanced coding skills for system administrators.

SSO impact on XTRF portals

When SSO is selected exclusively as the gateway to specific XTRF portals, certain features are disabled to keep the system's integrity.

When the Home Portal is SSO-exclusive

When the Vendor Portal is SSO-exclusive

When the Client Portal is SSO-exclusive

Customer Portal API

  • You will no longer be able to access CP API with a login and a password.

  • Adding a Contact Person through API is no longer available.

  • The following API endpoints are blocked:

    • POST /customers/{customerId}/persons Creates a new client contact person.

    • POST /system/mail/resetPassword Sends password reset e-mail.

    • POST /system/login Authenticates partner with given username and password.

    • POST /system/account/password Sets user's password to a new value.

    • PUT /system/account/password Sets current user's password to a new value.

    • POST /system/validateToken Checks if the given password reset token is valid.

 

Testing Procedures

When configuring the SSO settings, be careful not to lose access to your XTRF instance. Please check our best practices to avoid this:

  • Sign in as an administrator and introduce changes - then save your changes, but do not sign out!

  • In another browser / on another computer, try to sign in as a regular user.

  • Validate if your SSO configuration works as expected.

  • Try to sign out from a regular user account and sign in again.

  • If you cannot do so, sign in back to SSO in the original browser and fix the configuration.

If possible, perform the procedure on a test XTRF instance. Also, consider keeping the form-based login option active until the configuration is completed and the results are satisfactory.

If you accidentally lose access to your XTRF instance, you must contact XTRF support.

SSO activating and deactivating

Activating SSO on a brand new XTRF instance

No user migration procedure is required.

Activating SSO on an instance with existing users

When you activate an SSO-only login on an instance, you cannot sign in using your old credentials. 

Deactivating SSO on an instance with existing users

If you deactivate SSO on an instance where the regular sign-in form was also enabled, users can sign in using their credentials.

If you deactivate SSO on an instance where the regular sign-in form was disabled, users will have to create new passwords through the I forgot my password link on the sign-in page.

FAQ

How can I sign in as an administrator to modify SSO Settings when my SSO Provider configuration has changed?

  1. Configure your new SSO Provider.

  2. Sign in to XTRF as an administrator using the old Identity Provider credentials.

  3. Change the configuration as described in the Configure XTRF section to support the new Provider.

If your old SSO Provider is unavailable, you should run your xtrf with -Dxtrf.authentication.enforceLocal=true parameter and sign in as an admin user using its credentials (concerns only Home Portal). The other way to access the XTRF Home Portal is to contact XTRF support.

All portals will be switched to the login/password sign-in method with this parameter!

Is SSO supported for multi-node installation?

Yes, SSO is supported for multi-node installations for all three portals. However, the proper configuration of sticky sessions needs to be applied on the proxy server(s). For more details, refer to the “XTRF MultiNode - Installation and Configuration Guide.”

I'm using XTRF branches. Is this feature supported with SSO?

There is no special support for XTRF branches; the SSO is configured globally, not per XTRF branch.

Can the XTRF's support staff access the system while SSO is enabled?

Yes, they can do this through a dedicated support access channel.

If XTRF does not find a user with an e-mail address received from an SSO provider, will it create a new one (provision)?

That is an optional action that can be realized as a part of a post-login script (requires advanced coding skills for custom solutions).

What does 'connect with 3rd party API & update user properties' mean?

OpenID Connect, being built on top of OAuth2 and RESTful API, can utilize other API endpoints than the one mandated by the standard. Therefore, a post-login script can request more information from the IdP than possible, for example, with SAML2.

How do you handle the impossibility of signing in to the Client Portal using a Client account (and that the only real users are Clients' Contact Persons)?

It is currently possible to sign in to the Client Portal using a company account instead of a Contact Person account. This will not be possible with SSO. You may need to review contact persons' permissions before enabling SSO if you were previously using company accounts. If you weren't, nothing will change.

With SSO enabled, are the user creation, activation, and deactivation still managed in XTRF?

If the post-login provisioning is inactive (the default), user management is still done in XTRF. We are not currently planning the deprovisioning operation.

Does the Automatic Logout work for idle users who have logged in through SSO?

Yes. Automatic logout ends the XTRF session and requires re-authentication with IdP.