Our Single sign-on (SSO) implementation is very flexible, as we do not require that the Identity Provider (IdP) server be able to directly communicate with the Flow Production Tracking server or vice versa. The flow of information which goes from one to the other is signed and transits via the client application. Usually this will be the browser that connects to Flow Production Tracking.

The IdP configuration must be done first. The IdP must send to Flow Production Tracking the login_id, which maps to the Flow Production Tracking login of the user. This is the key link between the two systems. In the context of an existing Flow Production Tracking site transitioning to SSO, please ensure that what is sent by the IdP matches the existing login in Flow Production Tracking. Failure to properly align the login_id sent by the IdP and the Flow Production Tracking login may result in duplicated users.

When transitioning an existing site, the first step is to audit the login used in Flow Production Tracking. If it is not possible, or too complicated, to align the two sets of logins, Flow Production Tracking offers a way to deal with this issue for existing users. Learn more in the Flow Production Tracking Administrator section.

We have split the configuration guide in two sections: for the IdP and for the Flow Production Tracking administrator.

IdP Administrators

Flow Production Tracking uses SAML 2.0 to implement SSO support. It is a standard that has been used for a number of years and it is supported by most of the IdP providers we have considered.

Every IdP system has a different mechanism to manage them. We will offer example integrations in ADFS and Okta, but things may differ in your environment.

The SAML Attributes

In your IdP configuration, you will need to add attributes to be passed on to Flow Production Tracking.

The SAML2 response payload must contain the following attributes. The Attributes, with a name format of Unspecified or Basic,  can be defined:

Name	Type	Presence	Notes
login_id	string	Mandatory	The login ID the user will have in Flow Production Tracking.
This must be unique within Flow Production Tracking, and consistent from session to session.
firstname	string	Mandatory	The user’s first name.
lastname	string	Mandatory	The user’s last name.
email	string	Mandatory	The user’s email address.
access	string	ADFS: Mandatory
Other IdPs: Optional for Flow Production Tracking version 8.11.0.4033 or later. Mandatory for previous versions.	Can only have a value of true or false.
If true, the user will have access to Flow Production Tracking.
This attribute is only mandatory for ADFS. If not present, access to Flow Production Tracking is implicitly true.
groups	string	Optional	If not present, or empty, the user’s permission group will not be modified from its current value. For a new user, the default user permission group will be used, as defined in the Site Preferences. If it is present, it should correspond to the name of one of the permission groups defined in Flow Production Tracking. If the name does not match, the user will be granted the default user permission group. ex: “Admin”

Notes

• The access attribute is required for ADFS configurations because it only validates the username and password and sends claims to Flow Production Tracking. While other IdPs will only let users access Flow Production Tracking if they have been granted access. The username and passwords may be good, but they do not suffice.
• The groups attribute is optional, and if absent (or invalid) will not modify the user’s permission group. Given the added complexity of populating this attribute, we strongly suggest to leaving it out, at least initially, to facilitate the initial configuration. This can be managed by the Flow Production Tracking Administrator.
• We do not use the NameID provided in the SAML payload. Instead we rely on the client-provided attribute login_id.

There are a number of strategies that can be used to decide on the login_id, access, and groups.

The login_id must be unique and constant. Email addresses or names may seem like good candidates, but it is important to understand what needs to be done should they ever change (e.g., someone changes their last name).

For access and groups, one common strategy in a Windows environment is to use Active Directory Security Groups. The presence of a user in a given group is reflected in the attribute value.

We strongly suggest to leaving out the groups attribute when first configuring the IdP. Then you can decide later if it is desirable to manage this centrally or if it can be left to Flow Production Tracking Administrators.

The SAML Endpoints

The Flow Production Tracking server defines two SAML specific endpoints. These will be active only if SAML is set as the Authentication method, or when testing your SAML configuration.

The following endpoints will be necessary when you configure your IdP for Flow Production Tracking. These endpoints will become functional only after SAML is enabled on your site, giving an error otherwise. It is suggested that your IdP be configured manually as opposed to using a metadata file.

URL	Notes
https:// YOUR_SITE_URL /saml/metadata	The SP endpoint where Flow Production Tracking publicizes its other endpoints.
https:// YOUR_SITE_URL /saml/saml_login_response	The endpoint where the IdP must send its signed/encrypted claims to Flow Production Tracking.

Identity Provider (IdP) Configuration

The next step is to configure your identity provider. While we can't provide guides for every possible provider, here are convenient step-through instructions for 2 of the most popular:

• Okta Configuration Guide
• Active Directory Federated Services (ADFS) Configuration Guide

The next steps

Now that you have configured your IdP, your Flow Production Tracking Administrator is ready to configure and test Flow Production Tracking with the required information.

Your Flow Production Tracking Administrator will need:

• the SAML 2.0 Endpoint (HTTPS) URL,
• The Public Certificate used by the IdP to sign its payloads, and
• The Identity Provider Issuer string.

The actual name used for these may change depending on the IdP being used.

Ideally, you will want to be available during the Flow Production Tracking configuration to help with troubleshooting and fixing any issues.

Flow Production Tracking Administrators

Before attempting to configure Flow Production Tracking, you need to wait until the IdP is configured. Once that is done your IdP Administrator will provide you with the information needed by Flow Production Tracking.

Configuring Flow Production Tracking

After logging in as an Administrator, you need to go to the Site Preferences page, via your settings menu in the top right corner:

Flow Production Tracking User Menu

Proceed to the Authentication pane and open it up:

Flow Production Tracking Authentication Pane

If you do not see the ’SAML Authentication’ radio button and section, please contact Flow Production Tracking Support so that it can be enabled.

You can now enter the information by opening up the SAML Authentication section:

Flow Production Tracking Authentication Pane Settings

• SAML 2.0 Endpoint (HTTPS): The URL on the SSO backend where Flow Production Tracking will redirect for the Authentication.
• Public Certificate: The certificate required to communicate with the IdP.
• Identity Provider Issuer: The entity ID for the service, as defined by the IdP.
• SSO Configuration (YAML Format): Additional configuration settings. See the next section.

Do you need to use additional configuration ?

The SSO Configuration panel allows for additional configuration, following the YAML format. These options are used only in special cases.

The following is the list of accepted tokens and sample uses. Unknown tokens will simply be disregarded. Improper formatting or erroneous values may affect the whole set of configuration. Please be careful.

Encryption

By default, the SAML payloads are only signed with the IdP certificate. It is also possible to encrypt the SAML payload. To achieve that, a new certificate needs to be generated, adding the private key to Flow Production Tracking and the corresponding public key to the IdP config. The actual steps to add the public key to the IdP depend on the vendor, please refer to your IdP documentation. The private key will be configured in Shogun using the following YAML structure (replace KEY with your private key):

service_provider:
    private_key: "KEY" # the key used for encryption
security:  embed_sign: true # embed the signature in the SAML header
    authn_requests_signed: true # authorization requests are encrypted
    logout_requests_signed: true # logout requests are encrypted
    logout_responses_signed: true # logout responses are encrypted

Single Log Out (SLO)

By default, we do not make use of SLO. Should you need it, it can be configured with the following token:

identity_provider:
    slo_target_url: https://single.logout.url

Ignore some fields in update

As mentioned before, Flow Production Tracking considers the IdP as the authoritative source for user information. Any information in Flow Production Tracking will be updated from the IdP at login and when the claims are renewed.

In some particular circumstances, it may be necessary to protect the information set in Flow Production Tracking by an Administrator and prevent it from being updated with the IdP information.

The list of allowed tokens are: firstname, lastname, email, and groups.

ignore_updates:
    - email

Auto-provisioning

Default: true

When auto-provisioning is enabled, any user who is granted access to Flow Production Tracking but does not exist in its database will automatically be created with the information given by the IdP. If no group is given, the user will be assigned Flow Production Tracking’s Default User Permission Group value, as indicated by the Site Preferences’ Advanced settings.

Automatic user creation is often not desirable. The new user will not have access to the relevant projects and will require the intervention of a Flow Production Tracking Administrator to fix. It is usually better for the Administrator to create the users in advance, with the proper permissions and the correct login. This will make the user’s experience easier.

autoprovision: false

Skip sending email upon SSO activation

Default: false

Whenever SSO is activated or deactivated, an email is sent to all of the active users. This email lets them know about the state of SSO and any action they need to take.

We strongly recommend that you turn off the activation emails when doing the initial tests on your Staging server or when doing tests on your Production server. This avoids confusion for your users and unnecessary support calls.

skip_activation_email: true

Use a secondary browser window to renew the user credentials

Default: false

Flow Production Tracking on the web browser uses an iframe to renew the user’s claims against the IdP server. Some IdP systems do not allow clients to use an iframe for authentication. For example, Okta’s default configuration denies the use of iframes unless explicitly changed by an IdP Administrator. In the case of Okta, this is a system-wide setting that will affect all other applications, not just Flow Production Tracking. Your IdP may have similar limitations or restrictions.

To get around this constraint, Flow Production Tracking will open a secondary browser window in the bottom left corner of the screen. It asks the user not to close this window. Flow Production Tracking should be configured with this setting if iframes are not allowed.

saml_claims_renew_iframe_embedding_disabled: true

Testing your configuration

Once you have entered the required values, save your settings but do not set the authentication mode to SAML Authentication yet. Use the Test link to validate your configuration first. You will likely need to allow Flow Production Tracking to open pop-up windows.

We strongly suggest that your IdP Administrator be present when doing your tests. This can help when troubleshooting.

Failure

Flow Production Tracking Test Failed

When this occurs there should be some indication, pop-up, or output to help you identify the problem. If you and your IdP Administrator cannot locate the issue, you may need to open a Flow Production Tracking Support ticket so that we can have a look at the server logs.

Success

Flow Production Tracking Test Success

If the test is successful you can proceed to the next steps.

The next steps

Now that the configuration is working, you are ready to proceed.

Test on your Staging server first

This has been mentioned a few times before, but we really must stress the need for this step. It helps ensure that all of your tools, scripts, and third party applications are communicating correctly with Flow Production Tracking. You must confirm that all the pieces of your production pipeline are working as expected. Once SSO is enabled on your Production site, stability is the main concern.

Before SSO can be enabled on your production site, we need a clear and precise statement from you indicating that all of your tests in Staging were successful. This also lets our Support team keep a look out for SSO related issues on your site.

Enabling SSO

On your Staging site, the email notification should be turned off to prevent confusion for your users. You will likely be cycling a few times, enabling and disabling SSO.

On your Production site, you might also want to temporarily turn off email notifications if you plan on doing tests. Enabling SSO will terminate all ongoing sessions on the site, except for the user changing the configuration. This should be done during an off-peak period, when few users are interacting with Flow Production Tracking.

While an email will be sent to all the active users once SSO is enabled, you may also elect to send out a notification email prior to that. This email can explain to the users why and when this is being done, and who they should contact if they run into any issues.

The Flow Production Tracking login flow will try to fix initial login issues, if possible. Users will have the option of linking their existing accounts based on emails or authenticating themselves with their old username and password. While this may provide a way to overcome an initial connection, it is also complex and error prone. It is possible that duplicate users will be created erroneously, resulting in support calls and being charged for those duplicate users.

The goal is to make the transition to SSO transparent to your users. To that effect, there are a few steps that can be taken to make the transition seamless.

Easy transition for existing users

The core of the authentication process revolves around the match between the login_id provided by the IdP and the existing Flow Production Tracking login. An audit of the existing Flow Production Tracking user base should be done to validate that there is a constant rule used to assign login values, and to ensure that the IdP will be in a position to send a matching login_id.

When there is a match, users will connect with their Flow Production Tracking site immediately, without any additional steps or input on their part. This is the ideal situation.

As a Flow Production Tracking Administrator, you can take steps to resolve cases where Flow Production Tracking login naming is inconsistent or when it is not possible to easily ensure that the IdP sends out the correct login_id.

First solution:

Simply change the user’s Flow Production Tracking login to match the IdP login_id. You will need to let the user know what the new username is. Should SSO be turned off, they will need the new username to connect to Flow Production Tracking, using their old password.

Second solution:

Link the IdP account with the Flow Production Tracking account:

1. Connect to your Flow Production Tracking Site using an Administrator account.

2. Navigate to the People page:

   

3. Ensure that the column Single Sign-On Login is visible:

   

4. Edit the field for the problematic user and enter the login_id send out by the IdP.

   

5. Now the accounts are linked and the problematic user will be able to log in as the proper user.

You may have to follow these steps for a number of irregular Flow Production Tracking logins.

Inviting and creating new users

There are two ways to add new users when SSO is enabled. In both cases, it is mandatory that the IdP be updated to allow access to these users prior to taking any actions in Flow Production Tracking.

1. Connect to your Flow Production Tracking Site using an administrator account.

2. Navigate to the People page:

   

3. Depending on the situation, you have two options:

• The first option is to invite a new user. This is the default option. Clicking on the + Person button will bring up the Invite dialog:

  
  
  This dialog will send out an invitation email to the user. No changes are made within Flow Production Tracking. The user must already have been granted access to Flow Production Tracking in the IdP.

  If autoprovision is set to false, the user will not be able to use Flow Production Tracking until a user is created by an Administrator.

  Otherwise, on first login the user will be presented with a dialog asking them if they want to link with a previous existing account or create a new user.

  The former choice will lead them to a page where they need to authenticate using the Flow Production Tracking username and Flow Production Tracking password of the previous account. The latter choice will create a new user which does not have access to any project.

  Note: Sending an invite may not be the ideal choice to add a new user.

• The second option is to create a new person. Click on Create a new Person now to bring up the old user creation dialog:

  
  
  This will effectively create a new user in Flow Production Tracking, with the specified access, and also send out an invitation email to the specified address. Be careful with the information entered, as it may be updated by the IdP claims when the user initially logs in (unless prevented by the Ignore some fields in update option).

  You may find it useful to modify the dialog by clicking on more fields and adding the Single Sign-On Login field. This allows you to enter the additional information to ensure a seamless connection by the new users.

  Note: This is the preferred method for adding users.

Login flow in Flow Production Tracking when SSO is enabled

When SSO is enabled, Flow Production Tracking has to make additional checks before the user can connect. This is even more the case on the first connection. Here is the logic behind the login flow:

Login Flow

Two important situations that may occur are account linking and user creation. In either situation, the user will need to proceed through a set of steps, which may be complicated for them.

To make their experience as seamless as possible, the Flow Production Tracking Administrator should be the one creating the users and/or linking the accounts. This requires more work on the Administrator’s part, but it is beneficial to the users. See Easy transition for existing users for more information.

Accessing your Flow Production Tracking site with internal tools and third-party applications

Any internal tools or scripts that use a username / password pair to initiate a connection with your Flow Production Tracking server will need to be modified.

Some of the options available:

• Use the Authentication module offered with the Flow Production Tracking Toolkit (will require PySide/PyQt).
• Use Flow Production Tracking Desktop to handle authentication and obtain the session token from it.
• Implement your own SSO Login flow to your IdP. We can provide the high-level steps required, as well as additional technical information.

For third-party applications, you will need to contact the individual developers if SSO in Flow Production Tracking is not supported.

Wrapping up

For existing users, ideally the login_id should match the Flow Production Tracking login. But that may not always be possible.

How to choose the login_id to be sent by my IdP

Remember the constraint that the login_id be both constant over time and unique.

Some of our clients have decided to use emails, or firstname.lastname as the login_id. This may be problematic if the user name changes. However, name changes may not happen very often, which makes this a viable choice, and will only require occasional intervention by a Flow Production Tracking Administrator.

Other clients have used their employee’s ID. While this may be resistant to changes in employee name, it is a bit delicate for Flow Production Tracking Administrators to handle these. It is not obvious which employee the ID maps to, and can lead to input errors.

Additional information

Should you encounter any serious issues during the configuration process, please contact our Support team.

After the initial onboarding meeting, we are also available to help during the initial configuration or for troubleshooting.

Any suggestions or comments you have on this guide will be appreciated. If you use IdP that we have not documented, we would like to improve this guide by adding the set up instructions you followed, as well as screenshots.

To learn more, please see SSO in Flow Production Tracking: An Administrator’s guide and Single Sign-On troubleshooting.