/
Single Sign On

Single Sign On

Owned by Danny Hannah, created
Last updated: Mar 25, 2024
6 min read

Target release

June 2018

Epic

 

Document status

PUBLISHED

Document owner

@Danny Hannah

Designer

@Amish Ladhu

Tech lead

@Danny Hannah @Rokas B

Technical writers

@Danny Hannah

QA

 

Feature Overview

SSO is a way to login to a third party platform using an identity provider managed by your internal IT team.
An example is that Convertr use Google Workplace for its main business services, we could then mandate that all systems we use must allow for sign in with Google in order to ensure we remain access control whilst enforcing our own password policies.

Prerequisites

To configure for Convertr we need the following items:

  • Documentation for IDP

  • Client Metadata XML file

  • Ideally a test account

Convertr will then need to generate the following and provide to the client:

  • Metadata XML file

  • x.509 Certificate

It’s very important that the client XML has Organisation metadata, as this is what we use to show the SSO Provider in the Convertr platform. If it doesn’t exist when the client sends it to us, you can add it manually. It will look like this:

<Organization> <OrganizationName xml:lang="en">CLIENT NAME</OrganizationName> <OrganizationDisplayName xml:lang="en">CLIENT NAME</OrganizationDisplayName> <OrganizationURL xml:lang="en">URL</OrganizationURL> </Organization>

First, generate certificates: https://www.samltool.com/self_signed_certs.php

  • Country Name - United Kingdom

  • State or Province Name - London

  • Organization Name - Convertr

  • Common Name, the domain - convertr.io

  • Valid days - 3650

  • Bits to generate the private key - 1024 bits

  • Digest Algorithm - SHA512

Generate those certs and save them in a text editor with the following filenames:

  • Private Key - private.pem

  • X.509 cert - certificate.crt

Then, generated the XML, these can be generated from https://www.samltool.com/sp_metadata.php

  • Main info

    • EntityId - https://{ENTERPIRSE}.cvtr.io/saml/sp

    • Attribute Consume Service Endpoint (HTTP-POST) - https://{ENTERPRISE}.cvtr.io/saml/login_check

    • Single Logout Service Endpoint (HTTP-REDIRECT) (OPTIONAL) - this is the SSO Logout URL from the SSO provider / client.

    • NameId Format - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    • SP X.509 cert  - copy from certificate.crt which you generated above

    • AuthnRequestsSigned - True

    • WantAssertionsSigned - True

  • Organization Info

    • Organization name - Convertr

    • Organization DisplayName - Convertr

    • Organization Url - https://convertr.io

  • Technical Contact

    • Given Name - Convertr Tech

    • Email - tech@convertr.io

  • Support Contact

    • Given Name - Convertr Support

    • Email - support@convertr.io

Click “Build SP Metadata” and it will generate the the SP Metadata XML and save with the certificate and key you generated earlier and call this metadata.xml.

Adding the SSO provider to the Enterprise

You’ll need access to AWS S3 in production to do this. You’ll need to navigate to the client bucket.
You can then add the following files to the path (if it doesn’t exist you’ll need to create that directory structure).

bucket > config > sso

Files:

  • metadata.xml - this is the one the CLIENT sent, not ours

  • certificate.crt - this should be extracted from the client metadata.xml file, you can then use this tool to format it if needed https://www.samltool.com/format_x509cert.php

  • private.pem - this is OUR one, the one you generated above

You must then send the client OUR metadata.xml file which you generated earlier.

Each SSO provider should be named according to its support in the app/config.yml on the Convertr project. If the response is using standard emailAddress as the response then is should generally work.

If this SSO is for the primary account holder (e.g. our client) then it can safely go into the default folder as below. Otherwise it will require additional development work to register it as a provider type.

Once you have all the rest in place, you should be able to see the provider registered in the User section of the platform when you add or edit a user.

PS: All certificates are encrypted and saved in Redis to avoid calling S3 each time a certificate is required. If this is a change of certificate make sure you clear the SSO cache in redis DB05 key: client-{enterpriseId}:SSO-e{enterpriseId}.

Objective

As part of Convertr’s commitment to improving security, we need the ability to support single sign on for our clients, firstly for their own users but where possible support for other users of the system (Convertr users, Publishers etc).

Convertr will support SAML2.0 requirements, meaning we will support SSO for the vast majority of services available.

User flow will be SP (service provider) led, meaning:

  • User must be added into Convertr first

  • All login happens from the Convertr platform first

  • Convertr platform will then push the user to the IdP

  • IdP will then authenticate the user and send them back to the Convertr platform

  • Convertr will then validate the logged in user is found in Convertr, either by the email address, or by some other GUID (extra development work will be required in these instances).

Assumptions

We assume that all clients will be using the SAML2.0 specification, will supply documentation and a technical contact. Ideally we will also be provided access to a test account for trouble shooting.

Requirements

Requirement

User Story

Importance

Jira Issue

Notes

Requirement

User Story

Importance

Jira Issue

Notes

1

Must be able to login with SAML provider

As a primary user of Convertr (direct client to Convertr), I should be able to login to Convertr with my IdP to centralise my credential management and enforce our own password policies.

HIGH

https://convertr.atlassian.net/browse/CON-3325

 

2

Must be able to manage assign identify providers to users

As an admin or super admin of the platform, I should be able to create users who can access Convertr and assign the SSO provider to their account, forcing them to login via IdP and not username and password.

HIGH

 

3

Should not support self signup from IdP

As a user, I must be added to Convertr by an Admin or Super Admin user, and should not be able to self register to Convertr from my SSO provider.

HIGH

 

4

Should not take data from IdP

As a user, I should manage my Convertr profile independently from the IdP profile the authentication is the only communication between the two systems.

HIGH

 

5

Must support multiple SSO providers on a single tenant

As a primary user (direct client to Convertr) I should be able to set up a user and choose my SSO provider when creating my user. When logging into the platform I should see a Login option for my IdP.

As a secondary user to the platform (a publisher or advertiser) I should also be able to sign in with an SSO provider if I have confirmed this with firstly the Primary client, and secondly with the Convertr team.

HIGH

https://convertr.atlassian.net/browse/DUU-41 https://convertr.atlassian.net/browse/DAS-839 https://convertr.atlassian.net/browse/CON-4340

 

6

Must allow for easy implementation of new SSO providers

As a developer or technical person within Convertr, I would like to be able to implement SSO where possible without requiring development work. We should have a default location which is scanned with AWS S3 which will allow for us to dynamic add SSO metadata, certificates and private keys if required.

 MEDIUM

https://convertr.atlassian.net/browse/CON-4459

 

7

 Should support logout if possible

As a user, if supported, when logging out of the platform when using SSO I would like to also be logged out of the IdP.

 MEDIUM

 https://convertr.atlassian.net/browse/CON-4547

 

User interaction and design

https://invis.io/VNYEF5PZDT2#/428316634_Login-Multistep-Sso-1

Open Questions

Question

Answer

Date Answered

Question

Answer

Date Answered

 

Out of Scope

 

Other Notes

Config for OneLogin used for SWZD:

 

 

Related content