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 code snippet provided by Annoto or using any other 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.

(Note : Please refer to Using The API for instructions on how to get access to the

annotoAPI).

1. Annoto analyzes the payload, grants the user permission, and will show his details in the widget.

2. By default, Annoto will not save the user login information. The annotoAPI.auth(token) should be called at page refresh.

3. Your client side JS can use the annotoAPI.logout() method to logout the user.

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

Once the user has been authenticated on your side, you must create a payload containing the required information about the user.

It should take the user information below and encode JWT token using the provided function and the SECRET. The JWT payload should contain:

• If email is not provided, email notifications for users won’t work.

• If you prefer using your own JWT library instead of the code provided by Annoto. The JWT token MUST be signed using HS256 algorithm.

JWT’s full specification is available at https://tools.ietf.org/html/rfc7519​

PHP Example

<?php require_once('./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 );

$key = "4e54273d5d17859d464cb9bf";

$jwt = JWT::encode($payload, $key); ?>

Source files for JWT:encode:

​https://github.com/Annoto/jwt-php​