# 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

![](/files/-MMkKbEoL_flcPPeBB3J)

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)***](/developers/widget/getting-started.md#using-the-api) method to authenticate the user.

{% hint style="info" %}
Annoto will not save the user login session. The `annotoAPI.auth(token)` should be called at each page load.
{% endhint %}

## Setup

What you will get from Annoto:

* Your clientID
* A unique secret that will be used to sign JWT tokens.

{% hint style="danger" %}
**THE SECRET MUST BE KEPT CONFIDENTIAL ON YOUR SERVERS.**
{% endhint %}

## JWT Anatomy

JWT payload should contain the required user information, and be encoded (signed) using the provided SECRET.

{% hint style="success" %}
The JWT token MUST be signed using HS256 algorithm.
{% endhint %}

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        | <p>scope indicating permissions of the user:</p><ul><li><em>‘user’</em> - regular user (default)</li><li><em>‘moderator’</em> - can moderate threads.</li><li><em>‘super-mod’</em> - can moderate threads and have access to the Annoto dashboard.</li></ul> | No        |
| *aud*      | url           | audience of the token (<http://annoto.net>)                                                                                                                                                                                                                  | No        |

{% hint style="warning" %}
If email is not provided, email notifications for users won’t work.
{% endhint %}

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

## JWT Libraries

There are libraries available for virtually any programming language.

{% hint style="success" %}
A good source is: <https://jwt.io/libraries>
{% endhint %}

## PHP Example

```php
<?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);
?>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.annoto.net/developers/integrations/sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.