SSO (Single Sign On)

Introduction
Single Sign-On (SSO) is an authentication mechanism that allows users to access several applications with only one set of login credentials.
By enabling SSO for your Annoto widget, you become responsible for the authentication of your users: they get authenticated through your own login portal and can use Annoto services freely.
Process
1.An unauthenticated user requests access to your site (post login details to your server).
2.Your server authenticates the user, The user gets authenticated using your own authentication and authorization process.
3.If the user access is granted, You create a secured JWT payload that contains information about the user, using any standard library.
4.The JWT token should be part of the login post answer (or some other query as you see fit).
5.Your client side JS code should call the annotoAPI.auth(token) method to authenticate the user.
Annoto will not save the user login session. The annotoAPI.auth(token) should be called at each page load.
Setup
What you will get from Annoto:
Your clientID
A unique secret that will be used to sign JWT tokens.
THE SECRET MUST BE KEPT CONFIDENTIAL ON YOUR SERVERS.
JWT Anatomy
JWT payload should contain the required user information, and be encoded (signed) using the provided SECRET.
The JWT token MUST be signed using HS256 algorithm.
The JWT payload should contain:
Property
Type
Description
Mandatory
iss
string
issuer of the token (clientID provided by Annoto)
Yes
exp
number
expiration timestamp in seconds. Indicating when the user login session expires.
Yes
jti
number/string
unique identifier for the JWT. Equal to the unique identifier of your user.
Yes
name
string
visible user name
Yes
email
string
User email account
No
photoUrl
url
publicly accessible url to user photo
No
scope
string
scope indicating permissions of the user:
‘user’ - regular user (default)
‘moderator’ - can moderate threads.
‘super-mod’ - can moderate threads and have access to the Annoto dashboard.
No
aud
url
audience of the token (http://annoto.net)
No
If email is not provided, email notifications for users won’t work.
JWT’s full specification is available at https://tools.ietf.org/html/rfc7519​
​
JWT Libraries
There are libraries available for virtually any programming language.
A good source is: https://jwt.io/libraries​
​
PHP Example
<?php
 require_once('./JWT.php'); // https://github.com/Annoto/jwt-php
​
$issuedAt = time();
$expire = $issuedAt + 60*20; // Adding 20 minutes
$payload= array(
  "jti" => 1234,
  "name" => "Hen Eytan",
  "photoUrl" => "https://images.pexels.com/photos/101584/pexels-photo-101584.jpeg",
  "iss" => "zRCIsImlzcyI6Imh0dHA6XC9cL3d3dy5vcGVudS",
  "exp" => $expire
);
$secret = "4e54273d5d17859d464cb9bf";
​
$jwtToken = JWT::encode($payload, $secret);
?>

Last modified 20d ago

Property	Type	Description	Mandatory
iss	string	issuer of the token (clientID provided by Annoto)	Yes
exp	number	expiration timestamp in seconds. Indicating when the user login session expires.	Yes
jti	number/string	unique identifier for the JWT. Equal to the unique identifier of your user.	Yes
name	string	visible user name	Yes
email	string	User email account	No
photoUrl	url	publicly accessible url to user photo	No
scope	string	scope indicating permissions of the user: ‘user’ - regular user (default) ‘moderator’ - can moderate threads. ‘super-mod’ - can moderate threads and have access to the Annoto dashboard.	No
aud	url	audience of the token (http://annoto.net)	No