Introduction
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: Overview of 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 URLDepending 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.
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 (JIT) 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.
How to create and use deep links
If you'd like to redirect users to different parts of the platform with deeplinks, there are two ways to do it; add an Identity Provider URL or change ACS URL.
Add an Identity Provider URL
Add the Identity Provider URL in the configuration in Reward Manager and then create links, using the following format, where you take the ACS URL from us, change "EndLogin" to "StartLogin" and add &url=MyRewards or whatever the extension might be. You can copy the extension from the platform when you've opened the page.
For example: Search?sFields[a]=12&sType=Attribute
So this will be an example of the full URL, which will initiate the SSO and once authenticated, the users will land on the Top Offers page - https://site1.rewardgateway.dev/Authentication/StartLogin?idp=88&url=Search?sFields[a]=12&sType=Attribute
Change ACS URL
If you don't add the Identity Provider URL in Reward Manager, then you'll need to change the ACS URL in the configuration on your side to have the extension at the end.
This is an example of how the ACS URL should be added: https://site1.rewardgateway.dev/Authentication/EndLogin?idp=88&url=Search?sFields[a]=12&sType=Attribute
If you have any questions, reach out to the Integrations Team clientintegrations@rewardgateway.com