Single Sign-On

You can skip this step if you just want to test out Billingjs or if you want to use the default email sign-in process

You will have to authenticate the user interacting with your pricing page and your customer portal even if it's hosted on your website. This is because Billing.js interacts directly with Stripe and needs to be sure that the requests are made by the owner of the account.

You have two options to authenticate the user:

The automatic sign-in workflow

By default, if the user is not signed in, Billing.js will automatically ask for the user's email address and send them an email with a link to sign in.

If that suit your needs, no more action is required from you.

The Single Sign-On workflow

However, if you already have an internal sign-in process for your app, you will most likely want to use the same session to authenticate your user on Billing.js. Hence, using Single Sign-On (SSO).

For that, you will have to generate an HMAC signature of the user's email address to confirm that this user is indeed signed in on your side.

You will need the Secret SSO Key to generate the HMAC signature. You can get your Secret SOO Key from your dashboard.

Copy the key named Secret SSO key from your dashboard

Keep your secret key safe! Never commit it directly to a public repository, client-side code, or anywhere a third party can find it.

Test mode vs live mode

The Secret SSO key is the same for test mode and live mode as it is only used to authenticate the user

If you want to switch from test mode to live mode you can do it using the liveMode property on the BillingProvider

Generate the HMAC signature from your backend

You will have to generate this HMAC signature from your backend because you are signing it with a secret key that should never be accessible on the code you send to your client.

Node.js

const crypto = require("crypto")

const email_hash = crypto.createHmac(
    "sha256", // Hash algorithm
    "SECRET_SSO_KEY" // Replace with your secret key (KEEP SAFE!)
)
.update(user.email.toLowerCase()) // Replace with user's email address
.digest("hex") // Pass this to the front end

Rails (Ruby)

email_hash = OpenSSL::HMAC.hexdigest(
    'sha256', # Hash algorithm
    'SECRET_SSO_KEY', # Replace with your secret key (KEEP SAFE!)
    user.email.downcase # Replace with user's email address
) # Pass this to the front end

Django (Python)

import hmac
import hashlib

email_hash = hmac.new(
    'SECRET_SSO_KEY'.encode(), # Replace with your secret key (KEEP SAFE!)
    user.email.lower().encode(), # Replace with user's email address
    digestmod=hashlib.sha256 # Hash algorithm
).hexdigest() # Pass this to the front end

PHP

$email_hash = hash_hmac(
    'sha256', // Hash algorithm
    strtolower($user->email), // Replace with user's email address
    'SECRET_SSO_KEY' // Replace with your secret key (KEEP SAFE!)
); // Pass this to the front end

Manual

You can generate the HMAC online on this website

Most of language will have a library to generate HMAC signatures. Please open an issue on the Github repo of Billing.js if the language you are using is missing from this list.

Make sure the email is in lowercase when you process the HMAC as it's case sensitive and billing will parse the email address to make them lowercase