Configuring Single Sign On

Overview

This tutorial will walk you through the configuration of your ConceptShare account to use SAML for single sign on.

Before you begin …

Terminology

• SAML 2.0 (referred to here simply as SAML) is version 2 of the Security Assertion Markup Language; a standard for exchanging authentication and authorization data between security domains.
• Single-Sign-On (SSO) refers to a broad spectrum of methods, standards, and specifications all of which ultimately facilitate a user's ability to log into various services by leveraging existing credentials from another service.
• Identity Provider (IdP): refers broadly to the functionality, frameworks, and infrastructures that collectively work to provide the authorization and authentication services.
• Service Provider (SP) in the context of SAML, refers to products (including SaaS) which provide some utility to users, and require authorization and authentication services from an identity provider.
• SP initiated SSO when the login workflow starts at the SP (any product) and the user is redirected to the IdP to get authorization, it's referred to as SP initiated SSO, since the SP explicitly triggers the SSO workflow.
• IdP initiated SSO also referred to as unsolicited login; this is a method of triggering a SAML login to an SP from the IdP directly.
• Assertion is a package of information that supplies one or more statements made by a SAML authority (usually the IdP). Typically, an assertion will contain details about the authorization details of the user in question, various relevant attributes associated to that user, and an authorization decision as to whether or not the user was authorized.
• Claim Rules - When establishing a trust relationship between an IdP and SP, the IdP needs to be told what user attributes the SP will need in the assertion, in order to be able to grant the user access. These attributes are collectively referred to claim rules.
• Signing Certificate is a digital certificate, which contains the public key used to sign messages by SPs and IdPs so that the counter party can verify that the messages are in fact originating from the trusted source, and not some malicious 3rd party impersonating one of them.
• Encryption Certificate is a digital certificate, which contains the public key used to encrypt the SAML requests/responses between SPs and IdPs so that the messages can't be read if intercepted in transit by malicious 3rd party.
• Federation Metadata URL an IdP generated URL which a Service Provider (ConceptShare) can use to auto-configure all, if not most, of the SAML settings needed to connect to it. In some cases, this may be an XML file, and not a URL.
• Relying Party Trust Metadata URL a ConceptShare URL which your IdP can use to auto-configure all of our SAML settings. This URL contains the certificates, endpoints, and other information necessary for the IdP to communicate with ConceptShare. See the pre-requisites section for further details.

Prerequisites

• An enterprise account in ConceptShare
• An Identity Provider (IdP) which supports SAML 2.0 (ex. ADFS 2,3 & 4, OKTA, etc.)
• Have either an Account Administrator role, or any custom role with permissions to Manage account SAML settings in ConceptShare
• Someone on your team capable of configuring your IdP to establish a Relying Party Trust with ConceptShare. Basically, you (or your IT team) need to know what IdP you have, and how to configure it so that your IdP trusts ConceptShare requests to authenticates your users and let us know if the authorization was successful.

Setting Up SAML in ConceptShare

1. Navigate to the top right corner GEAR icon and select SAML Settings from the menu.

2. Set Is SAML Enabled to Yes and hit Save in the top right corner of the screen. This will cause ConceptShare to generate the Relying Party Metadata information which will contain all the details your IdP Will need to establish trust relationship with ConceptShare in XML format, which nearly all IdPs can use simply by pointing to the URL where this information is surfaced.

Relying Trust Metadata URL: https://<your_conceptshare_account_url>/saml.ashx?f=metadata 

ex. https://companyabc.conceptshare.com/saml.ashx?f=metadata

If you navigate to the above URL after enabling SAML and saving, you should see XML data containing the details about the SAML service description, the required fields and bindings, and our x509 signing and encryption certificates.

3. If you have a Federation Metadata URL or equivalent, this is going to be pretty easy; just enter it into the URL to config XML field and hit Load Settings. If the URL contains the necessary information, you should see the your configuration details automatically populated in the UI.

Once you've reached this point successfully (and have saved your settings), all the necessary ConceptShare configuration is complete.

Next, you'll configure your IdP to accept ConceptShare's authentication requests, and set up the Claim Rules so that when a user authenticates via SAML, your IdP sends us the correct attributes and relevant details about that user so we know how to identify them in ConceptShare.

Configuring your IdP

Regardless of the nuances and specifics for each IdP when it comes to setting up a new SAML endpoint, there a few points which apply to all configurations.

1. Whether you use our Relying Party Trust Metadata URL, or whether you choose to manually configure your IdP to set the correct HTTP Bindings, expose the SSO End-point, and use our x509 certificates for signing and encryption, your IdP will need these values.

Relying Trust Metadata URL: https://<your_conceptshare_account_url>/saml.ashx?f=metadata
ex. https://companyabc.conceptshare.com/saml.ashx?f=metadata

When you enabled SAML in ConceptShare, it will expose all the necessary details your IdP needs to communicate with ConceptShare in XML form at the URL posted above. How your IdP will use our Relying Party Metadata URL and where it can be ingested depends on the IdP and is outside the scope of this tutorial. For those details, you'll need to reference the documentation for your specific IdP.

2. Once you've configured your IdP to communicate with ConceptShare, you'll need to configure your IdP to map 3 key pieces of information and ensure that they are sent to ConceptShare in the event that a user successfully authenticates. ConceptShare requires the following 3 attributes from your IdP :

2.1. <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"> mapping to the same email address as the user's ConceptShare username

In some organizations, it's common practice to have user's with multiple domains and emails. When mapping your IdP's email fields to that of the SAML attribute, be especially careful to map the username to the correct field in your IdP. Otherwise, ConceptShare will see authetication requests for usernames it's never encountered before and will not be able to correctly identify and authenticate these users.

2.2. <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"> mapping to the user's last name

2.3. <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"> mapping to the user's first name

Here's a sample of what that might look like as captured in a SAML authentication request:

<saml:AttributeStatement>
    <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
       <saml:AttributeValue>testy.mctestface@conceptshare.com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
        <saml:AttributeValue>McTestFace</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
        <saml:AttributeValue>Testy</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement></code>

Once you've reached this stage in the tutorial, your IdP and ConceptShare should be configured to autenticate users via SAML. You can test to see if the end-to-end solution is correctly configured by testing the SAML login feature for a test user that has an account in ConceptShare, and is correctly configured in your IdP.

NOTE: your test user needs to already have a user profile in ConceptShare. You should also explicitly verify that their username (email) matches that which your IdP will be sending in the SAML response.

Additional SAML configurations

Force SAML

Depending on your needs as an organization, there are a few different ways to leverage SAML SSO for your account.

1. FORCE everyone to use SAML
2. FORCE only certain users with specific email domains to use SAML login
3. OPTIONAL for all users

You can configure ConceptShare to use the SAML authentication mode of your choice in the SAML Settings, in the Force SAML section:

JIT Provisioning

Enabling Just In Time (JIT) Provisioning allows users that are new to ConceptShare, and have not explicitly been provisioned with a ConceptShare account by an account admin to automatically have their user profile created dynamically, provided that they can successfully use SAML and authenticate with their IdP.

Using the Default account role and Default project role drop-down menu, you can specify what default roles are assigned to new users who have had their user profiles automatically provisioned. It’s advisable to use a role with limited access until an account administrator can set a more appropriate role.

As an example, user Bob (bob@acme.com) has never used ConceptShare and has not been provisioned with an account, but Bob can successfully authenticate into Acme’s Identity Provider.

If JIT Provisioning IS NOT ENABLED: when Bob gets redirected back from the IdP after successfully authenticating, the IdP will send ConceptShare Bob’s name and email address, and he will see an error stating that he’s not a recognized user, and that he should contact an account administrator who can provision an account for him.

If JIT Provisioning IS ENABLED: when Bob gets redirected back from the IdP after successfully authenticating, the IdP will ConceptShare his name and email information, and ConceptShare will recognize that there is no existing user with the email. He will then have a new user account created with the email, and name as sent from the IdP. He will initially be assigned the account and project roles as specified by the drop-downs and can begin to access whatever areas of ConceptShare his default account and project roles will permit.

Customize SAML User Interface

To help streamline the login experience for users, ConceptShare allows you to customize nearly every element of Login interface.

If you force SAML by domain, item #5 shows the error message an end-user from that domain would see if they tried to use the standard authentication method instead of using SAML login button on the left hand side.

Each of the numbered elements above can be customized by navigating to the SAML Settings, under the SAML Login Screen Details