Security Assertion Markup Language (SAML) Setup Guide

High-level overview of how Security Assertion Markup Language (SAML) works and how to set it up in RiskSense.

Introduction

Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context. This single sign-on (SSO) login standard has significant advantages over logging in using a username/password:

  • No need to type in credentials.
  • No need to remember and renew passwords.
  • No weak passwords.

Most organizations already know the identity of users because they are logged in to their Active Directory domain or intranet. It makes sense to use this information to log users in to other applications, such as web-based applications, and one of the more elegant ways of doing this is by using SAML.

This guide provides a high-level overview of SAML, shows how it works, and includes steps to set up SSO with RiskSense.

How SAML Works

SAML SSO works by transferring the user’s identity from one place (the identity provider) to another (the service provider). This is done through an exchange of digitally signed XML documents. SAML is XML-based, which makes it a very flexible standard. Two federation partners can choose to share whatever identity attributes they want in a SAML assertion (message) payload if those attributes can be represented in XML. RiskSense requires two attributes: an email address, and another attribute chosen by the identity provider. The attribute names are configurable in RiskSense and will likely differ between identity providers.

Consider the following scenario: A user is logged into a system that acts as an identity provider. The user wants to log in to the RiskSense application (the service provider). The following happens:

  1. The user accesses the remote application using an intranet link, a bookmark, or similar, and the application loads.
  2. The application identifies the user’s origin via a user supplied email address and redirects the user back to the identity provider, asking for authentication. This is the authentication request.
  3. The user either has an existing active browser session with the identity provider or establishes one by logging into the identity provider.
  4. The identity provider builds the authentication response in the form of an XML-document containing the user’s username or email address, signs it using an X.509 certificate, and posts this information to the service provider.
  5. The service provider, which already knows the identity provider and has a certificate fingerprint, retrieves the authentication response and validates it using the certificate fingerprint.
  6. The identity of the user is established, and the user is provided with application access.

SAML SSO Configuration and Login Workflow

The following diagram illustrates the configuration and workflow used to carry out a service-provider-initiated SAML SSO login that, when attempting to log in to a remote application such as the RiskSense platform, triggers the SAML SSO workflow event sequence.

SAML Setup - Workflow

RiskSense SAML Setup Process

  1. Identify customer point of contact for SSO implementation. This contact will work with a RiskSense Customer Success Operations Manager (CSOM) to set up SAML.
  2. The customer SSO contact and RiskSense CSOM have an initial meeting to discuss implementation. The following topics and guidelines are discussed:
    1. RiskSense uses two authentication attributes that need to be established on the client’s SSO solution. Please note that each attribute name is case sensitive.
      • The first authentication attribute is always an email address. This cannot be changed. Please note that this must be the email address that the identity provider responds with.
      • The second attribute can be whatever the client wants. Examples include first name, last name, company ID number, etc.
      • For both attributes, it helps us to know how the authentication attribute will be written out when “asked” for by the SSO. For example, if the two attributes used are email and first name and the SSO identifies them spelled out as “E-mail” and “fname”, RiskSense needs to ensure that we enter these two credential designations spelled out the exact same way.
    2. We need to establish who will test the logins. Will the SSO contact be authorized to log into RiskSense to test the connection, or will another user need to be set up with a RiskSense login to test the connection?
  3. After the credentials are set, the client must send their updated metadata file to RiskSense in a secure email.
  4. We will send our metadata file to the client in a secure email to upload in the client’s SSO solution.
  5. Once completed, have the designated login tester attempt to sign in. If all goes well, they should be logged into the platform. If not, RiskSense has logs we can check to ascertain the compatibility issue. Common issues include:
    1. A mismatch of credentials.
    2. A mismatch in spelling of credentials.
    3. Authentication credentials not sent to RiskSense.
    4. Client’s metadata file may contain errors.
  6. Additional meetings can be set up, if needed, between RiskSense and the SSO contact to troubleshoot and review any errors to ensure a successful connection.
  7. Once the login is successful, other RiskSense users will be upgraded to SAML. This can be performed by manager-level RiskSense users or by the RiskSense support team.
  8. If the initial tester needs to be deactivated, RiskSense support will deactivate the user.

Creating a SAML User

To create a SAML user, see Creating a SAML User.

Logging in as a SAML User

To log into RiskSense as a SAML user, see Logging into RiskSense Using SAML.