This article will describe the different settings that must be configured to make a SAML connection work between an IDP (Identity Provider) and Reward Gateway (Service Provider). 

Whether using an existing IDP or a Custom SAML connector this guide will help make a better understanding of the settings involved with completing the setup. 

Please note, that some of these fields may not be required depending on the Identity Provider used with Reward Gateway.

Recommended reading before Guide to Inbound SSO with SAML

Creating a new Inbound integration

To create an Inbound SSO integration, log into Reward Manager > ‘Integrations’ tab on the left. Under the ‘Explore’ tab, click on ‘Inbound SAML’ which will take you to the configuration page. 

If you don’t have access please speak with your Client Success Manager or a member of the Client Support team who will assign your permissions.

You can watch the following video or follow the guide below:

Initial Setup

Configuration Name

A name to uniquely identify the integration. This name will be used if a “Sign In with” button is displayed on the login page, i.e. “Sign in with Okta”.

Parameter Name

It is defaulted to 'SAML Response' but if it is different it can be changed.

Certificate

We require that the SAML response is signed to verify the client’s identity. This is different from the SSL certificate and will be provided by the IDP. You can either upload a .crt file or paste a valid X.509 .pem Certificate. 

Signature check to be performed on

What element of the SAML Response is signed using the certificate above? Is it the full SAML Response or just the SAML Assertions?
In most cases, this should be SAML Assertion. 

Service Provider Initiated Authentication?

The authentication is SP (RG) initiated when the user has a ‘Log in via SSO’ button on the RG Login page which initiates the authentication (as opposed to clicking a button on your intranet leading to RG). 
This option can provide more secure authentication between the identity provider and RG by sending an additional detail to the identity provider which must be returned to RG as a part of the SAML Response. This serves as an extra layer of verification. 

Identity Provider URL
Depending on the mode of SSO (SP initiated or IDP initiated) this field will be mandatory or optional.
If it is SP Initiated (users have a ‘Log in via SSO’ button on the RG login page), it is a mandatory field as a SAML Request must be sent to initiate the authentication attempt.

If it is an IDP initiated setup (users have a button on the company intranet leading to the RG platform), it is optional. However, if there is a sign-in page or something similar for the IDP, you can include this here as it will help redirect users to the correct place to get authenticated - for example, they will be led to the Microsoft Login page to enter their credentials.
Encrypted Assertions

Encrypting the SAML assertion is optional. In most situations, it isn't encrypted and privacy is provided at the transport layer using HTTPS. 2. It's an extra level of security that's enabled if the SAML assertion contains particularly sensitive user information or the environment dictates the need.

Mapping

This section will allow mapping of the outgoing fields / claims from the IDP to fields on Reward Gateway. 

Identifier
Choose the unique identifier used to identify the member. If your scheme is Preloaded, you can choose between Payroll Number (Employee ID) or Email Address. If your scheme is on self-registration, this will be the Employee ID by default.

SAML Identity Location

You can choose to send the employee identifier through the Name Identifier or as a separate attribute claim (under a different field, e.g. Email Address). If it is a separate attribute claim, you need to include what the outgoing alias is.

Additional Attributes

Additionally, you can configure any of the attributes displayed on this page. Including the outgoing claim types or aliases for these and they will automatically be mapped during the SAML transfer.

Just-in-Time Provisioning

If enabled, we will automatically create an account for the employee after their first SSO login. The additional attributes configured above will be used to pre-populate the fields during the onboarding of the member.
You can learn more about JIT in the following article: Just-In-Time Provisioning

Testing

At this stage, you can make a login attempt to test the integration. These attempts should be picked up automatically and in case of any errors, they will be displayed on the screen along with the assertion attempt.

Once any errors identified are fixed and a successful attempt has been made, the greyed out “Next” button would turn green and allow you to proceed to the next step.

Review and Publish

Once Testing is completed, you can review the Integration settings and click ‘Complete’ at the bottom. Once completed, the SSO integration will be in a 'Pending' state. You can then publish it by going back to the integrations dashboard, and clicking on Options > Publish.