Partner SSO

Caution

Note that this is not for integrating enterprise SSO providers such as Okta or Azure AD for partner or merchant accounts, if you want to enable enterprise SSO login options please contact support.

These are instructions on how to generate Single Sign-On tokens on your server. These token can be used to authenticate your users into our merchant dashboard for your organisations.

1. Generate your Partner SSO Key

You can do this by logging into your partner dashboard and under Settings > Single Sign-On (SSO) for Organisations and generate a key. Store this key in a secure environment variable on your server. Do not expose this key in any frontend interface.

2. Get your Partner ID

From your partner dashboard grab the first ID in the URL. For example:

https://dashboard.chargebackstop.com/partners/ptnr_T1Ng7EgYrY7uaKMgPsASE/settings

In this case ptnr_T1Ng7EgYrY7uaKMgPsASE would be your Partner ID.

3. Generate your SSO Token

You can do this using all major programming languages, see below for common examples:

1. Install a JWT Library

   We use JSON Web Tokens to securely authenticate your users. First, install the appropriate JWT library for your server.

   Python

   pip install PyJWT

   Node.js

   npm install --save jsonwebtoken

   C#

   dotnet add package System.IdentityModel.Tokens.Jwt

   Go

   go get github.com/golang-jwt/jwt

   Java

   implementation 'com.auth0:java-jwt:4.4.0'

   Ruby

   sudo gem install jwt

2. Generate Tokens on your Server

   These tokens must be used within 15 minutes of issuance (UTC timezone)

   Caution

   Make sure to thoroughly read through the appropriate documentation for your library and ensure the right security methods are used such as setting appropriate expiries on JWT tokens.

   Python

   import jwt
   from datetime import datetime, timezone
   
   private_key = 'YOUR_PRIVATE_PARTNER_SSO_KEY'
   
   def create_chargebackstop_sso_token(email):
     user_data = {
         "iat": datetime.now(tz=timezone.utc),
         "user_email": email,
     }
     return jwt.encode(user_data, private_key, algorithm='HS256')

   Node.js

   const jwt = require('jsonwebtoken');
   
   const privateKey = 'YOUR_PRIVATE_PARTNER_SSO_KEY';
   
   function createChargebackstopSsoToken(email) {
     const userData = {
       iat: Math.floor(Date.now() / 1000),
       user_email: email,
     };
   
     return jwt.sign(userData, privateKey, { algorithm: 'HS256' });
   }

   C#

   using System;
   using System.IdentityModel.Tokens.Jwt;
   using System.Text;
   using Microsoft.IdentityModel.Tokens;
   using System.Security.Claims;
   
   public class JwtTokenGenerator
   {
       private const string PrivateKey = "YOUR_PRIVATE_PARTNER_SSO_KEY";
   
       public static string CreateChargebackstopSsoToken(string email)
       {
           var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(PrivateKey));
           var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
   
           var claims = new[]
           {
               new Claim("user_email", email),
               new Claim(JwtRegisteredClaimNames.Iat,
                   new DateTimeOffset(DateTime.UtcNow).ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer64)
           };
   
           var token = new JwtSecurityToken(
               claims: claims,
               signingCredentials: credentials);
   
           return new JwtSecurityTokenHandler().WriteToken(token);
       }
   }

   Go

   package main
   
   import (
     "fmt"
     "time"
   
     "github.com/golang-jwt/jwt"
   )
   
   var privateKey = []byte("YOUR_PRIVATE_PARTNER_SSO_KEY")
   
   func createChargebackstopSsoToken(email string) (string, error) {
     token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
       "iat":        time.Now().Unix(),
       "user_email": email,
     })
   
     tokenString, err := token.SignedString(privateKey)
     if err != nil {
       return "", err
     }
   
     return tokenString, nil
   }

   Java

   import com.auth0.jwt.JWT;
   import com.auth0.jwt.algorithms.Algorithm;
   
   import java.time.Instant;
   import java.util.Date;
   
   public class JwtGenerator {
       private static final String PRIVATE_KEY = "YOUR_PRIVATE_PARTNER_SSO_KEY";
   
       public static String createChargebackstopSsoToken(String email) {
           Algorithm algorithm = Algorithm.HMAC256(PRIVATE_KEY);
   
           return JWT.create()
                   .withClaim("user_email", email)
                   .withIssuedAt(Date.from(Instant.now()))
                   .sign(algorithm);
       }
   }

   Ruby

   require 'jwt'
   
   PRIVATE_KEY = 'YOUR_PRIVATE_PARTNER_SSO_KEY'
   
   def create_chargebackstop_sso_token(email)
     payload = {
       iat: Time.now.to_i,
       user_email: email
     }
   
     JWT.encode(payload, PRIVATE_KEY, 'HS256')
   end

4. Redirect your user

Your user must already be a member of an organisation with your partner account. If the user is not a member the SSO will fail, and due to security implications you cannot SSO a user that is a member of an organisation outside of your partner account.

Tip

The token you generate must be used within 15 minutes of creation, so we recommend only creating these tokens when the user wants to be redirected rather than ahead of time

Your Base URL will be either https://dashboard.chargebackstop.com, or your own white label instance such https://chargebacks.example.com, make sure to redirect your customer to the right one.

Your Partner ID will be the ID we retrieved earlier such as ptnr_T1Ng7EgYrY7uaKMgPsASE

Your SSO Token will be the token we generated above. You need to generate this token each time.

Putting it all together

{Base URL}/auth/partner-organisation-sso?partner_id={Partner ID}&token={SSO Token}

For example

https://dashboard.chargebackstop.com/auth/partner-organisation-sso?partner_id=ptnr_T1Ng7xxxxx&token=eyJhbGciOiJIUzI1NiIsInR5cCIyyyyy

If you have any questions, please let our customer success team know and we'll do our best to help you.