Skip to main content

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.

zvFHEmtmhdXZFz935v3Tx_a6TKAghp0qknvdkx29jljaBU4EEf-Lo4k6-ZVqeJAJHl63NZdIX0eBkKWS9aeMyYqNPWWZ5kaStOPgk1svXRAELwKArV8QlweYsUFzKvZ6oZLCn_5j

  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 dataCommunity 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=tTOKEN]&customer=Ocustomer-en]

       

    2. If your instance is based in the US: 

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

       

    3. If your instance is staging: 

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

       

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

Recommendations:

  • We recommend to use asymmetric algorithm, e.g. RSA256. Check out the example at the bottom of the article (token.php).
  • Here’s a useful resource that makes life easier when you work with JWT https://jwt.io

 

Note: JWE (Encryption) is not supported on inSided.

 

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;

 

A question — how do I update the button to say something other than “Login with Token” ? Having a hard time finding it in Phrases.

 

Thanks!

 

 


Hi @MackenzieK! The phrase for “Login with Token” is not in the list of default phrases in Control, but it can be added using the following:

Module.               Key.

Common

common.sso.oauth.login.token


@Cristina do you have the phrases for the rest of the copy on that popup?

  • Login to the community
  • Social login

Thanks!


Hi @Onomatopoeia! Sure, here they are:  

  • Login to the community: 

    Common

    login.detail.title

  • Social login

    Common

    sso.title


Where do I see ‘Control URL’ in the backend?


Hi@VarshaAhir - if you’re referring to this part:

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)

...the control URL is simply the URL of your backend environment.  In that URL you’ll have an ID that looks something like ‘customer-en’.  For this community, for example, it’s ‘gainsight-us’.


@Kenneth R and Team, I just noticed that there is the ability to define an avatar as well as username in the payload. So we can anonymize usernames and avatar.

 

This could be exactly what I am needing 😁


Reply