Single Sign On (SSO)

Note: Single Sign-On (SSO) is an advanced feature that must be implemented by a developer.

The Single Sign-On (SSO) feature cuts down friction by allowing your users to seamlessly switch between your application and the Tapfiliate dashboard.
Authentication is handled on your end meaning that users don’t have to create separate accounts and don’t need to login separately to get access to your affiliate program. Tapfiliate’s SSO feature is a fixed part of the Enterprise plan.

The single sign-on feature uses a technology called JSON Web Token (JWT) which ensures safe and secure exchange of user (authentication) data.

About JWT

A JWT is divided into 3 chunks delimited by a . (period):

1: The JWT header

The header should be a Base64Url encoded JSON string:

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

Since Tapfiliate only supports the HMAC SHA256 (HS256) hashing algorithm, this part of the JWT token is fixed.

2: The JWT Claims set (Payload)

There are several required attributes that we need in every JWT payload. These attributes include iat, jti, email, firstname & lastname - see the table below for further details.

Again, these required user attributes should be sent as a Base64Url encoded JSON string

Note: The values for email, first name, & last name should NOT be empty.

3: The JSON web signature (JWS)

The last chunk of the request is the encrypted signature. You don’t need to worry too much about this, but basically it takes all the information above, along with a shared secret and generates an encrypted string out of all of it. Then, per JWT standards, a chunk of that encrypted string is taken (known as a checksum), and that is the JWS signature.

The signature can be created in the following way:

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

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

Configuring SSO

You can enabled and configure your SSO settings on the SSO configuration page.
This page has the following settings:

SSO Modes

Adding new SSO users to programs is easy and convenient for both the user and the publisher. At Tapfiliate we have three different SSO modes to make it even more convenient for our users:

SSO Only

If you are planning on using only SSO to onboard affiliates, than this is the right mode for you. SSO only mode will ensure that all unauthenticated requests against the affiliate portal will be redirected to a login url of your choice. All signup and login pages on Tapfiliate will be disabled for your account.

SSO only authentication process:

1. Unauthenticated user (someone who hasn’t yet logged in) navigates to your Tapfiliate URL (for example, https://yourdomain.tapfiliate.com/dashboard/).

2. The tapfiliate SSO mechanism recognizes that SSO is enabled and that the user is not yet authenticated.

3. The user then gets redirected to the remote login URL configured in your SSO settings (for example, https://yourdomain.com/tapfiliate/sso/).

4. Your own login script authenticates the user on your side

5. Your script builds a JWT request that contains relevant user data.

6. The customer is then redirected to the Tapfiliate endpoint at https://yourdomain.tapfiliate.com/sso/jwt/access/

7. Tapfiliate then gets the user detail from the JWT payload and grants the user a session.

Mixed: Conditional Redirect

If you are planning on recruiting other affiliates, next to the users you are onboarding through SSO, you might choose the conditional redirect method. In this mode your program’s signup pages and the affiliate login page will be shown as usual. When an SSO user tries to login, Tapfiliate will detect that the user is an SSO user and will redirect them to your chosen login url. The downside of this method is that this theoretically ‘leaks’ data, seeing as it would be evident from the redirect, that the user exists on our platform and thus exists in your database.

Conditional redirect authentication process:

1. Unauthenticated user (someone who hasn’t yet logged in) navigates to your Tapfiliate URL (for example, https://yourdomain.tapfiliate.com/dashboard/).

2. The user gets redirected to our login form.

3. The submitted email address will be used to detect whether this is an SSO user or a ‘regular’ user. SSO users will be redirected to the remote login URL configured in your SSO settings (for example, https://yourdomain.com/tapfiliate/sso).

4. Your own login script authenticates the user on your side

5. Your script builds a JWT request that contains relevant user data.

6. The customer is then redirected to the Tapfiliate endpoint at https://yourdomain.tapfiliate.com/sso/jwt/access/

7. Tapfiliate then gets the user detail from the JWT payload and grants the user a session.

Mixed: Ignore Form Logins

In this mode, form logins on Tapfiliate by SSO users are simply ignored and an “unknown email or password” type error is returned

Ignore form logins authentication process:
In this mode, SSO users can only get authenticated by being sent by you to the JWT endpoint.

Authenticating users

Now that you know how to create the JWT payload, it is time to authenticate your users! You can do this by sending them to the SSO endpoint and including the JWT in the query string:

   https://__yourdomain__.tapfiliate.com/sso/jwt/access/?jwt=[[[[jwt-payload-here]]]]

The return_to URL

When a user is redirected to your login script by Tapfiliate, a return_to parameter will be passed within the URL, as well. This parameter contains the page that Tapfiliate will return the user after the authentication has been approved.

1. User goes to https://yourdomain.tapfiliate.com/p/programs.
   
2. The fact that the user hasn’t been authenticated is recognized by Tapfiliate (assuming you chose SSO only mode).
   
3. Tapfiliate then redirects the user to: https://yourdomain.com/tapfiliate/sso/?return_to=/p/programs/
   
   

What your script needs to do is take the return_to value from the invoked URL and pass it back to Tapfiliate in the return_to query parameter, when submitting the JWT token. The return_to parameter is a relative URL.

Error handling

In the scenario that Tapfiliate encounters an error while processing a JWT login request it will report a message that explains what the issue is. If you have an error URL configured for your JWT integration, it will redirect to that and pass a ‘message’ parameter.

For example, the message “?message=Wrong+username+or+password” in the URL would indicate that:

• the email address indicated in the JWT token is invalid
  
• firstname or lastname is not present in the JWT token
  
• there are empty values for firstname or lastname in the JWT token
  
  

Logging out users
Users can be logged out by sending them to https://yourdomain.tapfiliate.com/sso/jwt/logout/ . Again, a return_to parameter can be passed to determine where the user is redirected after they are logged out of Tapfiliate.