SAML Integration: Terminology & Requirements

This article discusses the technical requirements, components, and terminology related to SAML 2.0 SSO integration. To see the guide related directly to SAML SSO configuration in the admin website, go to this article about SAML configuration. 

Engagement Rx (the Service Provider) and the client company (the Identity Provider) must perform the following steps to start the SAML integration process:

1. Upload SAML Signing Certificate: Client company uploads their SAML Signing Certificate in the form of a X.509 certificate via the admin website (in the Certificate Manager module of the Settings section; up to two certificates can be uploaded per portal). The client's SAML Response is signed by the private key, while Engagement Rx uses the public key to verify the SAML signature to begin the integration process.
2. Generate and Upload SAML Encryption Certificate: Client company generates a SAML Encryption certificate (in the Certificate Manager module of the Settings section in the admin website), then downloads the Metadata XML file to retrieve the public key. The client company must encrypt the SAML assertion using the public key. Encryptions should be contained within an EncryptionAssertion XML node inside the SAML Response.*
3. Identify and Map Included Fields: The client company identifies the fields which are included in the SAML assertion from the set list of Engagement Rx field names. Included fields must be mapped.

*Details for Encrypting Assertion Data

A cipher with a symmetric key should be used to encrypt the SAML assertion. Within the EncryptedAssertion node, the cipher used is specified by the EncyptionMethod element; the KeyInfo element is used to describe the symmetric key used.

The encrypted assertion is stored in the CipherValue element after being encrypted using the symmetric cipher. The symmetric key should then be encrypted using the SAML Encryption public key which can be retrieved from the Engagement Rx Admin website (in the Certificate Manager module of the Tools section). The encrypted symmetric key is stored in the CipherValue element.

Here are the acceptable symmetric ciphers:

• TRIPLEDES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc
• AES-128: http://www.w3.org/2001/04/xmlenc#aes128-cbc
• AES-256: http://www.w3.org/2001/04/xmlenc#aes256-cbc
• AES-1: http://www.w3.org/2001/04/xmlenc#aes192-cbc
• TRIPLEDES KeyWrap: http://www.w3.org/2001/04/xmlenc#kw-tripledes
• AES-128 KeyWrap: http://www.w3.org/2001/04/xmlenc#kw-aes128
• AES-256 KeyWrap: http://www.w3.org/2001/04/xmlenc#kw-aes256
• AES-192 KeyWrap: http://www.w3.org/2001/04/xmlenc#kw-aes192

 The allowed asymmetric ciphers are:

• RSA-OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

Transport Details

The SAML assertion is transported to the Service Provider via an HTTP POST request in accordance with SAML 2.0 protocol. The assertion body is base64-encoded; Engagement Rx expects the assertion to be embedded inside an HTML<form> tag under the name “SAMLResponse”.

Target Resource

The system supports a Target Resource by specifically requesting the resource under the RelayState parameter. If a valid Target Resource is requested and the member’s SSO login is successful, the member will be redirected to the Target Resource.

The resource must be enabled for the portal for the redirect to occur (otherwise normal redirection will occur instead). The Target Resource is case sensitive.

Here is the complete set of supported resources within the system:

SAML Member Attributes

Member attributes are pieces of data that describe individual members in a portal (in the Engagement Rx system). Member attributes are used to identify members, group members in reports, and/or the pass-through of data back to the client if data-feeds are being used. You can see the full list of member attributes, values, and related details here.