Configure the Single sign-on (SSO)
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.
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
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:
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).
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).
Client ID you received after registering with the Identity Provider.
Client Secret you received after registering with the Identity Provider.
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
Sign-in scenario
Groovy Script example
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
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?
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=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.
- 1 General architecture
- 1.1 Compatibility
- 2 SSO Provider configuration
- 3 Basic SSO configuration
- 4 Advanced SSO configuration - post login actions
- 5 SSO impact on XTRF portals
- 6 Testing Procedures
- 7 SSO activating and deactivating
- 8 FAQ
- 8.1 How can I sign in as an administrator to modify SSO Settings when my SSO Provider configuration has changed?
- 8.2 Is SSO supported for multi-node installation?
- 8.3 I'm using XTRF branches. Is this feature supported with SSO?
- 8.4 Can the XTRF's support staff access the system while SSO is enabled?
- 8.5 If XTRF does not find a user with an e-mail address received from an SSO provider, will it create a new one (provision)?
- 8.6 What does 'connect with 3rd party API & update user properties' mean?
- 8.7 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)?
- 8.8 With SSO enabled, are the user creation, activation, and deactivation still managed in XTRF?
- 8.9 Does the Automatic Logout work for idle users who have logged in through SSO?