SevOne SAML Single Sign-On Setup Guide
26 April 2023
IBM SevOne NPM Version 6.5.0
Document Version 6.5.0.0
SevOne SAML Single Sign-On Setup Guide
Table of Contents
1 Introduction 2
2 Configure SAML Using Okta Setup 3
2.1 Prerequisite3
2.2 Login to Okta Account3
2.3 Create / Configure SAML application 4
2.4 Gather Information required for NMS configuration5
2.5 Configure Single Sign-On in NMS6
3 Configure SAML Using Azure Active Directory Single Sign-On Setup 10
3.1 Prerequisite 10
3.2 Create / Configure Azure Active Directory Single Sign-On application 10
3.3 Configure Single Sign-On in NMS 11
4 Restart Single Sign-On Service 13
5 Enable Single Sign-On 14
6 Redirect On Logout15
7 HSA Configuration 16
8 Upgrade Process 17
9 Login CSRF18
10 Troubleshooting19
10.1 Is DEX Running? 19
11 FAQs21
12 References 22
SevOne SAML Single Sign-On Setup Guide
1
SevOne Documentation
All documentation is available from theIBM SevOne Support customer portal.
© Copyright International Business Machines Corporation 2023.
All right, title, and interest in and to the software and documentation are and shall remain the exclusive property of IBM 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 IBM.
IN NO EVENT SHALL IBM, ITS SUPPLIERS, NOR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, WHETHER ARISING IN TORT,
CONTRACT OR ANY OTHER LEGAL THEORY EVEN IF IBM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IBM
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.
IBM, the IBM logo, and SevOne are trademarks or registered trademarks of International Business Machines Corporation, in the
United States and/or other countries. Other product and service names might be trademarks of IBM or other companies. A current
list of IBM trademarks is available onibm.com/trademark.
SevOne SAML Single Sign-On Setup Guide
2
1 Introduction
Single Sign-On (SSO) is available with dex. This document provides details on how to configure SAML (Security Assertion Markup
Language) using Okta and Service Provided Initiated Azure Active Directory Single Sign-On (sP-initiated Azure AD SSO) setups.
On a HSA, Single Sign-On must not be configured. Only configure Single Sign-On on the Cluster Leader. If a failover on a
Cluster Leader happens, only then configure Single Sign-On on the HSA. When the Cluster Leader 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 Leader.
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.
Currently, the version of dex SevOne uses, only supports SP-initiated Single Sign-On.
IdP-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, where an attacker can trick a legitimate
user into unknowingly logging into the application with the identity of the attacker. Please refer to Login CSRF section
below for details.
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.
When a URL is used for Single Sign-On configuration, between the identity provider and NMS dex config, you must be
consistent with using either the IP address or a DNS name. Please do not mix and match IP addresses and their
corresponding DNS names.
The details in this document do not apply to single-peer clusters.
•
•
•
Terminology usage...
In this guide if there is,
[any reference to
master
]OR
[[if a CLI commandcontains
master
] AND/OR
[its output contains
master
]],
it means
leader
.
And, if there is any reference to
slave
, it means
follower
.
SevOne SAML Single Sign-On Setup Guide
3
•
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
2 Configure SAML using Okta Setup
2.1 Prerequisite
IP Address of SevOne NMS Cluster Leader required.
2.2 Login to Okta Account
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 Appbutton in the left-panel.
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 / Configure SAML application.
IMPORTANT: Upgrade / Install SevOne NMS
To use Single Sign-On feature, you must be on SevOne NMS 5.7.2.15 or higher version.
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.
Ensure that in the upper-left corner, Classic UI option is chosen.
SevOne SAML Single Sign-On Setup Guide
4
1.
2.
3.
4.
5.
6.
2.3 Create / Configure SAML application
Create a new SAML application in your SAML provider site.
Add a Single Sign-On URL.
Add an Audience URI (also known as, SP Entity ID).
For IdP initiated login support, Default RelayState must be set to the NMS client ID, sevonenms.
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.
Example
https://<Cluster Leader IP address>/sso/callback
If the SAML application requires Recipient and Destination URLs, use the above URL for both.
Example
https://<Cluster Leader IP address>/sso/callback
SevOne SAML Single Sign-On Setup Guide
5
7.
1.
2.
3.
Example
In this example, 10.168.129.48 is the Cluster Leader IP address.
Provide permissions to the users to use the app.
2.4 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.
SevOne SAML Single Sign-On Setup Guide
6
1.
2.
3.
4.
a.
b.
c.
d.
e.
f.
g.
h.
i.
2.5 Configure Single Sign-On in NMS
Copy x.509 certificate, /usr/share/pki/sso/saml.pem, to SevOne NMS' cluster leader.
SSH into your Cluster Leader.
$ ssh root@<Cluster Leader IP address>
Run /usr/local/scripts/dex_setup_template.sh 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.
$ vi /etc/dex/config.yaml
Uncomment the SAML section (starting with line
- id: saml
) by removing the # from each line.
id - is an identifier unique todex. If you do not have any other connections withidof SAML, you may leave it as is.
This is for Internal Use Only, but must be unique if you are configuring multiple connectors.
name - setto a reasonable value. This value will be displayed to users when presented with login options.
type - leave as saml.
Set config.ssoURL to the Identity Provider Single Sign-On URL.
Set config.ssoIssuer to theIdentity Provider Issuer.
Set config.cavalue to the file path where your x.509 certificate is located. For example, /usr/share/pki/sso/saml.pem.
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.
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.
Please make sure that once the appliance or Virtual Machine is configured with the Single Sign-On, its IP Address cannot
be changed. Otherwise, Single Sign-On will fail.
If directory/usr/share/pki/ssodoes not exist, create it.
Running dex_setup_template.sh generates a new MySQL
dex password
as well as a new
OAuth secret
. If this script
must be run again for any reason, please use the new password and secret for any editing to be done on the
generated /etc/dex/config.yaml file. Failure to do so, results in the following authentication error forallactive dex
connectors.
Error
Authentication Exception: Invalid client credentials.
The first 3 lines that start with ## should remain as comments.
SevOne SAML Single Sign-On Setup Guide
7
5.
6.
a.
b.
7.
8.
authnRequestBindingType: "HTTP-Redirect"
If you used the domain name for <Cluster Leader IP address> in the previous section, replace all instances of the Cluster
Leader IP address 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,
AddcaCertFileand set it with a path to your CA.
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 / leader1
# the URL here can be the IP or the hostname of the cluster master / leader2
3
# Cluster master / leader IP that will issue the valid auth tokens. This has to be
reachable by DI, the NMS and the IdP
4
# If behind a proxy, this should be the proxy address to the cluster master /
leader. The same proxy address for the issuer
5
# should be configured for the IdP, DI and the NMS. Everyone needs to agree on the
issuer and it has to be the same
6
# in all of the login cases in order for SSO to work.7
issuer: https://10.168.129.48/sso8
9
# Backend storage for authenticated clients10
storage:11
type: mysql12
config:13
host: 127.0.0.1:330714
database: dex_db15
user: dex16
# This is the MySQL password used to allow access to the dex database17
password:
jrFoHsG9xe2FjliSBgbNBgoblWCpkB54IgdvcogOK2BybtriJoYHG8b5NGoRrnhsFdTOmFaWUgd1eDROOND
akKB4BqV70FWD8IASx6CktYgNizzkdYKd6aaIgyNqkwXc
18
ssl:19
mode: "false"20
logger:21
level: "debug"22
format: "text"23
24
25
# The port where dex will run26
web:27
http: 127.0.0.1:555628
29
30
# The login page for dex authentication31
frontend:32
dir: /opt/dex/web33
theme: sevone34
issuer: SevOne35
36
37
# The connector for doing local SevOne authentication38
connectors:39
SevOne SAML Single Sign-On Setup Guide
8
- id: sevone40
name: SevOne auth41
type: sevone42
config:43
restUrl: "https://test-nms2.devops.sevone.com/api"44
resetPassUrl: https://test-nms2.devops.sevone.com/doms/login/newPassword.html45
caCertFile: "/etc/nginx/ssl/nginx.crt"46
noVerify: true47
48
# To get a SAML connector working, replace:49
# - The ssoURL and ssoIssuer with URLs from the SAML provider50
# - redirectURI/entityIssuer addresses need to point to the cluster master /
leader hostname or IP
51
- id: okta52
name: okta53
type: saml54
config:55
# This is provided by the SAML provider (Okta, Siteminder etc). It has to be
reachable by the user's browser.
56
ssoURL: "https://dev-835393.okta.com/app/sevonedev835393_testnms_1/
exk13u9fndI6T6GmJ357/sso/saml"
57
58
59
# This is provided by the SAML provider (Okta, Siteminder etc). This has to be
reachable by the user's browser.
60
ssoIssuer: "http://www.okta.com/exk13u9fndI6T6GmJ357"61
62
63
# This URL handles the login authentication. It should be the NMS cluster
master / leader.
64
# The user will be redirected here from the Identity Provider so this needs to
be reachable.
65
redirectURI: "https://10.168.129.48/sso/callback"66
67
68
# The certificate authority that was used to sign the SSL certificates for the
connection
69
# This is provided by the SAML provider70
ca: /usr/share/pki/okta/okta-cert.pem71
72
73
# The name of the field that contains the username attribute74
usernameAttr: name75
76
77
# The name of the field that contains the email attribute78
emailAttr: email79
80
oauth2:81
# skips asking the user to grant permission for login82
skipApprovalScreen: true83
# the OpenID Connect flow types to enable. DO NOT EDIT84
responseTypes: ["code","token","id_token"]85
86
# This defines which applications can authenticate using dex. Below is an example
NMS configuration,
87
# but other applications (e.g. DI) can be configured here88
staticClients:89
# The client_id. Use this id as the 'Default Relay State' when configuring a SAML
Service Provider.
90
- id: sevonenms91
# The redirect URIs matter for SP initiated logins (client (NMS) initiated
logins).
92
# It should contain all the peers in the cluster with both their hostnames and
IPs that are
93
# allowed to do SP initiated login. Also with HTTP and HTTPS access.94
# The user can be redirected to one of these after a successful login.95
redirectURIs:96
- 'http://test-nms2.devops.sevone.com/callback.php'97
SevOne SAML Single Sign-On Setup Guide
9
9.
10.
Restart SSO service. Please refer to section Restart Single Sign-On Service.
Enable SSO. Please refer to section Enable Single Sign-On.
- 'https://test-nms2.devops.sevone.com/callback.php'98
- 'http://10.168.129.48/callback.php'99
- 'https://10.168.129.48/callback.php'100
name: 'SevOne NMS'101
# The client_secret for the NMS client. The NMS will need this to initiate login.102
secret:
EAvgtOGIsxjcFdl2aaKoEOmlOCY3G7LVNdiDnf3ZiIqSdcw5xKYlaodmaUIHqFg9bVHIzYmG50wV9oAhYm6
WrBO7npuf713CUH9Tq5lgEjfHtTH8Zlpzkt1C9ilMBIDI
103
# samlInitiated is required to enable SAML's IdP initiated flow. If not using
SAML, you may omit this section.
104
samlInitiated:105
# This is where users will finally be redirected after a SAML IdP initiated
login.
106
# It can be any peer in the cluster.107
redirectURI: https://10.168.129.48/callback.php108
109
# The client_id. For Data Insight we need a separate static client as we configure
the redirectURIs differently.
110
# This id will be used in oidc configuration on Data Insight as 'clientId'111
- id: sevonedi112
# These redirect uris will be datainsight servers which are configured to use
this nms dex instance for auth.
113
# All valid hostnames should be here.114
redirectURIs:115
- 'https://10.168.10.11/callback'116
- 'https://datainsight.example.com/callback'117
name: 'SevOne DI'118
# The client_secret for the Data Insight client. This should be the same as the
one configured for the sevonenms static client
119
# This will be used in the Data Insight oidc configuration as 'clientSecret'120
secret:
EAvgtOGIsxjcFdl2aaKoEOmlOCY3G7LVNdiDnf3ZiIqSdcw5xKYlaodmaUIHqFg9bVHIzYmG50wV9oAhYm6
WrBO7npuf713CUH9Tq5lgEjfHtTH8Zlpzkt1C9ilMBIDI
121
# samlInitiated is required to enable SAML's IdP initiated flow. If not using
SAML, you may omit this section.
122
samlInitiated:123
# This is where users will finally be redirected after a SAML IdP initiated
login.
124
# This should be the datainsight url they came from125
redirectURI: https://10.168.10.11/callback126
127
# Let dex keep a list of passwords which can be used to login to dex.128
# We don't allow that so lets keep it disabled.129
enablePasswordDB: false130
SevOne NMS is using SAML. However, SevOne Data Insight is using OpenID-Connect. Please refer to
SevOne Data Insight
Administration Guide
> section Configuration > subsection OpenID Connect for details.
dex wraps SAML in OpenID-Connect tokens.
SevOne SAML Single Sign-On Setup Guide
10
•
•
•
1.
2.
3.
4.
a.
b.
5.
6.
7.
8.
9.
10.
a.
b.
11.
3 Configure SAML using Azure Active Directory Single Sign-On Setup
3.1 Prerequisite
Azure Active Directory (AD) subscription. If you do not have a subscription, you may obtain a free account.
Azure Active Directory (AD) Security Assertion Markup Language (SAML) Toolkit Single Sign-On (SSO) enabled subscription.
IP Address of SevOne NMS Cluster Leader required.
3.2 Create / Configure Azure Active Directory Single Sign-On application
Login to the Azure portal.
Navigate to Azure Active Directory under Azure Services.
Click Add button to add an Enterprise application.
Click Create your own application button.
Enter application name.
Select Integrate any other application application you don't find in the gallery. i.e., Non-gallery.
From left navigation bar, under Manage, click Users and groups.
Click Add user/group, and select the Azure users and groups to have access to Single Sign-On.
Click Assign after users and groups have been added.
From left navigation bar, under Manage, click Single sign-on.
Select SAML as the single sign-on method.
Click in sectionBasic SAML Configurationto edit.
Change Identifier (Entity ID) tohttps://
<Cluster Leader IP address>
/sso/callback where
<Cluster Leader IP address>
is the IP address of your SevOne NMS cluster leader.
Change Reply URL (Assertion Consumer Service URL) to https://
<Cluster Leader IP address>
/sso/callbackwhere
<Cluster Leader IP address>
is the IP address of your SevOne NMS cluster leader.
Click Save followed by to close.
Please refer tohttps://docs.microsoft.com/en-us/azure/active-directory/saas-apps/saml-toolkit-tutorial for
details.
IMPORTANT: Upgrade / Install SevOne NMS
To use Single Sign-On feature, you must be on SevOne NMS 5.7.2.15 or higher version.
For now, create your own Azure active directory single sign-on application. In the future, this will change so that the user
can use the existing gallery application supporting SAML SSO.
Your account must be an Azure subscription administrator / owner.
If the button is unavailable, your account may not have the correct permissions.
Here, you will determine which Azure users to provide access to Single Sign-On.
You are now on SAML-based sign-on page.
To go back, click Single sign-on under Manage in the left navigation bar.
This field is used for IDP-initiated SSO, so it will not be used, but is required for application setup.
If you get a pop-up asking if you want to test the app, decline it for now.
SevOne SAML Single Sign-On Setup Guide
11
12.
13.
14.
a.
b.
c.
15.
a.
16.
1.
2.
3.
4.
a.
Click in sectionUser Attributes & Claims to edit.
Claim name for value user.mail must be http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
Click Add new claim.
Enter name as displayname.
Enter namespace as http://schemas.microsoft.com/identity/claims.
Enter source attribute as user.displayname.
In section SAML Signing Certificate,
for Certificate (Base64) > click Download.
In section Set up <your application name>, you will need the login URL for the next steps.
3.3 Configure Single Sign-On in NMS
Copy x.509 certificate, /usr/share/pki/sso/saml.pem, to SevOne NMS' cluster leader.
SSH into your Cluster Leader.
$ ssh root@<Cluster Leader IP address>
Run/usr/local/scripts/dex_setup_template.shscript to update the config template.
$ bash /usr/local/scripts/dex_setup_template.sh
Using a text editor of your choice, edit /etc/dex/config.yaml file.
$ vi /etc/dex/config.yaml
Uncomment the SAML section (starting with line
- id: saml
) by removing the # from each line.
The raw certificate will not work.
Please make sure that once the appliance or Virtual Machine is configured with the Single Sign-On, its IP
Addresscannotbe changed. Otherwise, Single Sign-On will fail.
If directory /usr/share/pki/sso does not exist, create it.
Running dex_setup_template.sh generates a new MySQL
dex password
as well as a new
OAuth secret
. If this script
must be run again for any reason, please use the new password and secret for any editing to be done on the
generated /etc/dex/config.yaml file. Failure to do so, results in the following authentication error forallactive dex
connectors.
Error
Authentication Exception: Invalid client credentials.
SevOne SAML Single Sign-On Setup Guide
12
b.
c.
d.
e.
f.
g.
h.
i.
j.
5.
6.
id - is an identifier unique to dex. If you do not have any other connections with id of SAML, you may leave it as
is.
name - is the text that will be shown on the user interface of Single Sign-On page. You may have a string with
spaces if you wrap it in quotation marks.
type - leave as saml.
ssoURL - on Azure, under the 4th section of Single Sign-On page, Set up <your application name>, copy the
Login URL and paste it here, wrapping in quotation marks. For example, "SSO Login URL".
ssoIssuer - change the name of this field to entityIssuer and set the field to "https://<Cluster Leader IP
address>/sso/callback"; it must be wrapped in quotes.
redirectURI - leave as-is.
ca - set field as /usr/share/pki/sso/saml.pem.
usernameAttr - set to "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"; it must be wrapped in
quotes. This maps to the name attribute in the 2nd section of the SAML-based Single Sign-On page, under
Attributes & Claims.
emailAttr - set to "http://schemas.microsoft.com/identity/claims/displayname"; it must be wrapped in quotes.
This maps to the EmailAddress attribute in Azure.
Example
- id: saml
name: saml
type: saml
config:
ssoURL: "SSO Login URL"
entityIssuer: "https://<Cluster Leader IP address>/sso/callback"
redirectURI: "https://<Cluster Leader IP address>/sso/callback"
ca: /usr/share/pki/sso/saml.pem
usernameAttr: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
emailAttr: "http://schemas.microsoft.com/identity/claims/displayname"
Restart SSO service. Please refer to section Restart Single Sign-On Service.
Enable SSO. Please refer to section Enable Single Sign-On.
The first 3 lines that start with ## should remain as comments.
SevOne SAML Single Sign-On Setup Guide
13
4 Restart Single Sign-On Service
Restart Single Sign-On service, dex, on the Cluster Leader for the configuration changes to take effect.
$ ssh root@<Cluster Leader IP address>
$ supervisorctl restart dex
SevOne SAML Single Sign-On Setup Guide
14
1.
2.
3.
4.
5.
6.
7.
5 Enable Single Sign-On
Log into the SevOne GUI as an administrator.
From the navigation bar, click on the Administrationmenu and selectCluster Manager.
Click on Cluster Settings tab.
Choose Login subtab.
Field Enable Peer Certificate Verification must be unchecked if you are using an unsigned SSL certificate.
Select the Enable Single Sign-On check box to enable Single Sign-On.
Click Save to save the Login settings.
If you are already logged in, refresh the user interface.
•
•
If you have followed the instructions to configure dex but have encountered the following error, it may be related
to one of the following issues.
Error
Login did not save successfully. The following errors were reported: Single Sign-On - Invalid configuration.
Please configure Dex before enabling Single Sign-On.
You may need to regenerate the SSL certificate for your appliance. Please refer to Generate a Self-Signed
Certificate or a Certificate Signing Request guide for details on generating the SSL certificate.
Configured DNS server in NMS should be able to resolve theOpenID-Connect Issuer URL.
Please make sure the Common Name when generating your certificate request matches the
OpenID-Connect Issuer URL field on this page. It should be the appliance IP address.
SevOne SAML Single Sign-On Setup Guide
15
6 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 Leader'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)"
SevOne SAML Single Sign-On Setup Guide
16
1.
2.
3.
4.
5.
a.
b.
c.
d.
e.
f.
g.
7 HSA Configuration
If the Cluster Leader 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 havedex running on an HSA prior to a failover, ability to login will be impaired
on the entire NMS cluster.
Once the Cluster Leader 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 Leader 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 Leader 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
Port all configuration options from the Cluster Leader's /etc/dex/config.yaml file on to the HSA.
Restart dex on the HSA.
Enable Single Sign-On from the graphical user interface. Execute the steps below.
From the navigation bar, click theAdministrationmenu and selectCluster Manager.
Click on Cluster Settings tab.
Click on Login subtab.
Unselect theEnable Single Sign-On check box.
ClickSave to save the settings.
Select the Enable Single Sign-On check box.
ClickSaveto save the settings.
This will regenerate a bare-minimum working dex configuration with a valid dex secret and dex MySQL
password. Update the existing/etc/dex/config.yamlfile with the newly generateddex secretanddex MySQL
password.
Even if the setup script is used to generate a validdexconfiguration, you are still required to port the configuration
from the Cluster Leader.
The same steps must be taken when a failback is performed from the HSA to the Cluster Leader.
SevOne NMS is using SAML. However, SevOne Data Insight is using OpenID-Connect.
dex wraps SAML in OpenID-Connect tokens.
SevOne SAML Single Sign-On Setup Guide
17
1.
2.
3.
4.
5.
8 Upgrade Process
If you are upgrading from SevOne NMS 5.7.2.15, had Single Sign-On enabled, and dex configuration has changed, you will need to re-
enable Single Sign-On. Please follow the steps below.
SSH into the Cluster Leader IP address.
$ ssh root@<Cluster Leader IP address>
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.
Restart Single Sign-On service,dex, on the Cluster Leader for the configuration changes to take effect.
$ supervisorctl restart dex
•
•
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.
For IdP initiated login support, Default RelayState must be set to the NMS client ID, sevonenms. Please refer to Default
RelayState for more details.
SevOne SAML Single Sign-On Setup Guide
18
9 Login CSRF
Login CSRF is a type of attack where the attacker can force the user to log in to the attacker’s account on a website and thus reveal
information about what the user is doing while logged in. The risk varies depending on the application and hard to detect / evaluate
it. If a public registration for the application exists, therisk of an attack increases drastically as it is very easy for the attacker to create
an account and thus, know the credentials for it.
Login CSRF is like any other CSRF. The only difference is that it occurs on the login form. For additional information, you may search
for CSRF in general from your web browser.
To prevent Login CSRF, you must implement a token system in your code to ensure that a random token (i.e., CSRFToken) is
generated which is set as a cookie and as a hidden value in the form. When the form is submitted, the code must check if the token in
the form is the same as the token in the cookie and if the token matches, you will be able to log in.
The token works as a protection because the attacker does not know the value of the cookie CSRFToken and therefore, cannot send
that value in the form.
Details in this section have been gathered from https://support.detectify.com/support/solutions/articles/48001048951-
login-csrf. For examples and additional details, you may click on this link.
SevOne SAML Single Sign-On Setup Guide
19
1.
2.
3.
10 Troubleshooting
10.1 Is DEX Running?
To identify the status of dex on the Cluster Leader, you must execute the following command.
SSH to Cluster Leader.
$ ssh <Cluster Leader IP address>
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
This indicates that you are on the Cluster Leader, /etc/dex/config.yaml file is present, and dex is RUNNING.
dexmust be running onCluster Leaderand/etc/dex/config.yamlfile must be present.
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
SevOne SAML Single Sign-On Setup Guide
20
Example: SevOne-dexctl status > returns FAILURE
In this scenario, make sure that, you are on the Cluster Leader 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
Single Sign-On can be enabled from the SevOne NMS Graphical User Interface. Enter the URL of your Cluster Leader,
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.
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
•
•
•
If you are not on Cluster Leader 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.
SevOne SAML Single Sign-On Setup Guide
21
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
11 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 is NMS 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 isx.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 doesssoURL & ssoIssuermean 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 doesredirectURI & entityIssuer mean in/etc/dex/config.yamlfile?
The redirectURI and entityIssuer must point to the NMS Cluster Leader'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 Leader IP address>.
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 signing algorithm?
Yes.
What are the certificate signing options?
Applications can only sign SAML assertions.
What is the requirement for IdP?
Base64-encoded and URLs.
Is Service Provider Metadata required?
No.
Is SAML JIT support required?
No.
Is User Provisioning support required?
No.
