Integrating with SAML

This section details the steps required to provide the Portal with Single-Sign-On (SSO) functionality, by integrating the Portal with a SAML IdP (Identity Provider).

Configuring a SAML IdP

The steps below assume that the Portal is running on https://localhost:8443, and should be adjusted according to the real scheme, host and port.

Only one SAML IdP can be integrated with the Portal at any one time.

Your IdP can only be fully configured after it has been linked to the Portal, but the Portal needs the IdP metadata in order to be fully configured. This is a chicken-egg kind of problem, which can be overcome using the steps below.

1. In your IdP, setup a new SAML SSO configuration, with dummy values for Entity Id and Assertion Consumer Service, e.g.:

   • Entity ID: https://localhost:8443/saml2/dummy
   • Assertion Consumer Service: https://localhost:8443/saml2/sso/dummy

2. In your IdP, export the Provider Metadata. It will export into an XML file.

3. In the Portal, add an Identity Provider as follows:

   1. Go to Settings > System Settings > SAML. You will be taken to this page:

      

   2. Click the “Add Identity Provider” button. You will be taken to this page:

      

   3. Enter a name for the Provider.

   4. Upload the IdP metadata from Step #2.

   5. Click the “Save” button.

   6. The Provider will then be added to the Portal, and displayed as follows::

      

4. In the Portal, export the Portal metadata by clicking on the “Export Metadata” button, which saves an xml file containing the Portal metadata.

5. In your IdP, update the integration configuration as follows:

   1. Option A: Import the Portal metadata.xml file (if possible)

   2. Option B:

      1. Copy the encoded “Provider ID” value from the Portal metadata.xml file. It will look something like this:eyJhbGciOiJIUzUxMi...iDlMVTJinbaNP6bg8QL4c1y-RcGKIXYVv5kycaUcjXATrKmX5QVAu_wA
      2. Replace the "dummy" values in your IdP with that Provider ID value.

Each time an Identity Provider is added in the portal, the value of the encoded Provider ID changes, and needs to be updated in your IdP.

Configuring User Provisioning

There are two User Provisioning options in the Portal: Created and Provisioned. These can be seen in Settings > System Settings > SAML:

Option: Preconfigured

• When this option is select, each user must be created in the Portal before they can login via SSO.

Option: Created

• When this option is selected, new Portal users get automatically created when they first try to log in to the Portal via SSO.

• Specifying Default Portal Role (Mandatory):

  • Each time Portal users login via SSO, their role is set to the “Default Role”, which is specified as follows:

    

• Overriding Default Portal Role with IdP Role (Optional):

  • Optionally, you can setup your configuration so that each user’s role in the IdP gets automatically copied into the Portal. This is done as follows:

    • Step 1: In your IdP, add a custom user attribute named role

    • Step 2: In your IdP, create a “SAML Attribute Statement”, with a name of userRole, and value of user.role.

    • Step 3: In your IdP, adjust individual user profiles to have appropriate values for role e.g. either portal-viewer, portal-admin, or portal-editor.

    • Step 4: In the Portal, configure User Provisioning as follows:

      

• Overriding non-role attributes in the Portal, with the attributes from the IdP (Optional):

  • Each time Portal users login via SSO, the following attribute are set to blank:

    • First Name
    • Last Name
    • Email

  • Optionally, you can setup your configuration so that the corresponding attributes in the IdP get automatically copied into the Portal. This is done as follows:

    • Step 1: In your IdP, create a any of the following Attribute Statements:

      • Name firstName, value user.firstName
      • Name lastName, value user.lastName
      • Name email, value user.email

    • Step 2: In your IdP, adjust individual user profiles to have appropriate values for firstname, lastName, or email.

Securing SAML

If you wish to sign SAML requests or encrypt SAML response assertions, then the Portal Dedicated must be configured with a private key and certificate. To do this, use the following steps:

1. Get a private key and MC cert. For this example, we assume that there is a private key and cert at the following locations:

   • /opt/waratek/portal-private.key
   • /opt/waratek/portal.crt

2. Add the following 2 lines to your application.properties file:

   portal.security.authentication.saml.relyingparty.certificate=file:/opt/waratek/portal.crt
   portal.security.authentication.saml.relyingparty.private-key=file:/opt/waratek/portal-private.key

3. Restart the Portal Dedicated.

Verifying your Configuration

To verify that your SAML integration is now configured correctly, use the following steps:

1. Go to the Portal login page, and verify that the “Use Single Sign On” button appears e.g.

   

2. Click the “Use Single Sign On” button and verify that you get taken to the login page of your IdP.

3. Upon successful login to your IdP you should be redirected back to the Portal and logged in.