toc

General

Architecture

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

The portals can 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.

This feature is activated by the The XTRF feature toggle on in the License Server - activates this feature. To activate it, contact the XTRF Support Team for activation.

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 need to 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 proper 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

Expand

title	Click to expand

To configure SSO using Azure AD, please go to the Azure Active Directory menu and select App Registrations.
Click New registration and fill the form with your application name and Redirect URL:
Go to Certificates & secrets and add a New client secret:
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

In the XTRF Home Portal, go to Configuration menu > General Configuration > Security.
Go to the Home Portal / Vendor Portal / Client Portal tab.
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. (Optional) Scopes - the scope scopes of the access request used during advanced configuration (e.g., for Google: openid e-mail profile“openid email”; for ActiveDirectory: openid“openid”).

Home Portal - Sign in
Requirements
Home Portal SSO will allow signing in for 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. Google Oauth2 documentation describes these fields as:
Claim
Provided
Description
iss
always
The Issuer Identifier for the Issuer of the response. Always https://accounts.google.com or accounts.google.com for Google ID tokens.
sub
always
An identifier for the user, unique among all Google accounts and never reused. A Google account can have multiple e-mail addresses at different points in time, but the sub value is never changed. Use sub within your application as the unique identifier key for the user. Maximum length is 255 case-sensitive ASCII characters.
Possible Troublesome Cases
Expand
title Click to expand
In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:
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.
If the user in XTRF is inactive and SSO sign-in action is performed.
If there are no free licenses on the XTRF Instance.
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):
Not allow signing in.
Create a user in XTRF.
Sign-in scenario
Possible troublesome cases
Expand
title Click to expand
In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:
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.
If the user in XTRF is inactive and SSO sign-in action is performed.
If there are no free licenses on the XTRF Instance.
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):
Not allow signing in.
Create (provision) a user in XTRF (requires advanced coding skills for custom solutions).
Sign-in scenario
Expand
title Click to expand
Image Added
Groovy Script example
Expand
title Click to expand
Image Removed
Groovy Script Example
Expand
title Click to expand
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 Portaland Client Portal are referred to as 'Partner Portal'. Likewise, Vendors vendors and Clients clients will be referred to as 'Partners' partners.
Info
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
Expand
title Click to expand
In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:
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.
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.
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.
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):
Not allow signing in
Create a Partner and a Contact Person (requires advanced coding skills for custom solutions).
Sign-in scenario
Expand
title Click to expand
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
Expand
title Click to expand
Signing in
Only the SSO option is available on the Home Portal sign-in page.
Image Removed
Changing the password
After the first successful SSO login, password management options are inactivated in the:
Personal settings menu in the top menu bar.
Image Removed
Configuration Icon > User Management > Users.
Image Removed
Configuration Icon > User Management > Users > User account > General Info tab.
Image Removed
Home Portal API
Your API token login method is still active after disabling the user in the SSO provider. However, we recommend you create a dedicated user for API purposes and deny any user group the right to create tokens.
When the Vendor Portal is SSO-exclusive
Expand
title On the Vendor portal
Accepting an invitation to the Vendor Portal
The process now consists of two steps:
A vendor receives an Activate your account e-mail and complies by clicking Join. SSO login screen opens, and the vendor logs in.
A vendor receives a Complete your registration e-mail and
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
Expand
title Click to expand
Signing in
Only the SSO option is available on the Home Portal sign-in page.
Image Added
Changing the password
After the first successful SSO login, password management options are inactivated in the:
Personal settings menu in the top menu bar.
Image Added
Configuration Icon > User Management > Users.
Image Added
Configuration Icon > User Management > Users > User account > General Info tab.
Image Added
Home Portal API
Your API token login method is still active after disabling the user in the SSO provider. However, we recommend you create a dedicated user for API purposes and deny any user group the right to create tokens.
When the Vendor Portal is SSO-exclusive
Expand
title On the Vendor portal
Accepting an invitation to the Vendor Portal
The process now consists of two steps:
A vendor receives an Activate your account e-mail and complies by clicking Join. SSO login screen opens, and the vendor logs in.
A vendor receives a Complete your registration e-mail and clicks the provided link that leads to a confirmation screen. The Choose your password dialog box is now inactive (password is no longer necessary). The vendor verifies the data and clicks Join to complete the registration.
Signing in to the Vendor Portal
The User and Password dialog boxes and the Register button disappear. SSO sign-in window is displayed instead.
Changing the password
After the first successful SSO login, the password reset fields in > My Account > Credential cardare inactivated.
Limited permissions for new users
In Profile module > Users tab > Add User,you can add users with only Contact Person permissions. Other options in the Permissions card are inactive.
The Contact system administrator link in the embedded explanation leads to the Send Message contact form.
Editing existing user profiles
Editing the vendor's own profile: password fields are inactive.
Editing other contact persons' profiles: upgrading the permissions to Administrator or Regular User is disabled.
Editing administrators' and regular users' profiles: all options are available.
Expand
title On the Home Portal
Recruitment settings for Vendor Portal
All the options in the Home Portal's Configuration menu > Portals > Vendor Portal > Recruitment Settings section become inactive.
Signing into the Vendor Portal through the Home Portal
The Sign in to Vendor Portal as this Person button in the Home Portal > Vendor contact person profile > Main Data tab is inactive.
When the Client Portal is SSO-exclusive
Expand
title on On the Client Portal
Changing the password
After the first successful SSO login, the Password Change section in Client Portal > > My account > Settings tab becomes inactive
Adding contact persons
The +Add contact person button in the Contact Persons tab in the Account Preferences pop-up is inactivated.
Expand
title On the Home Portal
Editing clients' system accounts
In the Home Portal > Client profile > Main Data tab > System Accounts tab, the following buttons become inactive:
Sign in as this Partner
Send Welcome E-mail
Send Password Reset E-mail
Clients' contact persons' password reset
the Send Password Reset E-mail button becomes inactive in the Home Portal > Client contact person profile > Account Data tab.
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.
Advanced SSO configuration
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).
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 such 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?
Configure your new SSO Provider.
Sign in to XTRF as an administrator using the old Identity Provider credentials.
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=trueparameter 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.
Note
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
braIs
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,
then
will it create a new one (provision)?
That is an optional action that can be realized as a part of a post-login scriptpost-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
to handle no possibility
do you handle the impossibility of signing in to the
Partner
Client Portal using a
Partner
Client account (and that the only real users are
Partners
Clients' Contact Persons)?
It is currently possible to sign in to the Client Portal using a company account instead of an account 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,
where do we manage
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 , requiring and requires re-authentication with IdP.