SSO implementation

To perform Single Sign On / Authentication with your SaaS website, Frill will go through the following process:

1. Turning on SSO will disable all Frill logins to your Frill account, clicking Login / Signup on your Frill site will redirect the user to a page on your website
2. On your website the user will need to login or sign up
3. Your website will generate a unique Frill User Token (details below) to identify the user
4. Your website will redirect the user back to Frill, sending the Frill User Token 
5. On Frill the user will be logged in and identified by the information passed in the token

Note: When Frill redirects to your website it will sent a query param called redirect that contains a URL. You must redirect back to this URL (for step 4 above)

Note about security

The SSO data is passed as an encoded token, know as a JWT (JSON Web Token) in the URL - the token is an alphanumeric string about 150 characters long. The token is signed using a special key (Frill SSO Key) that is unique to each company and only the company administrators have access to. The data passed in the token is email, id , avatar and name - no passwords are passed, encoded or otherwise. The token is then decoded by the Frill servers and the signature is checked to verify the token was signed by the  Frill SSO Key associated with the account. If the token was not signed with the correct key the SSO login will fail.

Let's get started...

1. Install JWT library

2. Create token: 

use \Firebase\JWT\JWT;

$frillSSOKey = 'FILL_SSO_KEY';
$userData = [
 'email' => $user['email'],
 'id' => $user['id'],
 'name' => $user['name'],
];
$frillUserToken = JWT::encode($userData, $frillSSOKey, 'HS256');

Node code example

1. Install JWT library

npm install --save jsonwebtoken

2. Create token:

var jwt = require('jsonwebtoken');
var FrillSSOKey = 'FILL_SSO_KEY';
var userData = { 
  email: user.email,
  id: user.id,
  name: user.name,
};
var frillUserToken = jwt.sign(userData, FrillSSOKey, {algorithm: 'HS256'});

Python code example

First, install the  PyJWT library using the packaging tool of your choice.

<code>pip install PyJWT

Then generate JWTs as follows:

def generate_frill_jwt(user_id, email, name, frill_sso_key):     
    payload = {         
	'id': str(user_id),         
	'email': email,         
	'name': name,     
    }     
return jwt.encode(payload, frill_sso_key.encode(), algorithm='HS256')
	

.NET code example

var frillSecret = "FILL_SSO_KEY";
var tokenHandler = new JwtSecurityTokenHandler();
var claims = new List<Claim> {
  new Claim("email", email),
  new Claim("id", userId),
  new Claim("name", fullName),
};
var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(frillSecret));
var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
var date = DateTime.UtcNow;
var expired = date.AddDays(7);
var token = new JwtSecurityToken(
  claims: claims,
  expires: expired,
  signingCredentials: creds
);
return tokenHandler.WriteToken(token);
		

Ruby on Rails code example

1. Add gem 'jwt' to Gemfile.

2. Add following to  user.rb:

def frill_user_token
  payload = { id: id, email: email, name: name }
  hmac_secret = ENV['FRILL_SSO_KEY']
  JWT.encode payload, hmac_secret, 'HS256'
end

Java code example

1. Install JWT library
See guide here: https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt/0.9.1

2. Create token:

import java.util.HashMap;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.Jwts; 

public class FrillTokenGenerator {
    private static final String FrillSSOKey = "FILL_SSO_KEY";
    
    public static String createToken(User user) throws Exception {
        HashMap<String, Object> userData = new HashMap<String, Object>();
        userData.put("email", user.email);
        userData.put("id", user.id);
        userData.put("name", user.name);
        String frillUserToken = Jwts.builder()
            .setClaims(userData)
            .signWith(SignatureAlgorithm.HS256, FrillSSOKey.getBytes("UTF-8"))
            .compact();
        return frillUserToken;
    }
}

2. Redirect back to Frill with the user token

Once you’ve created the Frill User Token you need to redirect the user back to your frill domain passing the token as the ssoToken query string parameter. Eg:

YOURDOMAIN.frill.co/?ssoToken=FRILL_USER_TOKEN

Note: when Frill directs the user to your site we will pass the redirect url as a parameter redirect, use this parameter to determine where to redirect the user back to.

PHP code example

$ssoRedirect = $_REQUEST['redirect'];
$url = $ssoRedirect.'?ssoToken='.$frillUserToken; // $frillUserToken from code above
header('Location: '.$url);
die;