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.

SAML Group Mapping

In an IdP, groups help simplify user management. If the user is configured in certain groups in the Idp, this can be exposed in SAML and used to determine the user's team/role combinations in Portal. This mapping should be configured ONCE (in the Portal) and not per user. Users team/role memberships are then automatically mapped on first and future logins.

To Create teams in the Portal, Please refer to the teams page teams.md in the User guide.

In most IdPs, groups are exposed through a SAML attribute (for example: groups, memberOf, or member). There may be a default SAML groups attribute in your Idp or you may have to configure one - either way we need to know the attribute name (see below)

info

Before configuring SAML Group Mapping in the Portal UI:

1. Create groups in your IdP and assign users to them.
2. In your IdP SAML application, configure a groups attribute:
   • Attribute name: groups (or your chosen group attribute name)
   • Name format: Unspecified
   • Filter: Matches regex with value .* (if required by your IdP policy)

• In the SAML tab, select Created under User Provisioning. The Groups Attribute field appears in the Portal UI.

• In Groups Attribute, enter the IdP group attribute name configured in your SAML application.
  • Example: if your IdP sends groups in groups, enter groups.
  • Click Save Changes and confirm.
  • After saving, the Add Mapping button is enabled in the team-role mappings table.

Add Team Role Mapping

In Portal, we are mapping IdP groups to teams in the Portal using team role mappings. For example, if you want to map the developers group in your IdP to the developers team in Portal, then you would do the following:

• Click Add Mapping button. You will get an Add Mapping dialog with 3 fields: Group Name, Team and Role.
• In Group Name field, enter the IdP group name exactly as sent in the SAML assertion (exact, case-sensitive match), e.g. developers.
• Click the Role drop-down.
• Select a role. Currently, only Editor and Viewer are supported.

• Click the Team drop-down.
• Select the team in the Portal to map to, for example Engineering Team.

• Click Create.
• Once the mapping is created, you will see the new team role mapping in the table as follows:

After the mapping is created, when the user who is a member of developers group in IdP logs in to Portal, they will automatically become a member of Engineering Team with Editor role in Portal.

Edit Team Role Mapping

The Edit Team Role Mapping action lets users update the role and team in an existing mapping. The group name cannot be changed after creation. To edit a mapping:

• Click the Edit Pencil Icon. You will get an Edit Mapping dialog as follows:

• In the Edit Mapping dialog, update Role and Team.
• The group name is read-only. To change it, delete the mapping and create a new one.
• Click Update.

Delete Team Role Mapping

The Delete Team Role Mapping action removes the mapping from the Portal. This change will take effect next time mapped users login through the IdP.

• Click the Delete Icon. You will get a confirmation dialog as follows:

• Click Confirm to permanently delete the mapping.
• Click Cancel to keep the mapping unchanged.

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.