Skip to main content

Single Sign On (SSO)

This article explains what Single Sign-On (SSO) is, why it’s useful, and how to technically configure and manage SSO for affiliates using Tapfiliate’s Enterprise features.

Gumrah avatar
Written by Gumrah
Updated over a week ago

  1. About JWT (JSON Web Token)

  2. Configuring SSO in Tapfiliate

  3. SSO Modes explained

  4. Example (SSO Only Mode)

  5. Error Handling

  6. Logging Out Users

What the Single Sign On (SSO) is and why to use it?

Single Sign-On (SSO) is a feature that simplifies how your affiliates access both your platform and Tapfiliate. With SSO, users only need one set of login credentials to move seamlessly between systems—no more juggling multiple passwords or repetitive logins.

This guide will explain the benefits of SSO and provide a step-by-step technical overview of how to set it up using Tapfiliate.

Note: Tapfiliate SSO is available exclusively on our Enterprise plan.

Why Use Tapfiliate SSO?

SSO improves the experience for both affiliates and businesses:

  • For affiliates: One login gives them access to everything. They don’t need to remember multiple passwords or fill out repeated registration forms.

  • For businesses: Simplifies affiliate management, reduces friction, and increases participation in your programs.

  • Professional and seamless experience: SSO makes your platform feel integrated and polished, improving engagement and retention.

How Tapfiliate SSO Works

Tapfiliate SSO uses a technology called JSON Web Token (JWT) to securely exchange user authentication data. Essentially:

  1. Users log in to your system.

  2. Your system generates a secure JWT with the user’s details.

  3. The user is redirected to Tapfiliate with the JWT.

  4. Tapfiliate verifies the token and grants the user access.

This ensures a smooth, secure, and seamless login experience without creating separate Tapfiliate accounts.

Please, note that a developer has to be involved in order to set this up.

Technical Implementation of Tapfiliate SSO

About JWT (JSON Web Token)

A JSON Web Token (JWT) is divided into three parts, separated by periods (.):

  • Header: Contains metadata about the token.

{
  "typ": "JWT",
  "alg": "HS256"
}

Tapfiliate supports only HMAC SHA256 (HS256).

  • Payload (Claims): Includes required user attributes:

Setting

Description

iat

The time the token was generated, this is used to help ensure that a given token gets used shortly after it’s generated. The value must be the number of seconds since UNIX epoch . Tapfiliate allows up to two minutes clock skew, so make sure to configure NNTP or similar on your servers.

jti

JSON Web Token ID. A unique id for the token, used by Tapfiliate to prevent token replay attacks.

email

Email of the user being signed in, used to uniquely identify the affiliate on Tapfiliate.

firstname

First name of this user.

lastname

The last name of the user.

  • Signature (JWS): Ensures the token is authentic.
    Created using:

HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    secret)

Tip: There are loads of great libraries that can help you create JWTs.

Configuring SSO in Tapfiliate

Go to the Settings > Single Sign on (SSO) tab in your Tapfiliate Enterprise account.

Key settings include:

Setting

Description

Error URL

Where users are redirected if authentication fails.

Program

Assign new SSO users to a program.

SSO Mode

Choose between SSO Only, Conditional Redirect, or Ignore Form Logins.

Login URL

Where unauthenticated users are redirected (your login form).

SSO Modes explained

1. SSO Only:

All users must use SSO. Standard Tapfiliate login pages are disabled.

2. Conditional Redirect:

Regular affiliates can use Tapfiliate login, SSO users are redirected to your login page.

3. Ignore Form Logins:

SSO users can only log in through your JWT endpoint; Tapfiliate form logins are ignored.

Example (SSO Only Mode)

  1. User visits the Tapfiliate dashboard.
    Tapfiliate detects the user isn’t authenticated.

  2. Redirect to your login URL.

  3. Your system authenticates the user and generates a JWT.

  4. Redirect user back to Tapfiliate:

https://yourdomain.tapfiliate.com/sso/jwt/access/?jwt=jwt-payload-here

  1. Tapfiliate grants access.

  2. The user (affiliate) is logged in to his Tapfiliate account.

Return_to URL: Preserve the page the user intended to visit and pass it as return_to in the JWT request.

Error Handling

If a JWT login fails, Tapfiliate redirects to your configured Error URL with a message parameter explaining the problem. Examples: missing firstname/lastname, invalid email, or empty values.

Logging Out Users

To log out, send users to:

https://yourdomain.tapfiliate.com/sso/jwt/logout/

Optionally, include a return_to parameter to redirect users after logout.

Did this answer your question?