Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 19 Next »

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

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

 Click to expand

  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  (blue star) 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.

For example, 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

 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:

  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

 Click to expand

Groovy Script example

 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 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

 Click to expand

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

 Click to 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

 Click to expand

Signing in

Only the SSO option is available on the Home Portal sign-in page.

Changing the password

After the first successful SSO login, password management options are inactivated in the:

  1. (blue star) Personal settings menu in the top menu bar.

  2. (blue star) Configuration Icon > User Management > Users.

  3. (blue star) Configuration Icon > User Management > Users > User account > General Info tab.

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

 On the Vendor portal

Accepting an invitation to the Vendor Portal

The process now consists of two steps:

  1. A vendor receives an Activate your account e-mail and complies by clicking Join. SSO login screen opens, and the vendor logs in.

  2. 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 (blue star) > My Account > Credential card are 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.

 On the Home Portal

Recruitment settings for Vendor Portal

All the options in the Home Portal's (blue star) 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

 On the Client Portal

Changing the password

After the first successful SSO login, the Password Change section in Client Portal > (blue star) > 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.

 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.

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.

  • No labels