SAML Single Sign-On (SSO)

Metric Insights supports Single Sign-On (SSO) authentication, with Users being able to log into Metric Insights via a central Location (Identity Provider - IdP).

  • Metric Insights uses SAML (Security Assertion Markup Language) for authentication,
  • Some common SAML implementations that can be used are by Okta, Microsoft (ADFS), Oracle.

This article describes how to configure Metric Insights to work with a SAML-based IdP using Okta as an example. This process comprises the following steps:

Video Tutorial: Example of Okta Setup for v6

  1. Generate Metadata XML from Metric Insights
    1. Access the Installation Page for SimpleSAML in Metric Insights
    2. Copy Metadata
  2. Obtain Metadata XML from Idp
    1. Create New Application in Okta
    2. Configure Application
    3. Provide General Settings
    4. Provide Attribute Statements
    5. Finish Creating Application
    6. View IdP Metadata
    7. Copy IdP Metadata
  3. Finish SAML Configuration in MI Console
  4. Configure MI Loading Screen Behavior

If you're getting the "<Attribute Name> attribute is missing in the assertion or not mapped properly." error, see Getting "attribute is missing in the assertion or not mapped properly." Error.

Video Tutorial: Example of Okta Setup for v6

NOTE: This video illustrates Okta setup for MI v6.

1. Generate Metadata XML from Metric Insights

1.1. Access the Installation Page for SimpleSAML in Metric Insights

For v6:

  • Append /simplesaml to the Metric Insights URL, i.e. https://<Metric Insights Server>/simplesaml

For v7:

  • Append /simplesaml/module.php/admin/ to your Metric Insights URL, i.e. https://<Metric Insights Server>/simplesaml/module.php/admin/.

NOTE: The SAML Admin password can be found in the web container under /opt/mi/external_config/saml.php, its value is stored in the SAML_ADMIN_PASSWORD variable. Its value must be changed from the default one in order to be able to log in.

  1. Open the Federation tab
  2. Click on the arrow icon

Entity ID we are choosing on this step is using metricinsights-sp authentication source. The same  source is to be set in the SAML config in further steps.

1.2. Copy Metadata

Copy the parameters' values to generate an IdP XML from Okta:

  1. Single sign-on URL: The value of the entityID parameter,
  2. SP Entity ID: The value of the Location parameter of the md: AssertionConsumerService element with Binding parameter's value ending with HTTP-POST.

2. Obtain Metadata XML from Idp

2.1. Create New Application in Okta

Access Okta Admin menu

  1. Access Applications
  2. [Create App Integration]
  3. Select SAML 2.0
  4. [Next]

2.2. Configure Application

  1. Provide a descriptive App name
  2. [Next]

2.3. Provide General Settings

Provide values for the following two parameters:

  1. Single sign-on URL
  2. Audience URI (SP Entity ID)

See Copy Metadata for information on where to find the needed values.

Optionally, the value for Default RelayState can be provided and assigned to the MI instance hostname.

2.4. Provide Attribute Statements

Add the following Attribute Statements:

  1. Name: uid, Value: user.login
  2. Name: email, Value: user.email
  3. [Next]

2.5. Finish Creating Application

  1. Select "I'm an Okta customer adding an internal app"
  2. Select "This is an internal app that we have created"
  3. [Finish]

2.6. View IdP Metadata

  1. Access the Assignments tab to assign the application to the users
  2. Access the Sign On tab
  3. [View SAML setup instructions]

2.7. Copy IdP Metadata

  1. Copy metadata
    • Save it in an XML file for SAML SSO configuration via MI Console or keep it in clipboard for manual configuration

3. Finish SAML Configuration

The recommended way of finishing the SAML configuration for v7 is via MI Console. Alternatively, you can finish SAML configuration manually.

Finish SAML Configuration in MI Console

NOTE: Only users that are System Admins can access the MI Console.

3.1. Enable SAML

Access MI Console > Configuration > SAML

  1. Enable SAML
  2. [Confirm]
  3. Enter Validation Code from the selected authentication app and [Verify]

3.2. Upload IdP Metadata

  1. [Upload Provider Metadata] selecting the XML metadata from IdP.
  2. [Confirm]
  3. Enter Validation Code from the selected authentication app and [Verify]

3.3. Check MI Console

The message in Identity Provider Metadata field is no longer displayed and all mandatory Variables in SAML Configuration section are assigned values. Proceed with configuring MI loading screen behavior.

Finish SAML Configuration Manually

This section describes the process of finishing configuration of SAML manually, which can be used for both v7 and v6.

3.1. Access Web Container

sudo mi-web

3.2. Paste IdP Metadata Into New File And Update SAML Configuration Files

  1. Access external_config directory: cd /opt/mi/external_config
  2. Create new file which will contain metadata from IdP: nano <Metadata file name>
  3. Paste the previously copied IdP XML into the created file
  4. Ctrl + X to close the file
  5. Y to save
  6. View and verify the created file: cat <Metadata file name>
  7. Run the following command to save SAML configuration:
    • For v6: /opt/mi/iv/data/bin/mi-saml-config.php --input-file <full path to saml.xml> --saml-type adfsv3
    • For v7: /opt/mi/web/backend/data/bin/mi-saml-config.php --input-file <Full path to XML metadata> --save --saml-type adfsv3
  8. Two files are updated by the mi-saml-config.php script:
    • saml.php: Stores SAML configuration information,
    • saml20-idp-remote.local.php: Stores the certificate required to check signature.

Once SAML configuration is saved, proceed to check the result in MI console.

3.3. Check saml.php File Permissions and Owner

We recommend to set:

  • The file access level for 644 (-rw-r--r--),
  • the owner of the file for www-data:www-data (www-data user in www-data user group).

You can change the files access using chmod linux command, to change the owner use chown. 

3.4. Enable SAML in Metric Insights

Access Admin > System > System Variables

  1. Enter "SAML" in search field
  2. Set the SAML_ENABLED field to 'Y' using the gear icon on the right
  3. [Commit Changes]
  4. [Proceed]

3.5. Test SAML Configuration

Access the installation page for SimpleSAML in Metric Insights

  1. Access the Test tab
    • For v6, access the Authentication tab
  2. Access metricinsights-sp,
    • If setup correctly, then you will be redirected to your IdP to sign in. Upon successful login you will be redirected back to Metric Insights and the screen will show you the values of SAML fields, so you can check your mapping in saml.php.

4. Configure MI Loading Screen Behavior

Optionally, you can change the loading screen behavior from the default message to spinner.

  1. Enter "SAML_LOADING_SCREEN_OPTION" in search field
  2. Click on the gear icon
  3. Configure SAML_LOADING_SCREEN_OPTION:
    • "message": Display text message
    • "spinner": Display loading indicator
  4. [Save]
  5. [Commit changes]