SuccessPro Single-Sign-On Overview

SuccessPro SAML SSO Integration Overview

The SuccessPro platform supports Single Sign-On integration via the SAML 2.0 protocol, where SuccessPro acts as the Service Provider. The integration is most commonly implemented in conjunction with an automated user provisioning and hierarchy configuration process to ensure security, availability, and ease of user maintenance, where a unique identifier (tenantSpecificUserId) is populated in our system and referenced during the SSO auth flow.
  • SuccessPro supports both Identity Provider-initiated SSO (User action begins in the tenant’s system) and Service Provider-initiated SSO (User action begins in SuccessPro), and clients have the option to utilize one or both flows depending on requirements.
  • SuccessPro supports but does not require, encrypted assertions and signed requests.
As part of the SAML SSO integration, SuccessPro requires that an agreed-upon unique identifier be passed in every SAML assertion. This attribute, referred to in the SuccessPro system as tenantSpecificUserId, must match the unique identifier passed as part of the user provisioning process.


Initial Setup and Configuration of an SSO Integration

To establish an initial SSO integration, ActiFi and the tenant need to exchange information about their respective systems, such as the location of the systems (the URLs), public certificates that represent the trusted identity of each system, and agreed-upon user attributes to share.
    Request that the tenant’s tech team provide either metadata files for their system or the certificates for their respective PROD and DEV environments. Once received, pass these to the ActiFi dev team to finish the configuration.
    Submit a request to the ActiFi development team to enable an SSO endpoint for the tenant. Once the endpoint has been established, the development team will supply “metadata” XML files for both a DEV and PROD environment. These metadata files contain information about the SSO connection location, what user attributes ActiFi requires (most importantly, tenantSpecificUserId), and a public certificate that identifies ActiFi as a trusted partner.
    Via the admin screens, configure an “SSO Identity Provider Default” and “SSO Service Provider Default” Relay State for both DEV and PROD environments. You do not need to provide the Relay State names to the tenant’s tech team if the Relay States are configured as the IDP Default. The SuccessPro SSO service will use these Relay States when no other Relay State is provided during authentication. (see below for detailed Relay State instructions)
    Deliver the metadata files to the tenant’s tech team. (The files do not contain sensitive information and can be safely emailed.)
    If the client will be using an SSO Login button on the SuccessPro login screen (SP-Initiated SSO), request the “SP-Initiated IDP Login URL” from the client and supply this URL to the ActiFi tech team.


Relay State Configuration

  • Relay State represents a location or resource within SuccessPro. After a user authenticates and their identity is confirmed, the application will redirect the user to the location or resource represented by the Relay State. Relay States are configured via the SuccessPro admin console.
    Access the Relay State UI via Admin → Users & Access → Auth/SSO → SSO RelayStates
    Click “New”.
  • Active - If unchecked, the SSO system will ignore the Relay State
  • SSO Service Provider Default - If checked, this Relay State will be used when the SSO button on the SuccessPro login page is clicked (if enabled).
  • SSO Identity Provider Default - If checked, this Relay State will be used when a tenant user initiates SSO from their internal portal via a link with no Relay State provided.
  • Name - Unique identifier for the Relay State. Should be supplied to the IDP if not the default.
  • Redirect/Link Type (and optional additional drop-downs) - Used to configure the Relay State target.
    Once configured, if the Relay State is not an SP or IDP default, supply the Relay State Name to the tenant’s tech team to configure in their internal portal.

NOTE: Relay States can also be used internally via the following link format: https://[tenant].actifi.com/auth/wall?relayState=[Relay State Name]

These links are separate from any SSO integration and will have one of two behaviors when clicked:
    If the user who clicks the link is already authenticated in SuccessPro, the user will be automatically redirected to the resource represented by the Relay State.
    If the user is not authenticated, they will be presented with a login screen where they can enter credentials or request a one-time code sent to their email. After successful authentication, the user will be redirected to the resource represented by the Relay State.


Common Error Messages

The SuccessPro SSO services may redirect users to a message page if an error or misconfiguration is encountered during the authentication and relay process. The errors listed below represent default behavior. Many are customizable at the tenant level.

Resource Not Found

The user identity was successfully established, but the RelayState configuration did not point to a valid resource to target for a redirect.

User Not Found

Error: The user represented by the SSO assertion was not found in the SuccessPro system.

SSO System Error

An error occurred while attempting to consume the SSO assertion. This error is not customizable at the tenant level.