How to set up an ADFS integration for Authentication

In this article, we’ll run through how our clients can seamlessly integrate their Active Directory Federation Services (ADFS) for authenticating their employees.

Before continuing, we recommended reading the article: Guide to SAML Integration Settings

How do clients enable the ADFS integration?

To enable the ADFS integration, clients should log into Reward Manager, go to the Integration Dashboard and search for “ADFS” under the “Explore Integrations” tab. 

Select the integration and turn it “On” using the toggle button in the top right-hand side.

Setup ADFS for Reward Gateway

Step 1: Add Relying Party Trust

To start, add a Relying Party Trust by using the ADFS Management console and follow the Add Relying Party Trust Wizard.

Step 2: Select a Data Source

Choose the option to enter data about the relying party trust manually.

Step 3: Specify Display Name

Clients should then select a display name to represent their Relying Party Trust. Most put Reward Gateway or their program name here.

Step 4: Configure Certificate

No token encryption certificate is needed so ignore this step and proceed to the next.

Step 5: Configure URL

Tick the “Enable support for the SAML 2.0 WebSSO protocol” check box. 

To complete this step, clients will need their “SAML Consumer URL” which can be found on the Integration page on Reward Manager. It will look as below:

Copy the SAML Consumer URL and paste it into the “Relying party SAML 2.0 SSO service URL” box. It is worth taking note of your “Entity ID” too as you’ll need it in the next step.

Step 5: Configure Identifiers

Clients now need to enter their Entity ID into the “Relying party trust identifier” box. This may be the same domain as their program. 

Step 6: Choose Access Control

Clients can choose to permit all users now, and later choose to define more specific security policies if applicable.

Step 7: Complete adding the relying party

Ensure that the “Configure claims issuance policy for this application” check box is ticked, and click close.

Step 8: Edit Claims for Issuance

Under the Issuance Transform Rules dialog box, click Add Rule. 

Step 9: Choose Rule Type

From the “Claim rule template” drop-down menu, select the option to “Send LDAP Attributes as Claims”.

Step 10: Configure Claim Rule

This step is important. Claim rules will define how data about employees will be sent over to Reward Gateway.

Clients should chose the LDAP attribute they’d like to send and select the “Outgoing Claim Type” from the right. Note: The Outgoing Claim Type box can also be used to create custom claims.

To find out what data needs to be sent over as claims, refer back to the integration page on Reward Manager. Clients can always come back and edit their claim rules.

For more information mapping fields: https://docs.google.com/document/d/1E0ULHcA3ucFBiDrxfVeq8ACETGG7WqRgrAHMomG-J-A/edit

Step 11: Exporting the token signing certificate

As SAML Responses generated from the ADFS will be signed using a clients token signing certificate, Reward Gateway requires it to be on record. Clients should select their token signing certificate and export it as a “base64 encoded X.509 cer” – see second screenshot below. Keep hold of this as we’ll need it to complete the second part of the setup – Setup Reward Gateway for ADFS.

Setup Reward Gateway Integration for ADFS

For any further help understanding the settings on the setup, please refer back to this guide, How to set up an Inbound SSO integration.

Now that the ADFS is setup and complete, we can go ahead and complete the setup of the integration on Reward Manager. Clients should go back to their integration page for ADFS, and start with the initial step.

Step 1: Give the integration a name

Make it something that employees have heard of. 

Step 2: Upload the certificate

Clients need to take a copy of the token signing certificate they exported from their ADFS management console, and either upload it here or copy & paste the contents of it using the copy & paste option.

Step 3: Identity Provider URL

This would be the ADFS Sign In page url for the ADFS instance. Usually it is something like:

https://servername.companyname.com/adfs/ls/IdpInitiatedSignOn.aspx

Note: If a client wants to deep link directly into the relying party they created before, add the identifier as a parameter (loginToRP) to the identity provider url. 

For example:

https://servername.companyname.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRP=[RELYING-PARTY-IDENTIFIER]

Step 4: Mapping

We now need to map the Claim rules we setup on the ADFS to actual fields on Reward Gateway. 

Select which field is sending over the identity of the member – Payroll ID, Employee ID etc. – and then add any additional attributes.

For example: Email Address (Reward Gateway) => http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress  

Step 5: Testing

To test the integration, login via the ADFS Sign In URL configured in Step 3. This can be via a Test AD user.

If any errors were made in the setup, they will be displayed here. Clients should fix them and attempt to sign in again. Once the testing has passed, they’ll be allowed to review and publish their integration.

Step 6: Launch

After the connection has been tested and published, the clients Client Success Manager and Implementation Specialist will both get an email sent to them to approve this.

Once approved, it will be launched automatically and employees can start using their AD account to login to their Reward Gateway program.

Further Reading

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/add-a-token-signing-certificate