Configuring Contributor Nodes with SAML for SSO (beta)

From release 1.7.0 your Contributor Node can be configured using SAML 2.0 to support single sign on (SSO). This feature is currently in beta. Please direct any support enquiries to support@datarepublic.com.

With SAML integration, IT departments can specify the use of their own Identity Provider (IdP) using a SAML configuration file.

The benefits are: 

  • Convenience - users can use their existing organisation account to login to the Contributor Node.

  • Security - administrators can know which users have logged in and control access by individual user account.

Enabling SSO for your Contributor Node

The instructions below are a general guide. Your IdP will have additional documentation for adding new applications to support single sign on.

Requirements

  • Make sure your Identity Provider supports SAML 2.0

  • You will need to have IdP administrator permissions for creating SAML service provider applications (e.g. Google Accounts administrator access, if using Google as your IdP)

  • You will also need to have access to the machine/VM that hosts your Contributor Node

Configuring SAML Support

Preparation

The following steps are common to all IdP providers:

  1. Determine your Contributor Node URL (you will need this later). Your URL will typically take the form of an internally resolvable hostname, as well as the UI port configured in your contributor.sh file.

    1. By default the protocol will be HTTPS (i.e. SSL enabled).

    2. Hostname will have been configured when you installed the Contributor Node and should be set in contributor.sh.

    3. Port will also have been configured when you installed the Contributor Node (default is provided) and will be set in contributor.sh.

  2. Your ACS end point will be: https://<contributor_node_host:contributor_node_port>/sso/saml/acs

  3. Your Metadata XML file will be: https://<contributor_node_host:contributor_node_port>/sso/saml/metadata.xml

  4. Your Logout callback end point will be: https://<contributor_node_host:contributor_node_port>/sso/saml/slo

All these details are also documented in this config.json file, that can be found under: https://<contributor_node_host:contributor_node_port>/sso/config.json

1 2 3 4 5 6 7 8 9 10 11 { "saml": { "enabled": true, "baseURL": "https://<contributor_node_host:contributor_node_port>/", "metadata": "/sso/saml/metadata.xml", "login": "/sso/saml/auth", "loginCallback": "/sso/saml/acs", "logout": "/sso/saml/logout", "logoutCallback": "/sso/saml/slo" } }
  • loginCallback (ACS): Assumption Consumer Service is the endpoint called by the Identity Provider upon login. The Contributor Node will then use that request to serve a cookie and redirect the user to the dashboard

  • baseURL: Refers to the URL for your Contributor Node. It must be accessible to your internal users via your supported web browser.

  • metadata (XML): Contains all the configuration for SAML of the Contributor Node. This file must be provided to the Identity Provider (either downloaded or fetched from this URL).

  • logoutCallback (SLO): Single Logout is the endpoint called by the Identity Provider upon logout. The Contributor Node will invalidate the cookie and log the user out from the IDP (if supported).

Configure your IdP

Next you need to enable SSO for your Contributor Node as a new SAML Application supported by your IdP.

We have tested the Contributor Node SAML support with Google Authentication and OpenAM. Example procedures for configuring Google as an IdP  are below. Other IdP's are being tested.

Recommendations for any IDP:

  • We strongly recommend to enable Signed Requests.

  • To verify this has worked successfully, please download idp-metadata.xml

Example: Adding Contributor Node to Google Accounts SSO

For Official Google Documentation, please visit: https://support.google.com/a/answer/6087519?hl=en

1

Open Google Admin App. Create a custom SAML - click ‘Setup my own custom app’

2

Download the IDP metadata file and copy it to the machine that hosts your Contributor Node.

Place the metadata file in the same directory as your contributor.sh is placed

3

Fill the app name and description

4

Fill the Assertion Consumer Service (or ACS) and entityID URL.

  • Your ACS URL is: https://contributor_node_url>/sso/saml/acs

  • You entity ID is:  https://<contributor_node_url>/sso/saml/metadata.xml

Select signed response option (check-box), if available

5

Skip attribute mapping as it is not currently required for Contributor Nodes.

Click 'Finish'.

6

Enable access to the new app for the required users or groups.

  • This will depend on the way your IDP is configured and what User Groups you have available





Configure your Contributor Node to use your IDP

1

Edit the settings in your contributor.sh file to enable SAML support:

  1. Set HITCH_SAMLENABLED to true

  2. Set HITCH_SAMLBASEURL to Contributor Node URL resolvable and accessible by the browser.

 

1 2 export HITCH_SAMLENABLED=true export HITCH_SAMLBASEURL=<https://contributor...>



2

Add below to docker-compose.yaml

 

1 2 3 4 5 6 7 environment: - ... - HITCH_SAMLENABLED - HITCH_SAMLBASEURL volumes: - ./<IDP metadata filename>:/metadata.xml:ro



3

Restart the Contributor Node using contributor.sh

 

1 2 # contributor.sh down # contributor.sh up -d





Troubleshooting

1

Check Docker log messages

Docker contributor logs are output as "stdout" but you can also view them using the docker command line tool.

Look up the container ID with "docker ps" and then use "docker logs" to view the most recent log messages.

 

1 2 # imageID=`docker ps --format "{{.Names}}" --filter "name=contributor" | grep _contributor_` # docker logs --since 1h $imageID





2

Check network connection errors and browser console logs using your browser's inspector tool (e.g. on the Network tab).

Check that redirects are occurring correctly and that the are no errors in HTTP responses.





3

Finally, check your IDP logs - configuration and connectivity logs.

Check that certificates are valid and there are no error messages when users try to authenticate.