SAML Single Sign-On (SSO) for v7
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.
What version of MI are you using?
Video Tutorial - Example of OKTA Setup
Generate Metadata XML from Metric Insights
Append /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.
- Copy the Metadata XML (yellow area)
- Provide that to your SAML Identity Provider (IdP)
- Request the provider to return a Metadata key (typically xml) that includes the user ID, first name, last name, and email values for Metric Insights to use
Download and Verify .xml File Received from IdP
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.
Create saml.php File.
The 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.
What version of MI are you using?
- 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/opt/mi/iv/engine/config/saml.php - 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 adfsv3docker ps
kubectl get pods -n <your namespace for MI cluster>
For AWS ECS installation please use AWS UI console
docker service ls- Move
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
mi-console
kubectl exec -it <web master name> -n <your namespace for MI cluster> bash
docker exec -it <web container ID> bash
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
saml.phpfile - Store the
saml.phpin/opt/mi/external_config
cd external_config/
vim saml.php
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.
Enable SAML in Metric Insights
Access Admin > System > System Variables
- Enter "SAML" in search field
- Set the SAML_ENABLED field to 'Y' using edit icon on right
- [Commit Changes]
Configure MI Loading Screen Behavior
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
- Configure
SAML_LOADING_SCREEN_OPTION:- "message": Display text message
- "spinner": Display loading indicator
- [Save]
- [Commit changes]
TEST SAML Configuration
1. Change the Admin Password in the saml.php File
2. Login to the SimpleSAML Installation Page as Admin
- Click [Login as administrator]
3. Test Authentication Sources
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.
4. Check SAML Fields
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.
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:
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.
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.
- Open the Federation tab
- Click on the arrow icon
The 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.
Copy the parameters' values to generate an IdP XML from Okta:
- Single sign-on URL: The value of the entityID parameter,
-
SP Entity ID: The value of the Location parameter of the md: AssertionConsumerService element with Binding parameter's value ending with
HTTP-POST.
Access Okta Admin menu
- Access Applications
- [Create App Integration]
- Select SAML 2.0
- [Next]
- Provide a descriptive App name
- [Next]
Provide values for the following two parameters:
- Single sign-on URL
- 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.
Add the following Attribute Statements:
- Name: uid, Value: user.login
- Name: email, Value: user.email
- [Next]
- Select "I'm an Okta customer adding an internal app"
- Select "This is an internal app that we have created"
- [Finish]
- Access the Assignments tab to assign the application to the users
- Access the Sign On tab
- [View SAML setup instructions]
- Copy metadata
- Save it in an XML file for SAML SSO configuration via MI Console or keep it in clipboard for manual configuration
The recommended way of finishing the SAML configuration for v7 is via MI Console. Alternatively, you can finish SAML configuration manually.
NOTE: Only users that are System Admins can access the MI Console.
Access MI Console > Configuration > SAML
- Enable SAML
- [Confirm]
- Enter Validation Code from the selected authentication app and [Verify]
- [Upload Provider Metadata] selecting the XML metadata from IdP.
- [Confirm]
- Enter Validation Code from the selected authentication app and [Verify]
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.
This section describes the process of finishing configuration of SAML manually, which can be used for both v7 and v6.
sudo mi-web
- Access
external_configdirectory:cd /opt/mi/external_config - Create new file which will contain metadata from IdP:
nano <Metadata file name> - Paste the previously copied IdP XML into the created file
- Ctrl + X to close the file
- Y to save
- View and verify the created file:
cat <Metadata file name> - Run the following command to save SAML configuration:
/opt/mi/web/backend/data/bin/mi-saml-config.php --input-file <Full path to XML metadata> --save --saml-type adfsv3 - Two files are updated by the
mi-saml-config.phpscript:-
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.
We recommend to set:
- The file access level for 644 (
-rw-r--r--), - the owner of the file for
www-data:www-data(www-datauser inwww-datauser group).
You can change the files access using chmod linux command, to change the owner use chown.
Access Admin > System > System Variables
- Enter "SAML" in search field
- Set the SAML_ENABLED field to 'Y' using the gear icon on the right
- [Commit Changes]
- [Proceed]
- Access the Test tab
- For v6, access the Authentication tab
- 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.
- 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
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
- Configure SAML_LOADING_SCREEN_OPTION:
- "message": Display text message
- "spinner": Display loading indicator
- [Save]
- [Commit changes]