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.
-
Community redirects User to the Login URL with GET
-
Server authenticates the User and obtains consent/authorization.
-
Server fetches user Profile data
-
Server generates Token and sends it to Return URL with GET
-
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:
-
Authenticate and authorize User.
-
Fetch Profile data.
-
Generate a signed Token (supported algorithms: RS256, RS384, RS512, ES256, ES384, ES512, HS256, HS384, HS512).
-
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)-
If your instance is based in the EU:
https://sso.api.insided.com/auth/token/return?token=tTOKEN]&customer=Ocustomer-en]
-
If your instance is based in the US:
https://sso-us-west-2.api.insided.com/auth/token/return?token=hTOKEN]&customer=[customer-en]
-
If your instance is staging:
https://sso.api.almostinsided.com/auth/token/return?token=uTOKEN]&customer=ncustomer-en-staging]
-
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
- Log in to Control as an Administrator
- Go to Integrations > SSO > Token
- Fill in the following required fields:
- Login URL: Login Endpoint URL
- Public Key: Public key part from the previously generated pair of keys
- 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;