SSO: Single Sign-on

This feature enables advocates to signup and login to the Duel portal through their brand account eCommerce credentials.

Terminology
Technical Requirements 
Advocate Journey Recommendations
Example Endpoint

Single Sign-On (SSO) allows advocates to access the Duel portal with their ecommerce credentials. Instead of having to remember separate usernames and passwords for each login, SSO simplifies the process by providing a single authentication point. This can improve security and user experience. 

Terminology

• Portal: The Duel hosted portal on custom sub-domain.
• Estore: The brand estore/website connected to the portal.
• Entrypoint: A dedicated estore URL which serves as the persistent login area for connecting to the portal. Members are also directed here to reauthenticate on session expiry. (log out, expired session, public link)
• Endpoint: Estore endpoint for implementing SSO login and redirecting members to portal via single click.
• Advocate: User of a Duel powered programme

Advocate Journey Recommendations

The brand needs to create an Entrypoint where they pass along the program link the advocate is trying to access. An Entrypoint is a page with an exposed SSO link for logged in users.

Duel recommends that these Entrypoints are constructed as program overview pages for the various programs. For example:

1. Open Programme - https://brand.com/rewardsclub
2. Application Programme - https://brand.com/ambassadors

These pages have an authenticated (logged-in) version and non-authenticated (logged-out) version.

Brands can handle the ‘authentication’ event in any way they wish, either redirecting users back to this page after authentication or redirecting them directly to their SSO link and into the portal.

Redirection of Advocates 

If a member of the program attempts to access a specific area of the Duel portal, they will be redirected first to the correct entrypoint by Duel (customer will land on customer entrypoint). The brand should then automatically redirect them along the following path for the following conditions:

If Unauthenticated:

1. Automatic Redirect 1: Towards an authentication area to authenticate.
2. Automatic Redirect 2: Back to the Entrypoint.
3. Automatic Redirect 3: Via the SSO link to the URL they initially tried to access.

If Authenticated:

1. Automatic Redirect 1: Via the SSO link to the URL they initially tried to access.

Examples:

1. The user might click on ‘enter competition now’ and be redirected from that Duel ‘Competition’ page back to the Entrypoint to complete authentication before being redirected back towards the ‘Competition’ page.
2. The user might click ‘claim my points’ on the Checkout Page to enter the portal. They will then be redirected to the Entrypoint to be redirected via the SSO link into the portal.

Alternative Advocate Journey

The CTA could also be displayed within a logged in environment by using an area within 'my account' area as an Entrypoint as below.

1. Member is logged in on Brand Estore
2. Call to action link is displayed for Duel portal access (Required on Entrypoint)
3. On following the link, member is redirected to the portal with a new session (and a new account created with passed id/email/name if no prior existing account with same id)

Technical Requirements

The two following steps are required to set up SSO with Duel. 

1. Setup endpoint on the Estore backend (snippets & instructions provided below)
2. Setup the Entrypoint page with a call to action link pointing to your endpoint.

Overview

1. Request the necessary information from Duel to start the authentication flow by sending your slug and group ID (if applicable).
   1. You can your slug by following these instructions
   2. Find your group ID by following these instructions.
2. Duel responds with the authentication endpoint URL info and a nonce (which makes sure the link can only be used once).
3. Encode (base64) the most basic user information (id, email, name) required for signup/login and the code obtained in step 2 along with the public Task ID (if present).
   1. The user ID is very important, as it ensures that the connection persists even when users change their email.
4. Sign this encoded data with a secret key that is provided by Duel - it uniquely identifies you and makes us trust you. Important: Keep this key secret.
5. Create an authentication link based on the endpoint info obtained from step 2, the encoded data from step 3 and the signature from step 4.
6. Redirect the browser with the created authentication link to the Duel portal.

Example Endpoint (Pseudo-code)

(nonce, endpoint) =
await fetch(‘<https://api.duel.me/sso/{SLUG}/{GROUP_ID}’>)

payload = base64(
‘nonce={nonce}&id={USER_ID}&email={USER_EMAIL}&name={USER_NAME}&task={TASK_ID}’
)

signature = hmac(DUEL_APP_SECRET, payload, ‘sha256’).hexdigest()

redirect_link = endpoint + ‘?payload={payload}&sig={signature}’

redirect(redirect_link)

DUEL_APP_SECRET is sensitive and should be stored and retrieved in the same manner as environment variables or database credentials.

USER_ID parameter should be an immutable customer ID read from the estore session.

USER_EMAIL and USER_NAME parameters should be read from the estore session.

TASK_ID (optional) Read from URL search parameter ‘duel_task’ to forward member to a specific task after login. i.e. ENTRYPOINT?duel_task=a1

GROUP_ID (optional) If an account is being created the member will be placed in this group. If not specified created accounts will be placed in the default group.