Browser SSO Guide 2020.1.0

Dotmatics Limited
The Old Monastery, Windhill, Bishops Stortford, Herts, CM23 2ND, UK

Phone +44(0)1279 654 123 | Fax +44(0)1279 653 088 | www.dotmatics.com
Registered in England & Wales No. 5614524
Confidential - ©Dotmatics Limited
SSO Configuration Guide for Dotmatics Browser
2020.1 .0
Assumptions and Requirements ............................................................................................................. 3

SSO .......................................................................................................................................................... 3
SAML 2.0 SSO .......................................................................................................................................... 3
Supported IdPs ........................................................................................................................................ 4
IdP Configuration .................................................................................................................................... 4
Gather SAML Configuration .................................................................................................................... 4
Browser Generic SSO Configuration ....................................................................................................... 5
1. Configure sso.properties ............................................................................................................. 5
2. Store sso.<provider>.<key>.metadata.xml ................................................................................. 8
3. Enable SSO .................................................................................................................................. 9
4. Debug / Reload SSO Configuration ............................................................................................. 9
5. Create Browser Users ............................................................................................................... 10
6. Test SSO .................................................................................................................................... 10
Studies Authenticate Experiments........................................................................................................ 10
Appendix A - Browser Okta IdP Configuration ...................................................................................... 11
Appendix B - Browser Centrify® IdP Configuration ............................................................................... 17
Appendix C - Browser PingFederate IdP Configuration ........................................................................ 20
Appendix D - Browser ADFS Configuration ........................................................................................... 20
Appendix E - Browser Azure AD Configuration ..................................................................................... 21
Appendix F - Browser OneLogin™ Configuration .................................................................................. 22
Change Log ............................................................................................................................................ 28

2020.1 .0
This file describes a standard configuration of SSO in Dotmatics Browser. It is intended to be used
with Browser 5.5 or higher.
For assistance, please contact support@dotmatics.com or contact your local Dotmatics office, see
http://www.dotmatics.com/contact-dotmatics/ for details.
If you are using Studies, follow the steps in Studies Authenticate Experiments, below, once you have
configured SSO.
The Benefits of using single sign-on (SSO) include:
• Mitigate risk for access to 3rd-party sites (user passwords not stored or managed externally)
• Reducing password fatigue from different username and password combinations
• Reducing time spent re-entering passwords for the same identity
• Reducing IT costs due to lower number of IT help desk calls about passwords
• Centralised password management and application access control
Browser supports SSO via the SAML 2.0 standard. In this model, Browser acts as the service provider
(SP) and a third party (e.g. Okta, Centrify® , Google Apps etc.) acts as the identity provider (IdP):
Figure 1 SAML 2.0 SSO - CC BY-SA 3.0, https://en.wikipedia.org/w/index.php?curid=32521419

2020.1 .0
Browser supports a generic SAML 2.0 IdP and also has specific support for Okta
(https://www.okta.com) and Centrify® (https://www.Centrify® .com/). Most customers should be
able to use the generic provider support with an IdP of their choice.
There are additional notes for PingFederate, ADFS and OneLogin™ at the end of the document.
Additional support for specific IdP’s may be added on request.
To configure SAML 2.0 SSO you will need to configure Browser SSO login as a web application in your
IdP.
The most common settings are described below but some IdP’s may require additional settings that
are not documented here – in that event please contact your IdP and support@dotmatics.com for
assistance.
The SP SSO URL for Browser is:
http(s)://server:port/browser/api/sso/<key>/login
…where <key> is a memorable identifier that you choose (e.g. dotmatics_sso or

browser_cloud) and that you will use when configuring Browser. For example,
https://dotmatics-server/browser/api/sso/dotmatics_sso/login
You may have multiple IdP configurations, but each must use its own unique key.
Please note that if you use one of the keys provided by the default Browser installation (demo or
test) that they may be overwritten by future Browser upgrades. It is therefore recommended that
you choose your own unique key.
If required by your IdP, the Recipient URL and Destination URL should be set to the same value as
the SP SSO URL.
Browser does not require an Audience Restriction so this can be set to any value e.g. dummy.
Browser expects usernames (Name ID Format) in default format, often this is as an email address.
Browser will, by default, automatically strip any email domain “@corp.com” suffixes.
Once configured, your IdP should provide you with the following information:
IdP SSO URL – this is a link to your IdP which deals with user authentication and then redirects back
to the SP SSO URL. For example, in Google Apps, this takes the form:

2020.1 .0
https://accounts.google.com/o/saml2/initsso?idpid=short_guid_here&sp
id=number_here
IP Issuer (IPI) – this generally takes the form of a URL at your IdP. For example, in Google Apps, this
takes the form:
https://accounts.google.com/o/saml2?idpid=short_guid_here
IdP Metadata – this is an XML file containing configuration and certificate information. For example,
in Google Apps, this takes the form:
In this section, a generic SSO configuration is described.
The majority of SSO settings are stored in the …browser/WEB-INF/sso.properties file.

Entries are of the form <provider>.<key>=<value> and are case sensitive. In the example
given here, we are using generic as the SSO provider and the SSO is called demo.
Setting Description Values Required

(Yes/No)
generic.demo Enables or • 1 Yes

.enabled disables this • 0
particular • True
<provider>. • False
<key>
configuration

2020.1 .0

(Yes/No)
generic.demo. Value of your IPI For example: Yes

ipi https://accounts.google.com/o/s
aml2?idpid=short_guid_here
generic.demo. Value of your IdP For example: Yes
url SSO URL https://accounts.google.com/o/s
aml2/initsso?idpid=short_guid_h
ere&spid=number_here
generic.demo. Provides a user- For example: Generic SSO Demo No
description friendly name on
the Browser
login page
generic.demo. Specifies any • @.+ which strips any email domain No
regex replacement of “@corp.com” suffixes
the usernames • (?!) including the brackets will
returned by the always match nothing resulting in the
IdP. full username being returned
Default is @.+ In all cases, any text matching the regex

will be replaced with “” (empty string).
generic.demo. Hides or shows • 1 No
visible this particular • 0
<provider>. • True
<key> • False
configuration
from the login
page. Hidden
SSO
configurations
can still be
logged into with
the appropriate
SP SSO URL.
Default is True.

2020.1 .0

(Yes/No)
generic.demo. Specifies the get For example: RelayState No

relay parameter to
send to the IdP –
indicating where
to redirect to
after a successful
authentication
has taken place.
Default is
RelayState
generic.demo. Specifies • 1 No
fqurl whether the • 0
RelayState • True
should be sent as • False
a fully qualified
Browser URL
rather than a
relative path.
Default is False
doubleenc
whether the • 0
RelayState • True
should be sent as • False
doubly URL-
encoded value.
Default is False
samlrequest
whether the IdP • 0
authentication • True
request should • False
be sent as a
deflated, base64
encoded and URL
encoded
SAMLRequest
parameter.
Default is False

2020.1 .0

(Yes/No)
generic.demo. Specifies the For example: 9225c98b-76a2-45ec- No

issuer a5db-675de9793
issuer identifier.
There is no
default value.
adfs.demo.nam Specifies the For example: No
eidpolicyform
Name ID urn:oasis:names:tc:SAML:1.1:nam
at
Policy eid-format:emailAddress
Format and is
only used when
SAMLRequest
s are enabled.
There is no
default value.
Below is an example snippet from the sso.properties file:
Additionally, the IdP Metadata gathered during the IdP configuration should be stored in an
appropriately named XML file:
…tomcat/browser/WEB-INF/sso.<provider>.<key>.metadata.xml file.
Below is an example sso.<provider>.<key>.metadata.xml file:

2020.1 .0
You may also find files called …browser/WEB-INF/sso.<provider>.template.xml, these

should not be edited.
In Browser, navigate to Admin > Configure > System > Authentication and enable SSO
Authentication. Save your changes and you should see any enabled <provider>.<key> SSO
configurations listed:
If your configuration is not shown, double-check your settings and then select SSO reload
configurations. Save your settings to reload the SSO configuration.

2020.1 .0
If your configuration is still not shown, consult the browser log file
(…tomcat/logs/browser.log on Windows or …tomcat/logs/catalina.out on Linux)
or available in the Browser GUI (Admin > Configure > System > Logging) for error messages. If you
require further assistance, please contact Dotmatics Support, support@dotmatics.com, and attach
any relevant configuration and log files to your message.
Any users that use SSO must first be added to the Browser system as users with access to at least
one project. Usernames must match those returned by the IdP. If you intend on only providing SSO
access to your users, then use random complex passwords when creating their accounts.
Logout of Browser and you should see your configured SSO available as a login option:
Clicking on the green SSO button will take you to your IdP SSO URL and, assuming you are
authenticated there, bring you straight back in to Browser as a logged-in user.
If you are using Studies, then you will need to set the Studies Authenticate Experiments setting to
yes to ensure you can complete/countersign experiments correctly.

2020.1 .0
The setting can be found in Browser. Navigate to Configure > System > Application and enable the
setting, click the save icon at the bottom of the page.
These steps show how to configure Okta as an IdP for Browser.
Login to your Okta admin site. Click on Applications > Applications
Click on Create New App
Select SAML 2.0 and then click on Create

2020.1 .0
Give the application a name, for example Test, and click Next
In the Single sign on URL field enter the SSO URL of your Browser instance which takes the form,
http(s)://server:port/browser/api/sso/<key>/login. For example,
https://dotmatics-server/browser/api/sso/test/login. In the Audience URI
(SP Entity ID) enter dummy, and click Next

2020.1 .0
Complete the optional information on this page then click Finish

2020.1 .0
On the Sign On page, click on View Setup Instructions
Copy the:
• Identity Provider Single Sign-On URL – this will be used to populate your
okta.<key>.url setting
• Identity Provider Issuer – this will be used to populate your okta.<key>.ipi setting

2020.1 .0
Copy the IDP metadata – this will be stored as your …tomcat/browser/WEB-

INF/sso.okta.<key>.metadata.xml file
Return to the Sign On page and then assign the application to your users in the normal way using the
People and Groups tabs
Follow the Browser Generic SSO Configuration section above but instead of using the generic
provider, specify okta. Below is a sample sso.properties file where we have used the value
test as the <key>

2020.1 .0
Replace the whole of the …tomcat/browser/WEB-INF/sso.okta.test.metadata.xml

file with the IDP Metadata you copied above
Continue to follow the steps in the Browser Generic SSO Configuration section above, from “Enable
SSO” onwards, to turn on SSO. Ultimately, you should see your Okta SSO available as a login option

2020.1 .0
These steps show how to configure Centrify® as an IdP for Browser.
Login to your Centrify® manager site. Click on Apps > Add Web Apps > Custom
Click on Add next to the SAML app and then Yes on the confirmation dialog
In the Assertion Consumer Service URL field enter the SSO URL of your Browser instance which
takes the form, http(s)://server:port/browser/api/sso/<key>/login. For
example, https://dotmatics-server/browser/api/sso/testcentrify/login

2020.1 .0
Copy the:
• Issuer – this will be used to populate your centrify.<key>.ipi setting

• Identity Provider Sign-in URL – this will be used to populate your centrify.<key>.url
setting

2020.1 .0
Scroll down and click to Download Identity Provider SAML Meta data. This will be stored as your
…tomcat/browser/WEB-INF/sso.centrify.<key>.metadata.xml file
Click Save then change the application desciption to something meaningful and assign the
application to your users in the normal way using the User Access tab.
provider, specify centrify. Below is a sample sso.properties file where we have used the
value test as the <key>
…and corresponding sample …tomcat/browser/WEB-

INF/sso.centrify.testcentrify.metadata.xml file
Continue to follow the steps the Browser Generic SSO Configuration section above, from “Enable
SSO” onwards, to turn on SSO. Ultimately, you should see your Centrify® SSO available as a login
option

2020.1 .0
PingFederate is configured in a similar fashion to Okta and Centrify®.
In the PingFederate configuration, the option Always sign the SAML Assertion should be left
unchecked
The following parameters should be set for the RelayState to be honoured:
• generic.demo.relay=TargetResource
• generic.demo.fqurl=1
ADFS should be configured as an adfs configuration with the appropriate

sso.adfs.<key>.metadata.xml file.
In most configurations, we have found that double URL encoding is required:
adfs.demo.doubleenc=1
Additionally, Browser requires that the response/message body needs to be signed as well as the
assertion. This can be enabled on the ADFS server via a PowerShell command:
Set-ADFSRelyingPartyTrust -TargetName [Name of ADFS RP Trust] -

SamlResponseSignature "MessageAndAssertion"

2020.1 .0
Azure AD should be configured as an adfs configuration with the appropriate

sso.adfs.<key>.metadata.xml file.
Browser should be configured as a new Enterprise application in the Azure portal. The metadata
XML file is referred to as the federation metadata document.
In most configurations, we have found that double URL encoding is not required:
adfs.demo.doubleenc=0
The following optional settings are required for Azure AD:
• adfs.demo.samlrequest=1
• adfs.demo.issuer=GUID
The issuer ID is referred to as the Application (client) ID and the IdP SSO URL is referred to as the
SAML-P sign-on endpoint.
The IPI is referred to as the App ID URI.

2020.1 .0
In some configurations, you may have to set the NameIDPolicy Format to ensure the correct
identifier is returned by Azure AD. The default behaviour is to leave it unspecified. To specify that
the email address is returned you can use:
adfs.demo.sso.nameidpolicyformat=urn:oasis:names:tc:SAML:1.1:nameid-
format:emailAddress
Finally, Browser requires that the response/message body needs to be signed as well as the
assertion, see https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/certificate-
signing-options#certificate-signing-options. At the time of writing, this feature was only available in
certain (paid for) editions of Azure AD.
An example snippet Azure AD configuration is shown below:
These steps show how to configure OneLogin™ as an IdP for Browser. We will use a slightly modified
Centrify® configuration.
Login to your OneLogin™ manager site. Navigate to the OneLogin™ applications page, click Add App
and then add SAML Test Connector (Advanced)

2020.1 .0
Give the application a Display Name e.g. Dotmatics Browser SSO and click Save
Click on the Configuration tab and set the following parameters (note that in the following examples
we are using ‘testOneLogin as our key):
• Recipient - https://dotmatics-
server/browser/api/sso/testOneLogin/login
• ACS (Consumer) URL Validator - ^https:\/\/dotmatics-
server\/browser\/api\/sso\/testOneLogin\/login$
• Login URL: -https://dotmatics-
server/browser/api/sso/testOneLogin/login
Note that the Validator takes the form of a regex prefixed with “^”, forward slashes escaped with
backslashes and suffixed with “$”.
The other options on the page should be cross-checked against the following screenshots in case any
of your defaults have been changed. In a vanilla OneLogin™ setup, they can be left as-is:

2020.1 .0
…continued…

2020.1 .0
Click Save.
On the SSO tab, copy the:
• Issuer URL – this will be used to populate your onelogin.<key>.ipi setting

• SAML 2.0 Endpoint (HTTP) – this will be used to populate your onelogin.<key>.url
setting

2020.1 .0
Under More Actions on the top right-hand menu, click SAML Metadata to download your XML
configuration.
Edit the file as follows in order to render it compatible with a typical OneLogin™ configuration:
a) Remove the file’s XML header

b) Remove any occurrences of xmlns:ds=http://www.w3.org/2000/09/xmldsig#
c) Remove any occurrences of ds:
For example, an original versus edited comparison:
This will be stored as your …tomcat/browser/WEB-

INF/sso.onelogin.<key>.metadata.xml file.
Continue to assign the application to your users in the normal way using the Users tab.

2020.1 .0
provider, specify onelogin. Below is a sample sso.properties file where we have used the
value testOneLogin as the <key>
…and corresponding sample …tomcat/browser/WEB-

INF/sso.onelogin.testOneLogin.metadata.xml file:
Continue to follow the steps the Browser Generic SSO Configuration section above, from “Enable
SSO” onwards, to turn on SSO. Ultimately, you should see your OneLogin™ SSO available as a login
option

2020.1 .0
Date From Author Notes

Version
15DEC2020 5.5.2 DM Updated for 2020.1.0
10SEP2020 5.5.1 CC Added references to Blueprint
11JUN2020 5.50 AH Updated Azure with doubleenc=0 recommendation
19NOV2019 --- AH Updated for 5.5. Updated for OneLogin™
09APR2019 --- AH Updated Azure AD with reference to Enterprise and

enlarged screenshots.
07FEB2019 --- AH Azure AD added, PingFederate updated
09AUG2018 --- AH Double URL encoding and ADFS specific XML added
21MAY2018 --- AH ADFS note added
14MAR2018 --- RT Updated for adding reference to studies authenticating

experiments setting
29JAN2018 --- AH Updated for RelayState and fqurl parameters
27OCT2017 --- AH / CC Updated for 5.2 and added references to Reaction

Workflows and Chemselector. Added visible flag
17MAY2017 --- AH Updated for 5.1 removing build references
03MAY2017 --- AH Clarified Okta IDP template file contents
18OCT2016 --- AH Added Centrify® support
26SEP2016 --- AH First version

Browser SSO Guide 2020.1.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Browser SSO Guide 2020.1.0

Uploaded by

Copyright:

Available Formats

Dotmatics Limited

The Old Monastery, Windhill, Bishops Stortford, Herts, CM23 2ND, UK

Assumptions and Requirements ............................................................................................................. 3

Confidential - ©Dotmatics Limited

The Benefits of using single sign-on (SSO) include:

Figure 1 SAML 2.0 SSO - CC BY-SA 3.0, https://en.wikipedia.org/w/index.php?curid=32521419

Confidential - ©Dotmatics Limited

Additional support for specific IdP’s may be added on request.

The SP SSO URL for Browser is:

…where <key> is a memorable identifier that you choose (e.g. dotmatics_sso or

Confidential - ©Dotmatics Limited

In this section, a generic SSO configuration is described.

The majority of SSO settings are stored in the …browser/WEB-INF/sso.properties file.

Setting Description Values Required

generic.demo Enables or • 1 Yes

Confidential - ©Dotmatics Limited

Setting Description Values Required

generic.demo. Value of your IPI For example: Yes

Default is @.+ In all cases, any text matching the regex

Confidential - ©Dotmatics Limited

Setting Description Values Required

generic.demo. Specifies the get For example: RelayState No

Confidential - ©Dotmatics Limited

Setting Description Values Required

generic.demo. Specifies the For example: 9225c98b-76a2-45ec- No

Below is an example snippet from the sso.properties file:

Below is an example sso.<provider>.<key>.metadata.xml file:

Confidential - ©Dotmatics Limited

You may also find files called …browser/WEB-INF/sso.<provider>.template.xml, these

Confidential - ©Dotmatics Limited

Confidential - ©Dotmatics Limited

These steps show how to configure Okta as an IdP for Browser.

Login to your Okta admin site. Click on Applications > Applications

Click on Create New App

Select SAML 2.0 and then click on Create

Confidential - ©Dotmatics Limited

Confidential - ©Dotmatics Limited

Complete the optional information on this page then click Finish

Confidential - ©Dotmatics Limited

On the Sign On page, click on View Setup Instructions

Confidential - ©Dotmatics Limited

Copy the IDP metadata – this will be stored as your …tomcat/browser/WEB-

Confidential - ©Dotmatics Limited

Replace the whole of the …tomcat/browser/WEB-INF/sso.okta.test.metadata.xml

Confidential - ©Dotmatics Limited

These steps show how to configure Centrify® as an IdP for Browser.

Confidential - ©Dotmatics Limited

• Issuer – this will be used to populate your centrify.<key>.ipi setting

Confidential - ©Dotmatics Limited

…and corresponding sample …tomcat/browser/WEB-

Confidential - ©Dotmatics Limited

PingFederate is configured in a similar fashion to Okta and Centrify®.

The following parameters should be set for the RelayState to be honoured:

ADFS should be configured as an adfs configuration with the appropriate

In most configurations, we have found that double URL encoding is required:

Set-ADFSRelyingPartyTrust -TargetName [Name of ADFS RP Trust] -

Confidential - ©Dotmatics Limited

Azure AD should be configured as an adfs configuration with the appropriate

The following optional settings are required for Azure AD:

The IPI is referred to as the App ID URI.

Confidential - ©Dotmatics Limited

An example snippet Azure AD configuration is shown below:

Confidential - ©Dotmatics Limited