SevOne SAML Single Sign On Setup Guide

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. These setups have been tested and are supported by IBM SevOne. There are other identity providers which may work but have not been tested by IBM SevOne.

• 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.
  Note: Please refer to https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/saml-toolkit-tutorial for details.
• IP Address of SevOne NMS Cluster Leader required.
  Important: Upgrade / Install SevOne NMS

  To use Single Sign-On feature, you must be on SevOne NMS 5.7.2.15 or higher version.

1. Login to the Azure portal.
   Important: Your account must be an Azure subscription administrator / owner.
2. Navigate to Azure Active Directory under Azure Services.
3. Click Add button to add an Enterprise application.
4. Click Create your own application button.
   Important: If the button is unavailable, your account may not have the correct permissions.
   1. Enter application name.
   2. Select Integrate any other application application you don't find in the gallery. i.e., Non-gallery.
5. From left navigation bar, under Manage, click Users and groups.
   Important: Here, you will determine which Azure users to provide access to Single Sign-On.
6. Click Add user/group, and select the Azure users and groups to have access to Single Sign-On.
7. Click Assign after users and groups have been added.
8. From left navigation bar, under Manage, click Single sign-on.
9. Select SAML as the single sign-on method.
   Note: You are now on SAML-based sign-on page.

   To go back, click Single sign-on under Manage in the left navigation bar.

10. Click in section Basic SAML Configuration to edit.
    1. Change Identifier (Entity ID) to https://<Cluster Leader IP address>/sso/callback where <Cluster Leader IP address> is the IP address of your SevOne NMS cluster leader.
    2. Change Reply URL (Assertion Consumer Service URL) to https://<Cluster Leader IP address>/sso/callback where <Cluster Leader IP address> is the IP address of your SevOne NMS cluster leader.
       Important: This field is used for IDP-initiated SSO, so it will not be used, but is required for application setup.
11. Click Save followed by to close.
    Important: If you get a pop-up asking if you want to test the app, decline it for now.
12. Click in section User Attributes & Claims to edit.
13. Claim name for value user.mail must be http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
14. Click Add new claim.
    1. Enter name as displayname.
    2. Enter namespace as http://schemas.microsoft.com/identity/claims.
    3. Enter source attribute as user.displayname.
15. In section SAML Signing Certificate,
    1. for Certificate (Base64) > click Download.
       Important: The raw certificate will not work.
16. In section Set up <your application name>, you will need the login URL for the next steps.

1. Copy x.509 certificate, /secrets/dex/saml.pem, to SevOne NMS' cluster leader.
   Important: If directory /secrets/dex does not exist, create it.
2. SSH into your Cluster Leader as support.

   $ ssh support@<Cluster Leader IP address>

3. Run /usr/local/scripts/dex_setup_template.sh script to update the config template.

   
   $ sudo su
   
   $ podman exec -it nms-nms-nms /bin/bash
   
   $ bash /usr/local/scripts/dex_setup_template.sh
   

   Note: 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 /config/dex.yaml file. Failure to do so, results in the following authentication error for all active dex connectors.

   Error

   Authentication Exception: Invalid client credentials.

4. Using a text editor of your choice, edit /config/dex.yaml file.

   vi /config/dex.yaml

   1. Uncomment the SAML section (starting with line - id: azure or - id: okta) by removing the # from each line.
      Note: The first 3 lines that start with ## should remain as comments.
   2. 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.
   3. 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.
   4. type - leave as saml.
   5. 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".
   6. 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.
   7. redirectURI - leave as-is.
   8. ca - set field as /secrets/dex/saml.pem.
   9. 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.
   10. 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: "https://login.microsoftonline.com/uuid/saml2"
       entityIssuer: "https://10.49.8.85/sso/callback"
       redirectURI: "https://10.49.8.85/sso/callback"
       ca: /secrets/dex/saml.pem
       usernameAttr: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
       emailAttr: "http://schemas.microsoft.com/identity/claims/displayname"
   

5. Restart SSO service. Please refer to section RESTART SINGLE SIGN-ON SERVICE.
6. Enable SSO. Please refer to section ENABLE SINGLE SIGN-ON.

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

systemctl restart dex

1. Log into the SevOne GUI as an administrator.
   Important: If you are already logged in, refresh the user interface.
2. From the navigation bar, click on the Administration menu and select Cluster Manager.
3. Click on Cluster Settings tab.
4. Choose Login subtab.
5. Field Enable Peer Certificate Verification must be unchecked if you are using an unsigned SSL certificate.
6. Select the Enable Single Sign-On check box to enable Single Sign-On.
7. Click Save to save the Login settings.
   Note: 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.
     Important: 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.
   • Configured DNS server in NMS should be able to resolve the OpenID-Connect Issuer URL.

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)"

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 have dex 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.

1. Fail over the Cluster Leader to the HSA.
2. 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

   Note: This will regenerate a bare-minimum working dex configuration with a valid dex secret and dex MySQL password. Update the existing /config/dex.yaml file with the newly generated dex secret and dex MySQL password.
3. Port all configuration options from the Cluster Leader's /config/dex.yaml file on to the HSA.
   Note: Even if the setup script is used to generate a valid dex configuration, you are still required to port the configuration from the Cluster Leader.
4. Restart dex on the HSA.
5. 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.

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.

1. SSH into the Cluster Leader IP address as support.

   $ ssh support@<Cluster Leader IP address>

2. Rerun the setup script.

   
   $ sudo su
   
   $ podman exec -it nms-nms-nms /bin/bash
   
   $ bash /usr/local/scripts/dex_setup_template.sh
   

3. A new config will be written to /config/dex.yaml. And, it will save the old config to /config/dex.yaml.backup.
4. Copy and paste the custom config from connectors section in /config/dex.yaml.backup to the connectors section in /config/dex.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.
5. Restart Single Sign-On service, dex, on the Cluster Leader for the configuration changes to take effect.

   systemctl restart dex

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, the risk 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.

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

1. Execute the following command from the host to check the dex status.

   systemctl status dex

   If dex is running, it will return a message similar to the example below.

   Example
   

   
   dex.service - Dex
      Loaded: loaded (/etc/containers/systemd/dex.container; generated)
      Active: active (running) since Tue 2024-07-09 17:34:59 UTC; 2h 1min ago
     Process: 2365965 ExecStopPost=/usr/bin/podman rm -v -f -i --cidfile=/run/dex.cid (code=exited, status=0/SUCCESS)
     Process: 2365934 ExecStop=/usr/bin/podman rm -v -f -i --cidfile=/run/dex.cid (code=exited, status=0/SUCCESS)
    Main PID: 2366012 (conmon)
       Tasks: 8 (limit: 50216)
      Memory: 36.4M
      CGroup: /system.slice/dex.service
              ├─libpod-payload-8e37a5524368883e88c0110ac49f63b8316f4a4143a23a1a8add5d8b1d4e91a3
              │ └─2366022 /usr/local/bin/dex serve /config/dex.yaml
              └─runtime
                ├─2366009 /usr/bin/fuse-overlayfs -o lowerdir=/var/lib/containers/storage/overlay/l/XOFTFBIRI3IHVUTF7QIIMDMREL:/var/lib/containers/storage/overlay/l/CP>
                └─2366012 /usr/bin/conmon --api-version 1 -c 8e37a5524368883e88c0110ac49f63b8316f4a4143a23a1a8add5d8b1d4e91a3 -u 8e37a5524368883e88c0110ac49f63b8316f4a>
   

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

   If dex is not running, you will see a message similar to the example below.

   Example
   

   
   dex.service - Dex
      Loaded: loaded (/etc/containers/systemd/dex.container; generated)
      Active: inactive (dead)
   

   In this scenario, make sure that, you are on the Cluster Leader and /config/dex.yaml file is present prior to restarting dex.

   systemctl restart dex

   Note: systemctl status dex 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 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.

1. 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 /config/dex.yaml file. Currently it is set to NMS Client ID, sevonenms.

   For additional details, please refer to https://stackoverflow.com/a/34351756

2. 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.

3. 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.

4. 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.

5. What does ssoURL & ssoIssuer mean in /config/dex.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.

6. What does redirectURI & entityIssuer mean in /config/dex.yaml file?

   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>.

7. 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.

8. Does SevOne support SHA-256 or higher certificate signing algorithm?

   Yes.

9. What are the certificate signing options?

   Applications can only sign SAML assertions.

10. What is the requirement for IdP?

    Base64-encoded and URLs.

11. Is Service Provider Metadata required?

    No.

12. Is SAML JIT support required?

    No.

13. Is User Provisioning support required?

    No.

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