Token SSO setup guide

What is Token SSO?

Token is a JWT-based authentication mechanism that provides simple and secure way to integrate any Service (Identity Provider) with Community (Service Provider)

Token SSO Flow Representation

In order to understand how the Token SSO process integrates into the overall Community SSO architecture (i.e. Steps #1-3 in the diagram below) please see Single Sign-on (SSO): Getting Started.

1. Community redirects User to the Login URL with GET 

2. Server authenticates the User and obtains consent/authorization.

3. Server fetches user Profile data

4. Server generates Token and sends it to Return URL with GET 

5. Community receives Token, decodes and validates it by using Public Key and extracts Profile data

After retrieving the Profile data, Community starts #Step 3 of Community Single Sign-on.

How to Configure Token SSO on inSided

Server and Token generation

• Generate pair of keys for Token signing (requires shell and openssl).
• Check out the example below:

#!/usr/bin/env

openssl genrsa -out jwtRS256.key 2048
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Set up a web Server with Login Endpoint that performs the following:

1. Authenticate and authorize User.

2. Fetch Profile data.

3. Generate a signed Token (supported algorithms: RS256, RS384, RS512, ES256, ES384, ES512, HS256, HS384, HS512).

4. Send the Request with GET by using Return URL in this format:
   (where customer-en should be replaced with the id of your community, which you can find in the control URL)

   1. If your instance is based in the EU:

      https://sso.api.insided.com/auth/token/return?token=[TOKEN]&customer=[customer-en]

       

   2. If your instance is based in the US: 

      https://sso-us-west-2.api.insided.com/auth/token/return?token=[TOKEN]&customer=[customer-en]

       

   3. If your instance is staging: 

      https://sso.api.almostinsided.com/auth/token/return?token=[TOKEN]&customer=[customer-en-staging]

       

   4. If your instance is in sandbox, please use EU/US URL and adding [customer-en-sandbox] to the end of the URL and not Staging.

Community (inSided) configuration

1. Log in to Control as an Administrator
2. Go to Integrations > SSO > Token
3. Fill in the following required fields:
   • Login URL: Login Endpoint URL
   • Public Key: Public key part from the previously generated pair of keys
4. Press Install.

Once you’ve installed your configuration, we recommend using the built-in inSided SSO testing tool before you enable SSO for end users, to make sure everything is working as expected.

//token.php

<?php

//please install the package first https://github.com/firebase/php-jwt
use FirebaseJWTJWT;

//Read previously generated pair of keys
$privateKey = file_get_contents('jwtRS256.key');
//public key will be also needed as Public Key later in the Control Token configuration page
$publicKey = file_get_contents('jwtRS256.key.pub');

$payload = array(
    'id' => 'VGqczRfTVaSm',
    "username" => "john.doe",
    'email' => 'john@doe.com',
    "avatar" => "https://upload.wikimedia.org/wikipedia/commons/3/30/Rubik_cube.png",
    "customRoles" => "12,13"
);

//Get token by signing it with private key
$token = JWT::encode($payload, $privateKey, 'RS256');
echo "Token: $token" . PHP_EOL;

//Decode it back for  demo purposes
$payload = (array)JWT::decode($token, $publicKey, array('RS256'));
echo "Decoded payload: " . json_encode($payload) . PHP_EOL;