Your Contributor Node can be configured using SAML 2.0 to support single sign on (SSO). We note 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 signed in and control access to the Contributor Node.

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

Prerequisites

  • You have installed your Contributor Node

  • You have confirmed your Identity Provider supports SAML 2.0

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

  • You 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.

  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

{
"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 enabling 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.

Example

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

2. Add below to docker-compose.yaml

environment:
- ...
- HITCH_SAMLENABLED
- HITCH_SAMLBASEURL

volumes:
- ./<IDP metadata filename>:/metadata.xml:ro

3. Restart the Contributor Node using contributor.sh

# 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.

# 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. Check your IDP logs - configuration and connectivity logs.

Related Articles

Did this answer your question?