Skip to content

SSO/SAML2.0 Settings

Aligning with SAML terminologies, the following terms are used:

  • Contour application acts as the Service Provider, or SP in short
  • Directory services acts as the Identity Provider, or IdP in short

Pre-requisites

Basic SAML specification and security requirements to be compliant with Contour SSO:

  • Identity Provider (IdP) supports SAML 2.0, e.g. Microsoft Active Directory Federation Services (AD FS) or Azure Active Directory (AAD)
  • The entire SAML message must be signed. Signing the SAML assertions only is insufficient, and will result in a 400 Bad Request response
  • No assertion encryption
  • The SAML protocol version is urn:oasis:names:tc:SAML:2.0:protocol
  • The NameID format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • The IdP response status code must be urn:oasis:names:tc:SAML:2.0:status:Success
  • The IdP response NotBefore and NotOnOrAfter assertion timestamps must consider system clock skew and must be set to at least one(1) minute before and one(1) minute after the current time (this particularly concerns AD FS default settings)
  • The SignatureMethod algorithm is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  • The DigestMethod algorithm is http://www.w3.org/2001/04/xmlenc#sha256

Create SP Signing Key

Contour requires signing the SAML Audentication Request, therefore a signing key needs to be created and saved into a sub-directory under the Contour web-application installation directory. e.g. a sub-directory called saml/ under /opt/api-service/.

A signing key can be created using keytool command. While please DO double check internally whether any internal requirements on signing key used for SAML integration.

Example command: keytool -genkey -v -alias contoursaml -keystore contoursaml.pfx -storetype PKCS12 -keyalg RSA -keysize 2048 -validity 365

  • -alias: Alias Name for the key entry, you can change to your preferred name.
  • -keystore: File name for the keystore file, you can change to your preferred name.
  • -storetype: Recommend to use PKCS12, which is the industry standard format
  • -keyalg: Algorithm to be used to generate the key, recommend to keep as RSA
  • -keysize: Size of the key, recommend to keep as 2048
  • -validity: Validity of the keystore in days
(base) john@Admins-MacBook-Pro saml % keytool -genkey -v -alias contoursaml -keystore contoursaml.pfx -storetype PKCS12 -keyalg RSA -keysize 2048 -validity 365

Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  John Doe
What is the name of your organizational unit?
  [Unknown]:  Technology Services
What is the name of your organization?
  [Unknown]:  ABC Company
What is the name of your City or Locality?
  [Unknown]:  Singapore
What is the name of your State or Province?
  [Unknown]:  Singapore
What is the two-letter country code for this unit?
  [Unknown]:  SG
Is CN=John Doe, OU=Technology Services, O=ABC Company, L=Singapore, ST=Singapore, C=SG correct?
  [no]:  yes

Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 365 days
    for: CN=John Doe, OU=Technology Services, O=ABC Company, L=Singapore, ST=Singapore, C=SG
[Storing contoursaml.pfx]

(base) john@Admins-MacBook-Pro saml % ls -la
total 8
drwxr-xr-x   3 john  staff    96 Jan 18 10:52 .
drwxr-xr-x  26 john  staff   832 Jan 18 10:51 ..
-rw-r--r--   1 john  staff  2641 Jan 18 10:52 contoursaml.pfx

Configure SP Metadata

  1. Click on Gear on the top right, then "Security settings"
  2. Click into "Single sign-on (SSO)"
  3. Make sure the box "SAML" is already checked
  4. Click on Configure metadat builder
  5. Click on Edit to open and full up the form
    • Deployment domain: the full URL of your Contour web app, e.g. https://contour.abc.com
    • NameID format, AuthRequestSigned and WantAssertionSigned: not editable with Contour requirements as described in Pre-requisites section above
    • SP keystore file path: the absolute path to the keystore file, e.g. /opt/api-service/saml/contoursaml.pfx with reference to the example in Create SP Signing Key section above
    • Keystore password, Alias Name and Key password as you defined in Create SP Signing Key section above
  6. Click on Save, then Confirm
  7. Download the Contour SP metadata file

The Contour SP metadata file can be shared to the Identity Provider (IdP) administrators (e.g. IAM team) in your company to configure the IdP to allow the SAML connection from Contour.

Contour SP Metadata

Receive IdP Metadata

After the Identity Provider (IdP) administrators (e.g. IAM team) in your company completed the IdP configuration to allow Contour SAML integration, you should receive the IdP metadata (e.g. an xml file) to proceed the configuration on Contour.

Configure SAML on Contour

To configure the SAML with IdP metadata, the action must be taken by 2 different superadmin users in a make-check manner.

Part 1: First superadmin user (Make)

Proceed to configure the SAML integration with the IdP metadata received from your Identity Provider (IdP) administrators (e.g. IAM team), using the Sample IdP metada below as example:

  1. Click on Gear on the top right corner
  2. Navigate to "Security settings" under the "Company Settings" on the left panel
  3. Click into "Single sign-on (SSO)"
    • The status is "Disabled"
  4. Tick the checkbox "SAML"
  5. Click on Configure SAML
  6. Select to set up the configuration using a "Metadata xml file upload" from Identity Provider (IdP) or "Manual configuration"
    • If using the "metadata xml file upload", Contour automatically parse the file and pre-populate the configurations for "Entity ID", Single sign-on service endpoint", "IdP X.509 cert". Important to double-check the values against the IdP metadata file, especially the "IdP X.509 cert" should be exactly the same as the Signature|signing key with reference the sample IdP metadata below.
    • If "Manual configuration", specify the "Entity ID", Single sign-on service endpoint", "IdP X.509 cert"
  7. Define the "Attribute Mapping" of Contour fields to the Uri of the IdP attributes/claims, which should be included in the IdP metadata, with reference the sample IdP metadata below.
    • Username: map to the Uri of the desired "ClaimType", e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • Email: map to the Uri of the email address, e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    • User role: map to the Uri of the (AD) groups, e.g. http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    • Display name (optional): map to the Uri of display name of user, e.g. http://schemas.microsoft.com/identity/claims/displayname
  8. Click on Submit, then Confirm

Now, the status is changed to "Pending activation".

Contour SAML Config

Sample IdP metadata

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  ...
  <KeyInfo>
    <X509Data>
      <X509Certificate> {{IdP Signing certificate}} </X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>

<KeyDescriptor use="signing">
  <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data>
      <X509Certificate> {{IdP Signing certificate}} </X509Certificate>
    </X509Data>
  </KeyInfo>
</KeyDescriptor>

<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
    <auth:DisplayName>Name</auth:DisplayName>
    <auth:Description>The mutable display name of the user.</auth:Description>
</auth:ClaimType>

<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Uri="http://schemas.microsoft.com/identity/claims/displayname">
    <auth:DisplayName>Display Name</auth:DisplayName>
    <auth:Description>Display name of the user.</auth:Description>
</auth:ClaimType>

<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
    <auth:DisplayName>Email</auth:DisplayName>
    <auth:Description>Email address of the user.</auth:Description>
</auth:ClaimType>

<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Uri="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
    <auth:DisplayName>Groups</auth:DisplayName>
    <auth:Description>Groups of the user.</auth:Description>
</auth:ClaimType>

Part 2: Second superadmin user (Check)

  1. Click on Gear on the top right corner
  2. Navigate to "Security settings" under the "Company Settings" on the left panel
  3. Click into "Single sign-on (SSO)"
    • The status is "Pending activation".
  4. Click on Verify SAML, then Verify and Confirm

Now, the status is changed to "Enabled". The Single sign-on (SSO) via SAML2.0 is now effective.