Table of Contents 

Introduction

Set Up SSO on Chatham Direct Using SAML 2.0


Introduction

Single sign‐on (SSO) to ChathamDirect allows you to validate user access against your system, rather than having separate user passwords managed by Chatham. Chatham supports Identity Provider (IDP) Initiated and Service Provider (SP) Initiated SSO using SAML 2.0. 

 

This document is addressed to those IT professionals who will act as Administrators of the SSO feature in ChathamDirect. 

 

Note: Users must be created in Chatham’s system prior to logging in with SAML. You have the option to use the email address of the user, or to specify a unique SAML identifier for every user. Permissions and roles will be managed within Chatham’s website. 

 

Set Up SSO on Chatham Direct Using SAML 2.0
Steps to Setup

Log into ChathamDirect with an account having the administrative permission. Navigate to 
the following: 

  • In the upper-right corner, click your name 
  • In the “My Company” area, click Administration 
  • On the left menu, click SSO 
     

Note: Your user account in ChathamDirect must have the permission granted to manage the SSO module. If you do not see the menu items listed here or are presented with an error, or denied access, please contact your Chatham representative for assistance. 
 
 

Once you are in the SSO menu, you will be presented with the choice for IdP or SP initiated configuration options, which will guide you through set up: 


Choosing the login initiation method: Depending on how your company’s SSO is configured, you will want to choose the appropriate option for login, whether that is through IdP or SP initiation. Once the option is set, click Next:

  

Acquiring ChathamDirect metadata XML options: The second configuration menu allows you to choose the method which you will use to consume the ChathamDirect metadata. Depending on the configuration requirements of your IdP, there are two options: 

 

1. Use the ChathamDirect metadata – you will be presented with the option to download an XML file, or to use our metadata endpoint. 

2. Do not use the ChathamDirect metadata – a consumer endpoint URL for user login will be displayed. 

If you choose not to use the ChathamDirect metadata XML, then you will need to configure this manually. You will be presented with the URL where your identity provider will need to post the SAML assertion.  


**For SP-initiated SSO only – You will also need to download the ChathamDirect public certificate and load this into your identity provider to receive login/logout requests from ChathamDirect. 
 

Note: Depending on your company’s needs, your data may be split over more than one organization/account in ChathamDirect. Each organization within ChathamDirect that is set up for SSO will receive a unique Consumer Endpoint URL. 

 

Client metadata XML options: If your identity provider has a publicly accessible URL that exposes its metadata, our system allows you to provide your metadata via the metadata URL, which should be available in your IdP configuration. SP-initiated SSO only – This will also configure the identity provider service URL and logout URL. If your company changes its certificates, you will need to come back to the setup menu and click save to update your certificates. 

 

Public Certificates: If you are providing your metadata URL above, your public certificate will be automatically acquired by our system. If you are not providing your metadata URL, you will be presented with the option to set up your public certificate on this screen. SP-initiated SSO only – You will also need to manually configure the identify provider service URL. 

 

SSO Settings: Once the main configurations are entered for your organization, there is one final step with additional setup options available which varies based on the SP-initiated or IdP-initiated selection. 


Enable SSO for your company: This will enable or disable SSO.   
 

What is the Email/Identifier field in your metadata XML: This is the location of the SAML identifier that is contained in the assertion sent from your IdP. There are two options: 

  1.  The most common configuration is that the NameID tag in the SAML assertion will contain this identifier.  
  2. Alternatively, this identifier can be provided in a custom attribute within the assertion. If this is your configuration, provide the attribute name. 
     
    Note: By default, ChathamDirect will check the value provided as the SAML identifier against the username and email address user account fields. If you would like to use a custom SAML identifier (not email address), you can optionally specify this value on the user profile in ChathamDirect in the “Client Identifier (SAML Id)” field. 

Log users out of your identity provider when they log out of ChathamDirect (SP-initiated only): This option will send your identity provider a single logout request when a user chooses to log out of ChathamDirect. If you would like your users to be logged out of your identity provider when they log out of ChathamDirect select this option. 

 

Will you be using a custom login error page: This is the URL that a user will be redirected to for certain errors that occur during the SSO workflow. If this is not specified, the user will be redirected to a ChathamDirect error page. 
 
SECURITY NOTE: To avoid potentially exposing information to a malicious actor, the custom error URL is only used after the system has validated the SAML assertion. 
 

Will you be using a custom logout page where people will be redirected to on logout from ChathamDirect? (IdP-initiated only): This is the URL that a user will be redirected to upon logging out of ChathamDirect. If this is not specified, the user will be redirected to the ChathamDirect login page. 
 

Allow users to log into ChathamDirect using username/password authentication: Once SSO is enabled for your organization, username and password authentication is disabled by default. Alternately, if you would like all of your organization’s users to be able to use either SSO access or username/password authentication, you can enable this option. 
 

Send SAML messages to identity provider using a POST or GET method (SP initiated only): This describes the HTTP method that ChathamDirect uses to send a SAML message to your identity provider. It can be sent as a POST or GET (redirect). This will need to match the type of call your identity provider is expecting. 

 
Please contact your ChathamDirect representative if you would like more information on this setup, or if you need any additional assistance.