Basic SSO configuration
Check the compatibility
Once the Single Sign-On is activated on the license server, it’s time to connect the selected XTRF portal with the external Identity Provider compatible with the OpenID Connect standard. Some of the popular Identity Providers are Google, Microsoft Azure, GitHub, Paypal, and Salesforce.
XTRF SSO internally uses Google APIs 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 authorization endpoint URL and token endpoint URL on the XTRF configuration page.
All top Identity Providers use protocols compatible with the one used by XTRF.
Register with the Identity Provider
To connect with the Identity Provider, you need to register XTRF as a client application on their server:
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, switch the toggle in the top right-hand corner to enable the SSO for this specific portal.
Copy the Callback URL. It is the address you will be redirected to after your application is authorized. You will need it for the registration form.
Go to the Identity Provider’s web location and fill out their registration form. Here are the steps to follow for the most popular Identity Providers:
Instructions for Google
Instructions for Microsoft Azure
Instructions for GitHub
When the registration process is complete, you will receive two unique variables that will be needed later:
Client ID
Client Secret
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 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 of the access request used during advanced configuration (e.g., for Google: openid email profile; for ActiveDirectory: openid).
User requirements
Requirements for Home Portal Users
Home Portal SSO will allow users who already exist in the XTRF System to sign in. It is crucial to remember that users will be mapped by e-mail address.
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 email 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 of 255 case-sensitive ASCII characters. |
Requirements for Vendor Portal / Client Portal Users
There is no way to sign into Vendor / Client Portal with SSO by using an account set up for an enterprise. Only contact persons within the enterprise account will be recognized by SSO as system users.
Advanced SSO configuration
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 he or she can access the XTRF TMS instance (Service Provider).
The authentication process on 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.
General XTRF SSO configuration architecture
This feature is activated by the XTRF feature toggle on the License Server - contact XTRF Support Team for activation.
Compatibility
XTRF SSO internally uses Google API’s Client Library to communicate with the provider over OAuth 2.0 protocol. 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 Authorization Endpoint URL and Token Endpoint URL on XTRF configuration page.
SSO Provider Configuration
On the SSO provider side you need to register XTRF as a client application. During this process the most important part is to configure the Callback URL (you can find the proper 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
To configure SSO using Azure AD, please go to 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 New client secret:
You will receive an ID and secret value to use in XTRF configuration.
For another approach, see https://docs.pivotal.io/p-identity/1-11/azure-oidc/config-azure.html
Additional resources:
XTRF basic configuration
Basic configuration includes the configuration of the following parameters:
Auth URL - the endpoint for authorization server. It is used to get the authorization code (e.g. https://id.yourdomain.com/adfs/oauth2/authorize).
Access Token URL - the endpoint for 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 - the client identifier issued to the client during the application registration process.
Client Secret - the client secret issued to the client during the application registration process.
Scopes - the scope of the access request. It may have multiple space-delimited values. Scopes are specific to other services the authentication provider grants access to. The user may be granted specific scopes too, so the service provider can access other service providers on behalf of the user (i.e. user profile information). Value OpenID is required.
Example (Google, ActiveDirectory): openid email profile
All values are required.
XTRF SSO Configuration Form
Home Portal - Sign in
Requirements
Home Portal SSO will allow signing in for users already existing in the XTRF System. It is crucial to remember that users will be mapped by e-mail address. 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: