Introduction
This article will describe the different settings that must be configured to make a Inbound SAML connection work between an Identity Provider (IDP) and Reward Gateway, i.e. the Service Provider.
Whether using an existing IDP or a custom SAML connector, this guide explains the settings involved with completing the setup. At the end of the article information is included on how to create and use deep links using an Identity Provider URL or an ACS (Assertion Consumer Service) URL.
Please note that some of these fields may not be required, depending on the Identity Provider used with Reward Gateway.
For more information about SAML, see: Overview of Inbound SSO with SAML
Setting Up the Inbound SAML Integration - Summary of Steps
The high-level process steps which are needed to set up the Inbound SAML integration are:
Step 1. Finding and selecting the Inbound SAML integration in Reward Manager
Step 2. Initial setup: Capturing identity provider details
Step 3. Mapping: Mapping SAML attributes from the IDP to SP
Step 4. Testing: Testing the connector
Step 5. Review and Publish: Review the setup and request it to be published
Below is a video of the process, as well as written instructions for how to do all of the process steps.
Video of Process
You can watch the following video, or follow the guide below:
Process Steps
Step 1. Finding and Selecting the 'Inbound SAML' Integration in Reward Manager
1. Log into Reward Manager
2. Select Integrations > Integrations Dashboard from the menu on the left
3. Under the Explore tab, click on Inbound SAML which will take you to the configuration page
Note: If you don’t have to the Integrations Dashboard, please speak with your Client Success Manager, or a member of the Client Support Team, who will assign your permissions.
Step 2. Initial Setup
1. Add the Configuration Name
This should be a name to uniquely identify the integration.
This name will be used on the login page, if a Sign In with button is displayed, for example, Sign in with Okta
2. Add the Parameter Name
This is defaulted to SAMLResponse - but if it is different it can be changed.
3. Add the 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.
4. Select the relevant option under Signature check to be performed on, either SAML Response or SAML Assertion:
This should be based on which element of the SAML Response is signed using the certificate above. I.e. either the full SAML Response or just the SAML Assertion.
In most cases, this would be SAML Assertion.
5. Consider whether to select the Service Provider Initiated Authentication? option:
The authentication is Service Provider initiated when the user has a Log in via SSO button on the Login page that initiates the authentication (as opposed to clicking a button on your intranet leading to the platform).
This option can provide more secure authentication between the identity provider and the platform, by sending an additional detail to the identity provider which must be returned as a part of the SAML Response. This serves as an extra layer of verification.
6. Add the 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 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 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.
Step 3. Mapping
This section will allow mapping of the outgoing fields / claims from the IDP to fields onto the Reward Gateway platform.
1. Select the Identifier
Choose the unique identifier used to identify your members.
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.
2. Select the SAML Identity Location
You can choose to send the employee identifier through one of the following two options:
- The Name Identifier by selecting the Identity is in the Name Identifier element of the Subject Statement option.
- As a separate attribute claim (under a different field, e.g. Email Address) by selecting the Identity is in an Attribute element option.
If it is a separate attribute claim, you need to include what the outgoing claim alias is.
3. Configure Additional Attributes
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.
4. Enable or Disable 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 populate the fields during the onboarding of the member.
You can learn more about JIT in the following article: Just-In-Time (JIT) Provisioning
Step 4. Testing
1. At this stage, you can make a login attempt to test the integration:
2. These attempts should be picked up automatically and any errors will be displayed along with the assertion attempt.
3. Once any identified errors are fixed and a successful attempt has been made, the greyed out Next button will turn green and allow you to proceed to the next step.
Step 5. Review and Publish
1. Once Testing is completed, you can review the Integration settings and click Complete at the bottom.
2. Once completed, the SSO integration will be in a Pending state. You can then publish it by going back to the Integrations dashboard, and selecting Options > Publish.
How to Create and Use Deep Links
If you'd like to redirect users to different parts of the platform with deep links, there are two ways to do it:
- Add an Identity Provider URL
- Change the ACS URL
1. Add an Identity Provider URL
1. Add the Identity Provider URL in the configuration in Reward Manager and then create links, using the following format:
- When you take the ACS URL, change EndLogin to StartLogin
- 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
An example of the full URL, which will initiate the SSO and once authenticated, the users will land on a platform page: https://site1.rewardgateway.dev/Authentication/StartLogin?idp=88&url=Search?sFields[a]=12&sType=Attribute
2. Change the 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
Further Assistance
If you have any questions on this process, please reach out to the Integrations Team at: clientintegrations@rewardgateway.com