Procédure de Single Sign On Particeep (SSO)

Nous utilisons le principe des Macaroons pour gérer notre connection SSO

Macaroon : définition

Comme les Cookies, les Macaroons (macarons en français) sont des tokens qui portent l’identité de l’utilisateur. Leur principaux avantages sont :

Délégation : vous pouvez déléguer un macaron à une autre entité. Au passage vous pouvez restreindre les droits associés au token.
Règles intégrées : un macaron embarque ses propres règles de validation. On peut facilement ajouter une contrainte a un macaron mais il est impossible d’en retirer une sans casser la validation cryptographique.
Validation simple : un macaron peut être validé très facilement sans faire appel a un serveur distant.

Ces avantages rendent les macarons très efficaces pour une authentification décentralisée : une fois le token créé n’importe quel système peut le vérifier grâce a un secret partagé. L’absence de serveur centrale élimine le Single Point Of Failure de certains systèmes de SSO.

Le nom « macaroon » rend les recherche google un peu « compliqué », on vous conseille de lire les liens de la section référence pour vous familiariser avec les macarons.

Il existe des implémentations dans tous les languages majeurs (C, Java, Python, Go, Php, etc…)

Protocole Particeep

Concept général

Pour passer d’une application à l’autre on va associer un token macaron a la requête. L’application qui reçoit ce token peut le décrypter à l’aide d’un secret partager et connecter l’utilisateur automatiquement.

Le processus est le même dans les 2 sens :

du backoffice et interfaces utilisateurs Particeep vers une application externe
d’une application externe vers le backoffice Particeep

Le SSO Particeep ne permet pas de créer un utilisateur : l’utilisateur doit être créé au préalable sur la plateforme Particeep.

Format du Token

Le token possède 2 parties distinctes.

Un identifiant

L’identifiant est une String qui encode des paramètres permettant d’identifier l’utilisateur. Il est de la forme suivante :

token_name=$token_name:email=$email:user_id=$user_id

token_name : est une variable d’environnement. Elle prend les valeurs suivantes

Environnement de test : Particeep_M_Token_Test
Environnement de production : Particeep_M_Token

email : l’email dont l’utilisateur se sert pour se connecter sur la plateforme Particeep

user_id : l’id du user sur la plateforme Particeep. Ce paramètre est optionnel.

Examples :

Dans l’environnement de test pour le user admin@particeep.com qui a l’id 6f92033a-5efe-46ba-a442-dc8abdddee50 vous pouvez construire les identifiants suivant

token_name=Particeep_M_Token_Test:email=admin@particeep.com:user_id= 6f92033a-5efe-46ba-a442-dc8abdddee50

token_name=Particeep_M_Token_Test:email=admin@particeep.com

Des caveats

Les caveats sont les règles de validation du token.

On applique les règles suivantes comme des first_party_caveat :

ip : contient l’ip du user (exemple: "ip = 127.0.0.1")
browser : contient le user-agent du browser actuel de l’utilisateur (exemple: "browser = Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36")
time < yyyy-MM-ddThh:mm : indique la durée d’expiration du token. Les applications Particeep crée des tokens valides 24 heures (exemple : "time < 2042-01-01T00:00")
authorities : Les droits de l'utilisateur ainsi que sa clé d'API, sous le format suivant :

Pour un CGP : "PARTNER_$api_key"
Pour un admin ou sous admin : "ADMIN_$api_key"
Pour un utilisateur classique : "$api_key"

Quand vous recevez un token vous devez vérifier ces règles.

Quand vous créez un token vous devez enregistrer ces règles sur le token.

Enfin le token est signé avec votre secret d’api.

On vous recommande fortement d’utiliser une implementation officielle des macarons pour créer ou lire un token. La documentation de l’implémentation vous indiquera comment ajouter et vérifier des caveats. Voici un exemple en Scala/Java utilisant l'implémentation : https://github.com/nitram509/jmacaroons


val location   = "http://next-le.particeep.com"
val secretKey  = "s16FRvEnAb9PsVMjFtfo`^b|V~"
val apiKey     = "SLYfJWNymW97qFq6PWfUX6vVkcd5kYpHdZbOTii5"
val identifier = "token_name=Particeep_M_Token_Test:email=admin@particeep.com:user_id=12345"

new MacaroonsBuilder(location, secretKey, identifier)
  .add_first_party_caveat(s"ip = 127.0.0.1")
  .add_first_party_caveat(s"browser = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36")
  .add_first_party_caveat(s"authorities = $api_key")
  .add_first_party_caveat(date)
  .getMacaroon()

Transport du Token

Dans le cadre d’un SSO avec des domaines DNS différents, le cas d’usage est une redirection de type GET entre les 2 applications. Le token est donc passé en paramètre d’url

on recherche un paramètre nommé $token_name

C’est le même paramètre que dans l’identifiant. Il prend les valeurs suivantes

environnement de test : Particeep_M_Token_Test
environnement de production : Particeep_M_Token

L’url cible doit être une page de l’application et non une page satellite.

Une page de l’application backoffice a une url de cette forme

environnement de test :[urlapp]/${api_key}/.*
environnement de production : [urlapp]/${api_key}/.*

Toutes les autres pages sont des pages satellites.

Exemple

https://url/app/0554465d-b7e0-4d36-a0a4-8d9a06f28b59?Particeep_M_Token_Test=MDAyNWxvY2F0aW9uIENsaWVudF9BcHBsaWNhdGlvbl9OYW1lCjAwN2JpZGVudGlmaWVyIHRva2VuX25hbWU9UGFydGljZWVwX01fVG9rZW5fVGVzdDplbWFpbD1tYWNhcm9vbkBwYXJ0aWNlZXAuY29tOnVzZXJfaWQ9MWRkNWE4ZTMtMDk0ZS00YzYyLTgyNzgtZWZkNmI4ZTNhZWFlCjAwMTljaWQgaXAgPSAxOTIuMTY4LjAuMQowMDhjY2lkIGJyb3dzZXIgPSBNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMF8xM182KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvNzQuMC4zNzI5LjE2OSBTYWZhcmkvNTM3LjM2CjAwNDNjaWQgYXV0aG9yaXRpZXMgPSBQQVJUTkVSXzA1NTQ0NjVkLWI3ZTAtNGQzNi1hMGE0LThkOWEwNmYyOGI1OQowMDFlY2lkIHRpbWUgPCAyMDE5LTctM1QwMDowMAowMDJmc2lnbmF0dXJlIMWLjH0p3WW1mhufZpieQoRa1HemMbnKjo6Eu6NOtT2uCg