SevOne SAML Single Sign-On Setup Guide

SevOne Documentation

All SevOne user documentation is available online from the SevOne Support customer portal.

All right, title, and interest in and to the software and documentation are and shall remain the exclusive property of SevOne and its respective licensors. No part of this document may be reproduced by any means nor modified, decompiled, disassembled, published or distributed, in whole or in part, or translated to any electronic medium or other means without the written consent of SevOne.

In no event shall SevOne, its suppliers, nor its licensors be liable for any damages, whether arising in tort, contract, or any other legal theory even if SevOne has been advised of the possibility of such damages, and SevOne disclaims all warranties, conditions, or other terms, express or implied, statutory or otherwise, on software and documentation furnished hereunder including without limitation the warranties of design, merchantability, or fitness for a particular purpose, and noninfringement.

All SevOne marks identified or used on the SevOne website, as updated by SevOne from time to time, may be, or are, registered with the U.S. Patent and Trademark Office and may be registered or pending registration in other countries. All other trademarks or registered trademarks contained and/or mentioned herein are used for identification purposes only and may be trademarks or registered trademarks of their respective companies.

Introduction

Starting SevOne NMS 5.7.2.15, Single Sign-On (SSO) with dex has been implemented.

You must be on SevOne NMS 5.7.2.15 or higher. Please install or upgrade to the appropriate SevOne NMS version which supports the Single Sign-On feature.

On a HSA, Single Sign-On must not be configured. Only configure Single Sign-On on the Cluster Master. If a failover on a Cluster Master happens, only then configure Single Sign-On on the HSA. When the Cluster Master automatically fails over to the HSA, you are required to update Identity Provider configuration to now point to the HSA's IP Address / hostname.

In case of a failover, you need to modify your Identity Provider configuration (for example, Siteminder), to point to the new HSA instead of the failed Cluster Master.

Single Sign-On logins do not create new users. Due to this, it requires the users to be added to NMS manually.

Risks of using IdP-Initiated Single Sign-On Flow

There are security implications of IdP (Identity Provider) initiated SAML before implementing it with SevOne NMS.

dP-Initiated flows carry a security risk and are therefore NOT recommended. Make sure you understand the risks before enabling IdP-Initiated Single Sign-On.

In an IdP-initiated flow neither Auth0 (which receives the unsolicited response from the Identity Provider) nor the application (that receives the unsolicited response generated by Auth0) can verify that the user actually started the flow. Because of this, enabling this flow opens the possibility of an Login CSRF attack (please refer to https://support.detectify.com/support/solutions/articles/48001048951-login-csrf for details), where an attacker can trick a legitimate user into unknowingly logging into the application with the identity of the attacker.

SevOne recommends use of SP (Service Provider)-Initiated flows whenever possible. For details, please refer to https://auth0.com/docs/protocols/saml/idp-initiated-sso#risks-of-using-an-idp-initiated-sso-flow.

Configure Security Assertion Markup Language (SAML)

Prerequisite

IP Address of the Cluster Master required.

Login to Okta Account

Two Factor Authentication (2FA) with Okta requires configuration of Multifactor Authentication (MFA) enrollment policies. Please refer to https://help.okta.com/en/prod/Content/Topics/Security/healthinsight/required-factors.htm for details.

Sign-in to your Okta account.
Click on Admin button in the upper-right corner.
Click on Applications drop-down and select Applications.
Click on Add Application button.
Click on Create New App button in the left-panel.

Ensure that in the upper-left corner, Classic UI option is chosen.
Choose SAML 2.0 as a Sign on method.
Click on Create button to initiate Create SAML Integration.
Enter App name.
You may choose to add an App logo. This field is optional.
Click on Next button to Create SAML application.

Create SAML application

Create a new SAML application in your SAML provider site.
Add a Single Sign-On URL.

Example

https://<Cluster Master>/sso/callback

If the SAML application requires Recipient and Destination URLs, use the above URL for both.
Add an Audience URI (also known as, SP Entity ID).

Example

https://<Cluster Master>/sso/callback
For IdP initiated login support, Default RelayState must be set to the NMS client ID, sevonenms.

This is a change from the initial release, SevOne NMS 5.7.2.15, where the Default RelayState had to be set to the User Interface's auth callback. For example, https://<Cluster Master>/callback.php. Now, when an upgrade from SevOne NMS 5.7.2.15 is done, you will need to update the Default RelayState field to be set to the NMS client ID.
Add an attribute statement for name that has the value that maps to the user login in SevOne NMS.
Your configuration must look as follows.
Provide permissions to the users to use the app.

Gather Information Required for NMS configuration

You will need the following from the SAML provider in the NMS configuration.

The Identity Provider Single Sign-On URL.
The Identity Provider Issuer.
The X.509 certificate.

Configure Single Sign-On in NMS

Please make sure that once the appliance or VM is configured with the Single Sign-On, its IP Address must not be changed. Otherwise, Single Sign-On will fail.

Edit DEX Configuration

SSH into your Cluster Master.
Place the X.509 certificate somewhere on the box, such as /usr/share/pki/sso/saml.pem.
Run the script to update the config template.

$ bash /usr/local/scripts/dex_setup_template.sh
Using the text editor of your choice, edit /etc/dex/config.yaml file.
Uncomment SAML connector configuration. i.e. Remove the first # from each of the lines.

The first 3 lines that start with ## should remain as comments.
1. Set name to a reasonable value. This value will be displayed to users when presented with login options.
2. If you like, you may change the id. This is for Internal Use Only, but must be unique if you are configuring multiple connectors.
3. Do not change the type.
4. Set config.ssoURL to the Identity Provider Single Sign-On URL.
5. Set config.ssoIssuer to the Identity Provider Issuer.
6. Set config.ca value to the file path where your X.509 certificate is located.
7. Depending on your Identity Server Configuration, you may need to change the values of config.usernameAttr and config.emailAttr to match those of your server's attribute statements.
8. If your Identity Server requires a GET authentication request, instead of the default POST, place the following line under the SAML connector config since it configures how dex must handle the SAML response.
  
  authnRequestBindingType: "HTTP-Redirect"
If you used the domain name for <Cluster Master> in the previous section, replace all instances of the Cluster Master IP with the Domain Name.
If you have signed certificates set up on your SevOne NMS cluster, please update the following to validate these certificates. Under sevone > connector > config,
1. Add caCertFile and set it with a path to your CA.
2. Set noVerify to false to validate the certificates.
Please do not change any configuration in the storage, web, and frontend sections without first consulting with SevOne Support.
Your dex configuration file, /etc/dex/config.yaml must look like the following.

Example with detailed comments

# Note: Dex should only be running on the cluster master

# the URL here can be the IP or the hostname of the cluster master

# Cluster master IP that will issue the valid auth tokens. This has to be reachable by DI, the NMS and the IdP

# If behind a proxy, this should be the proxy address to the cluster master. The same proxy address for the issuer

# should be configured for the IdP, DI and the NMS. Everyone needs to agree on the issuer and it has to be the same

# in all of the login cases in order for SSO to work.

issuer: https://10.168.128.11/sso

# Backend storage for authenticated clients

storage:

type: mysql

config:

host: 127.0.0.1:3307

database: dex_db

user: dex

# This is the MySQL password used to allow access to the dex database

password: jrFoHsG9xe2FjliSBgbNBgoblWCpkB54IgdvcogOK2BybtriJoYHG8b5NGoRrnhsFdTOmFaWUgd1eDROONDakKB4BqV70FWD8IASx6CktYgNizzkdYKd6aaIgyNqkwXc

ssl:

mode: "false"

logger:

level: "debug"

format: "text"

# The port where dex will run

web:

http: 127.0.0.1:5556

# The login page for dex authentication

frontend:

dir: /opt/dex/web

theme: sevone

issuer: SevOne

# The connector for doing local SevOne authentication

connectors:

- id: sevone

name: SevOne auth

type: sevone

config:

restUrl: "https://test-nms2.devops.sevone.com/api"

resetPassUrl: https://test-nms2.devops.sevone.com/doms/login/newPassword.html

caCertFile: "/etc/nginx/ssl/nginx.crt"

noVerify: true

# To get a SAML connector working, replace:

# - The ssoURL and ssoIssuer with URLs from the SAML provider

# - redirectURI/entityIssuer addresses need to point to the cluster master hostname or IP

- id: okta

name: okta

type: saml

config:

# This is provided by the SAML provider (Okta, Siteminder etc). It has to be reachable by the user's browser.

ssoURL: "https://dev-835393.okta.com/app/sevonedev835393_testnms_1/exk13u9fndI6T6GmJ357/sso/saml"

# This is provided by the SAML provider (Okta, Siteminder etc). This has to be reachable by the user's browser.

ssoIssuer: "http://www.okta.com/exk13u9fndI6T6GmJ357"

# This URL handles the login authentication. It should be the NMS cluster master.

# The user will be redirected here from the Identity Provider so this needs to be reachable.

redirectURI: "https://10.168.128.11/sso/callback"

# The certificate authority that was used to sign the SSL certificates for the connection

# This is provided by the SAML provider

ca: /usr/share/pki/okta/okta-cert.pem

# The name of the field that contains the username attribute

usernameAttr: name

# The name of the field that contains the email attribute

emailAttr: email

oauth2:

# skips asking the user to grant permission for login

skipApprovalScreen: true

# the OpenID Connect flow types to enable. DO NOT EDIT

responseTypes: ["code","token","id_token"]

# This defines which applications can authenticate using dex. Below is an example NMS configuration,

# but other applications (e.g. DI) can be configured here

staticClients:

# The client_id. Use this id as the 'Default Relay State' when configuring a SAML Service Provider.

- id: sevonenms

# The redirect URIs matter for SP initiated logins (client (NMS) initiated logins).

# It should contain all the peers in the cluster with both their hostnames and IPs that are

# allowed to do SP initiated login. Also with HTTP and HTTPS access.

# The user can be redirected to one of these after a successful login.

redirectURIs:

- 'http://test-nms2.devops.sevone.com/callback.php'

- 'https://test-nms2.devops.sevone.com/callback.php'

- 'http://10.168.128.11/callback.php'

- 'https://10.168.128.11/callback.php'

name: 'SevOne NMS'

# The client_secret for the NMS client. The NMS will need this to initiate login.

secret: EAvgtOGIsxjcFdl2aaKoEOmlOCY3G7LVNdiDnf3ZiIqSdcw5xKYlaodmaUIHqFg9bVHIzYmG50wV9oAhYm6WrBO7npuf713CUH9Tq5lgEjfHtTH8Zlpzkt1C9ilMBIDI

# samlInitiated is required to enable SAML's IdP initiated flow. If not using SAML, you may omit this section.

samlInitiated:

# This is where users will finally be redirected after a SAML IdP initiated login.

# It can be any peer in the cluster.

redirectURI: https://10.168.128.11/callback.php

# Let dex keep a list of passwords which can be used to login to dex.

# We don't allow that so lets keep it disabled.

enablePasswordDB: false

Restart Single Sign-On Service

Restart Single Sign-On service, dex, on the Cluster Master for the configuration changes to take effect.

$ ssh <Cluster Master>
$ supervisorctl restart dex

Enable Single Sign-On

Log into the SevOne GUI as an administrator.
From the navigation bar, click on the Administration menu and select Cluster Manager.
Click on Cluster Settings tab.
Choose Login subtab.
Select the Enable Single Sign-On check box to enable Single Sign-On.
Click Save to save the Login settings.

SevOne NMS is using SAML. However, SevOne Data Insight is using OpenID-Connect.

dex wraps SAML in OpenID-Connect tokens.

Redirect on Logout

If you only have IdP initiated login enabled, NMS has the ability to redirect externally on logout or session timeout.

Execute the following command to add the destination URL to the Cluster Master's database.

$ mysqlconfig -h $cluster_master_ip -e "INSERT INTO net.settings(setting, value) VALUES('logout_url', '$destination_url') ON DUPLICATE KEY UPDATE value = VALUES(value)"

HSA Configuration

If the Cluster Master fails over to its HSA, Single Sign-On will stop working. Please make sure that dex is not running on an HSA prior to a failover - it should be kept in stopped state. If you have dex running on an HSA prior to a failover, ability to login will be impaired on the entire NMS cluster.

Once the Cluster Master fails over to the HSA, the authentication will fallback to local SevOne authentication. At this point, dex can be configured for Single Sign-On. And, dex can now be started and Single Sign-On can be enabled from the User Interface.

When the Cluster Master fails over to the HSA, the Identity Provider configuration must be updated to point to the HSA's IP Address / hostname.

Execute the following steps to enable Single Sign-On on the HSA.

Fail over the Cluster Master to the HSA.
Make sure the HSA has a valid dex config. This includes a valid dex secret and dex MySQL password. To ensure the conditions are met, run the following setup script each time a failover/takeover happens.

$ bash /usr/local/scripts/dex_setup_template.sh

This will regenerate a bare-minimum working dex configuration with a valid dex secret and dex MySQL password. Update the existing /etc/dex/config.yaml file with the newly generated dex secret and dex MySQL password.
Port all configuration options from the Cluster Master's /etc/dex/config.yaml file on to the HSA.

Even if the setup script is used to generate a valid dex configuration, you are still required to port the configuration from the Cluster Master.
Restart dex on the HSA.
Enable Single Sign-On from the graphical user interface. Execute the steps below.
1. From the navigation bar, click the Administration menu and select Cluster Manager.
2. Click on Cluster Settings tab.
3. Click on Login subtab.
4. Unselect the Enable Single Sign-On check box.
5. Click Save to save the settings.
6. Select the Enable Single Sign-On check box.
7. Click Save to save the settings.

The same steps must be taken when a failback is performed from the HSA to the Cluster Master.

SevOne NMS is using SAML. However, SevOne Data Insight is using OpenID-Connect.

dex wraps SAML in OpenID-Connect tokens.

Upgrade Process

If you have SevOne NMS 5.7.2.15 with Single Sign-On enabled and you would like to upgrade to a higher release, note that dex configuration has changed. You will be unable to use Single Sign-On as-is and are required to re-enable Single Sign-On. Please follow the steps below.

SSH into the cluster master.
Rerun the setup script.

$ bash /usr/local/scripts/dex_setup_template.sh
A new config will be written to /etc/dex/config.yaml. And, it will save the old config to /etc/dex/config.yaml.backup.
Copy and paste the custom config from connectors section in /etc/dex/config.yaml.backup to the connectors section in /etc/dex/config.yaml.
IMPORTANT
- yaml files are sensitive about indentations. Please be sure your indentation is correct.
- If you had any other custom config outside of connectors section in the old config file, you will need to transfer that config over to the new config file as well.
Restart Single Sign-On service, dex, on the Cluster Master for the configuration changes to take effect.

$ ssh <Cluster Master>

$ supervisorctl restart dex

The expected Default Relay State has changed from SevOne NMS 5.7.2.15 release. You will need to change this value in your SAML provider to sevonenms. Please go to Default Relay State for more details.

Troubleshooting

Is DEX Running?

To identify the status of dex on the Cluster Master, you must execute the following command.

dex must be running on Cluster Master and /etc/dex/config.yaml file must be present.

SSH to Cluster Master.

$ ssh <Cluster Master>
The following provides the options available to check the dex status.

SevOne-dexctl status 'help'

$ SevOne-dexctl status --help

USAGE:

SevOne CLI script to check (and fix) dex status

/usr/local/scripts/SevOne-dexctl status [OPTIONS]

OPTIONS:

--autofix -a | If the status is wrong, try to fix it

--help -h | Print usage and exit
Execute this command to check the dex status.
$ SevOne-dexctl status

SevOne-dexctl status will return one of the following messages.

Example: SevOne-dexctl status > returns SUCCESS

dex is expected to be RUNNING and it is RUNNING

--- Expecting status RUNNING

--- Supervisor status:

--- dex RUNNING pid 16845, uptime 2 days, 14:29:11

✓✓✓ Status matches, all good

This indicates that you are on the Cluster Master, /etc/dex/config.yaml file is present, and dex is RUNNING.

Example: SevOne-dexctl status > returns FAILURE

dex is expected to be RUNNING but it is STOPPED

--- Expecting status RUNNING

--- Supervisor status:

--- dex STOPPED Oct 02 09:45 PM

!!! Status does not match, please check /var/log/dex.log for details

In this scenario, make sure that, you are on the Cluster Master and /etc/dex/config.yaml file is present prior to restarting dex or add --autofix / -a option to SevOne-dexctl status command. This can be done in the following ways.

$ supervisorctl restart dex

OR

$ SevOne-dexctl status --autofix
If you are not on Cluster Master but dex is RUNNING, SevOne-dexctl status will inform you that,
- dex should not be running
- dex is running
- you should stop dex
SevOne-dexctl status script does not consider if Single Sign-On is enabled.

Single Sign-On can be enabled from the SevOne NMS Graphical User Interface. Enter the URL of your Cluster Master, from the navigation bar, click on Administration menu, select Cluster Manager, select tab Cluster Settings, subtab Login. You will see field Enable Single Sign-On under Single Sign-On section.

FAQs

What is Default RelayState?

In SAML spec, the RelayState is an optional parameter. We use the Default RelayState to signify specific login journey inside dex and it is important to be matched by both the IdP configuration and the dex config.yaml file. Currently it is set to NMS Client ID, sevonenms.

For additional details, please refer to https://stackoverflow.com/a/34351756
What isNMS Client ID? Why is it set to sevonenms?

NMS Client ID is set to sevonenms but, it can be changed.

The NMS Client ID is passed in the Default RelayState field from the IdP in order to trigger the authentication against the correct client setup in dex. This is needed as dex can support multiple different clients and we use it to distinguish an NMS specific authentication journey.
What is the difference between Identity Provider Single Sign-On URL & Identity Provider Issuer?
These are provided from the IdP configuration and must be part of a valid IdP configuration. The customer must configure dex accordingly.
What is x.509 Certificate?
This is the IdP provided certificate. Each IdP must have a certificate that needs to be copied on SevOne NMS box and dex must be configured to use it for validation purposes.
What does ssoURL & ssoIssuer mean in /etc/dex/config.yaml file?
The ssoURL and the ssoIssuer must be provided by the IdP. These are customer specific and must be configured by the customer. If the customer has a working IdP configuration then, they should be able to specify the ssoURL and ssoIssuer from the IdP configuration.
What does redirectURI & entityIssuer mean in /etc/dex/config.yaml file?

The redirectURI and entityIssuer must point to the NMS Cluster Master's IP address. redirectURI is a URL that handles the login authentication. The user will be redirected here from the Identity Provider so, the URL must be reachable.

For example, https://10.168.128.11/sso/callback, where 10.168.128.11 is the <Cluster Master>.
How can I determine if I have only IdP initiated login enabled?

IdP relates to a specific SAML workflow. Generally, this is what most customers will use and it depends on their requirements. Service Provider initiated login is also available through dex but it has to be configured accordingly.
Does SevOne support SHA-256 or higher certificate algorithm?
Yes.

References

https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso

Table of Contents (Start)

SevOne SAML Single Sign-On Setup Guide

Introduction

Configure Security Assertion Markup Language (SAML)

Prerequisite

Login to Okta Account

Create SAML application

Gather Information Required for NMS configuration

Configure Single Sign-On in NMS

Edit DEX Configuration

Restart Single Sign-On Service

Enable Single Sign-On

Redirect on Logout

HSA Configuration

Upgrade Process

Troubleshooting

Is DEX Running?

FAQs

References