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. This process comprises the following steps:
1.2 Copy Metadata
3.2.3 Get into Web Container
126.96.36.199 For Simple Installation
188.8.131.52 For K8s (Kubernetes)
3.2.4 Parse the .xml File
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.
/simplesaml to the Metric Insights URL, i.e.
https://<Metric Insights Server>/simplesaml
- Open the Federation tab
- Click on [Show metadata] link
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.
Verify that your IdP defined firstName, lastName, Email and UID attributes in the Metadata key file (the .xml file ).
If not provided in the
saml.xml file, these attributes values are to be populated in
saml.php file manually:
define('SAML_UID_FIELD', '<name as defined in IdP>'); define('SAML_EMAIL_FIELD', '<name as defined in IdP>'); define('SAML_FNAME_FIELD', '<name as defined in IdP>'); define('SAML_LNAME_FIELD', '<name as defined in IdP>');
You can find more information on how to configure Okta (one of IdP providers) for MI SAML SSL setup in our Knowledge Base article.
saml.php file from 5.x can be used on v6.x if the hostname is identical for both instances (the IdP looks for incoming requests from the 'approved' hostname/URL only). You can just place this file in the
/opt/mi/external_config directory inside the web container.
If the hostname has changed for 6.x instance, a new
saml.php must be created using metadata for the 6.x instance and a new profile is to be set in the IdP to represent v6.x.
- Copy the .xml file provided by IdP to the MI app server
- All the required metadata is going to be given in the response. Copy it and paste into the
saml.phpfile located at
- Parse the .xml file by running the following command:
/opt/mi/iv/data/bin/mi-saml-config.php --input-file <path to saml.xml> --saml-type adfsv3
kubectl get pods -n <your namespace for MI cluster>
For AWS ECS installation please use AWS UI console
saml.xmlfile from host to the web container identified above by replacing
<web container ID>with your web container ID:
docker mv /opt/mi/saml.xml <web container ID>:/opt/mi/saml.xml
From inside web container run the following command:
/opt/mi/iv/data/bin/mi-saml-config.php --input-file <full path to saml.xml> --saml-type adfsv3
- The metadata given in the response representing DEFINE section is to be copy-pasted into the
- Store the
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
Access Admin > System > System Variables
- Enter "SAML" in search field
- Set the SAML_ENABLED field to 'Y' using edit icon on right
- [Commit Changes]
Optionally, you can change the loading screen behavior from the default message to spinner.
- Enter "SAML_LOADING_SCREEN_OPTION" in search field
- Click on the gear icon
- "message": Display text message
- "spinner": Display loading indicator
- [Commit changes]
Access the Authentication tab
- Click [Test configured authentication sources]
- Remembering that you used metricinsights-sp in our very first step, (first step), click on metricinsights-sp to test
If setup correctly, then you will be redirected to your IdP to sign in.