Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
General Architecture
The general purpose of the XTRF SSOGeneral 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.
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 | ||
---|---|---|
| ||
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:
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.
(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
Possible troublesome cases
Expand | ||
---|---|---|
| ||
In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:
|
Sign-in scenario
Expand | ||
---|---|---|
| ||
Groovy Script
Exampleexample
Expand | ||
---|---|---|
| ||
|
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 | ||
---|---|---|
| ||
In some difficult cases, signing in with SSO will be impossible and will end up prompting the user trying to log in:
|
Sign-in scenario
Expand | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
Signing inOnly the SSO option is available on the Home Portal sign-in page. Changing the passwordAfter the first successful SSO login, password management options are inactivated in the:
Home Portal APIYour 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 | ||
---|---|---|
| ||
Accepting an invitation to the Vendor PortalThe process now consists of two steps:
Signing in to the Vendor PortalThe User and Password dialog boxes and the Register button disappear. SSO sign-in window is displayed instead. Changing the passwordAfter the first successful SSO login, the password reset fields in > My Account > Credential cardare inactivated. Limited permissions for new usersIn 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
|
Expand | ||
---|---|---|
| ||
Recruitment settings for Vendor PortalAll 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 PortalThe 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 | ||
---|---|---|
| ||
Changing the passwordAfter the first successful SSO login, the Password Change section in Client Portal > > My account > Settings tab becomes inactive Adding contact personsThe +Add contact person button in the Contact Persons tab in the Account Preferences pop-up is inactivated. |
Expand | ||
---|---|---|
| ||
Editing clients' system accountsIn the Home Portal > Client profile > Main Data tab > System Accounts tab, the following buttons become inactive:
Clients' contact persons' password resetthe 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.
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=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.
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
braIsbranches. 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,
thenwill 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
to handle no possibilitydo you handle the impossibility of signing in to the
PartnerClient Portal using a
PartnerClient account (and that the only real users are
PartnersClients' 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 manageare 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.
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|