Intégration SSO du module de RDV
ClicRDV met à votre disposition un système de SSO (Single Sign On) pour logguer vos clients sur le module de prise de RDV à partir de l'espace client de votre site internet.
Introduction au SSO
Note Cette rubrique présente un aperçu rapide de la connexion SSO, consultez également les rubriques suivantes pour approfondir le fonctionnement du SSO et les concepts associés.
1 Principe du SSO
L'espace client de votre site internet doit intégrer un cryptage des données relatives à l'identification de l'utilisateur. Ainsi, lors de l'ouverture du module de prise de rendez-vous, les données envoyées via l'url de connexion seront automatiquement décryptées et l'utilisateur connecté en fonction de la configuration utilisée.
2 L'URL de connexion SSO et ses paramètres
Pour établir une connexion SSO, vous utiliserez l'URL dédiée à cette fonctionnalité :
https://www.clicrdv.com/api/v1/sessions/sso/ :identifier.json?data=:data&iv=:iv
Le code :identifier vous sera transmis par ClicRDV.
Les paramètres :data et :iv représentent respectivement les données cryptées que vous nous transmettez à propos du client que vous souhaitez authentifier, et le vecteur d'initialisation utilisé lors du cryptage de ce jeu de données.
La génération des valeurs des paramètres :data et :iv dépendra de la stratégie SSO que vous souhaitez mettre en place (voir rubrique Votre stratégie SSO).
Le format ".json" précisé dans le chemin d'URL permet d'indiquer que le résultat de la requête de login SSO sera au format JSON.
3 Choix de la méthode d'authentification SSO
Deux modes sont possibles:
- Mode "redirection" 4
- Mode "proxy" 5
Dans le mode "redirection", vous souhaitez authentifier votre client sur l'API ClicRDV via un mécanisme SSO, puis le rediriger vers le module standard de prise de RDV de ClicRDV. Vous décidez donc de déléguer la gestion du parcours client à ClicRDV. Ce mode est plus simple que le mode "proxy" (voir 5) et est donc le mode recommandé pour la plupart des cas.
Dans le mode "proxy", alternatif à celui proposé en 4, est plus complexe. Il est adapté à la réalisation de votre propre parcours sur votre site internet ou sur votre application mobile.
4 Authentification SSO suivie d'une redirection vers le module de prise de RDV
Dans ce mode, vous souhaitez authentifier votre client sur l'API ClicRDV via un mécanisme SSO, puis le rediriger vers le module standard de prise de RDV de ClicRDV. Vous décidez donc de déléguer la gestion du parcours client à ClicRDV.
Ce mode est plus simple que le mode "proxy" (voir 5), et est donc le mode recommandé pour la plupart des cas.
Dans un premier temps, vous réalisez donc une connexion SSO "client à serveur" en redirigeant le navigateur internet de votre client sur l'URL SSO ClicRDV.
Pour ce faire, vous pouvez par exemple envoyer votre client (qui est supposé être loggué sur votre site) vers une URL du type https sur votre serveur.
Votre serveur est alors responsable de :
- vérifier que le client est authentifié sur votre site,
- générer l'URL SSO ClicRDV adéquate pour ce client en passant les informations d'identification du client connecté dans le paramètre
:data, - répondre à la requête initiale de votre client en le redirigeant vers l'URL SSO ClicRDV ainsi générée, avec un code HTTP 302 (redirection temporaire).
Important En passant le paramètre :redirect dans l'URL SSO ClicRDV, vous pouvez faire en sorte que cette requête redirige automatiquement votre client après sa connexion, via une redirection HTTP 302 (redirection temporaire). Le navigateur internet de votre client le redirigera automatiquement vers la page ciblée par le paramètre :redirect, page sur laquelle il sera directement authentifié, sans avoir à se logguer ni à créer de compte ClicRDV.
En général, vous devez passer le chemin d'URL vers votre module de prise de RDV dans ce paramètre, par exemple : si :redirect vaut "/ma-boutique", alors l'URL finira par "...&redirect=%2Fma-boutique", et votre client sera redirigé après connexion SSO vers https
Pour des raisons de sécurité, il n'est pas possible de rediriger vers un autre domaine que le domaine de l'API SSO, à savoir www.clicrdv.com.
Note Il est tout à fait possible de réaliser cette connexion SSO depuis une iframe sur votre site internet. Après établissement de la connexion, l'iframe sera redirigée vers le module de prise de RDV qui s'affichera en son sein.
5 Usage de l'API en mode "proxy" : vous gérez vous même tout le parcours de votre client
Ce mode, alternatif à celui proposé en 4 est plus complexe. Il est adapté à la réalisation de votre propre parcours sur votre site internet ou sur votre application mobile.
Le cas typique est celui d'un client connecté sur votre serveur (i.e. il a une session active chez vous) et que vous souhaitez authentifier sur notre API, pour ensuite requêter notre API depuis votre serveur, pour le compte de ce client.
Votre site ou votre application communiquent uniquement avec votre serveur, qui agit comme un proxy sur notre API.
Pour ce faire, vous initiez une requête SSO depuis votre serveur et vous récupérez le header Set-Cookie: _session_id=... renvoyé par la requête pour connaître l'ID de session ClicRDV à utiliser pour ce client.
Par la suite, vous pouvez requêter l'API ClicRDV depuis votre serveur en passant l'ID de session du client dans un header Cookie: _session_id=... ajouté à chaque requête faite à l'API ClicRDV.
Dans ce mode, vous gérez l'intégralité du parcours de votre client depuis votre serveur, votre client n'étant pas connecté à notre site via son navigateur internet.
De plus, vous êtes responsable de la gestion de la session du client, et en cas d'expiration de la session (typiquement quand l'API ClicRDV renvoie des erreurs HTTP 401 ou 404), il vous faudra renouveller une requête de login SSO.
Votre stratégie SSO
Note Le système SSO de ClicRDV est configurable. Il vous sera donc demandé d'établir votre stratégie SSO en répondant aux questions suivantes.
1 Quel identifiant client transmettre à ClicRDV ?
Lors de la première connexion SSO, votre client sera rattaché à un compte ClicRDV, créé pour la connexion SSO et qui servira à reconnaître ce même client lors de ses prochaines visites (nouvelles prises de RDV, annulation d'un RDV, etc.).
Afin d'établir ce lien entre votre client et son compte ClicRDV servant à la connexion SSO, vous devez impérativement nous transmettre un identifiant, nommé uid dans la suite de cette documentation, qui doit être unique pour chacun de vos clients.
A titre d'exemple, vous pouvez utiliser :
- l'ID de votre client dans votre système d'information Recommandé
- ou bien, une clé unique aléatoire (ex: UUID) associée à chacun de vos clients
2 Quel algorithme de cryptage et quelles options ?
Pour vérifier l'origine de la connexion SSO et s'assurer de la confidentialité des informations échangées, il est nécessaire de crypter les informations que vous envoyez à ClicRDV.
Le SSO ClicRDV est basé sur l'utilisation d'un algorithme cryptographique symétrique (clé secrète partagée entre vous et ClicRDV).
Deux algorithmes sont disponibles :
Vous devrez communiquer à ClicRDV votre choix :
- de l'un de ces deux algorithmes
- de la clé secrète et sa longueur (128 bits, 256 bits)
- de l'usage ou non d'un vecteur d'initialisation
- du mode associé à l'agorithme de cryptage (ex : "CBC")
- du padding associé à l'algorithme de cryptage (ex : "pkcs7")
Un vecteur d'initialisation (nommé iv dans la suite de cette documentation, pour "initialization vector" en anglais) permet d'assurer un degré supplémentaire de sécurité et est donc fortement recommandé.
Ces deux algorithmes et les diverses options associées (clé, mode, iv) sont utilisables quel que soit le langage de programmation que vous choisissez d'utiliser. Renseignez-vous sur les librairies ou modules existants pour utiliser facilement ces algorithmes dans votre langage de programmation.
3 Quel encodage pour les paramètres binaires ?
Lors de la connexion SSO, vous échangez avec ClicRDV des informations cryptées, ainsi que le vecteur d'initialisation. Il s'agit dans les deux cas d'informations "binaires" qui ne peuvent être envoyées telles quelles dans l'URL de connexion SSO (le binaire n'étant pas autorisé dans les URLs).
Il est donc nécessaire d'encoder les informations binaires dans un format "de transport", qui permettra de passer les informations via l'URL de connexion SSO.
Trois formats sont disponibles, parmi lesquels il vous faudra choisir :
- le format base64 (RFC 2045)
- le format base64 "urlsafe" (RFC 4648) : variante utilisant respectivement les caractères "-" et "_" en remplacement de "+" et "/"
- le format base64 "bouncycastle" : basé sur la librairie Java "Bouncy Castle", ce format est similaire au base64 "urlsafe", mais avec en plus le caractère "=" en remplacement de "." (voir documentation Bouncy Castle)
Recommandé Le format base64 "urlsafe" est recommandé car il permet d'éviter par la suite une étape d'URL-encoding des paramètres :data et :iv.
4 Que se passe-t-il après la connexion SSO ?
Votre client est désormais connecté en SSO à la plateforme ClicRDV.
Vous pouvez décider au choix :
- de le rediriger automatiquement vers votre module de prise de RDV, ou bien
- de gérer vous même le parcours de votre client sur votre site
Pour tout autre comportement, contactez ClicRDV pour étudier les possibilités de personnalisation.
Un exemple détaillé d'intégration
Cet exemple d'intégration est basé sur l'intégration iframe, avec un processus préalable, détaillé ci-dessous, qui dispense votre client de s'identifier sur le module de prise de RDV s'il est déjà identifié sur votre site (c'est le mécanisme d'authentification SSO suivie d'une redirection vers le module de prise de RDV).
Pour l'exemple, on suppose également que vous avez établi votre stratégie SSO avec les choix suivants :
- 1 l'
uidest votre identifiant client interne - 2 cryptage en AES 128 bits :
- en mode CBC
- avec un padding de type PKCS7
- un vecteur d'initialisation de 128 bits, passé dans le paramètre
ivet différent à chaque requête - une clé binaire (128 bits) secrète, partagée entre ClicRDV et vous, représentée en binaire par la séquence :
00110000001100010011001000110011001101000011010100110110001101110011100000111001011000010110001001100011011001000110010101100110
qui peut être représentée en hexadecimal par :30 31 32 33 34 35 36 37 38 39 61 62 63 64 65 66
ou encore, plus simplement en UTF-8 :0123456789abcdef
Note Il est toujours préférable en production d'utiliser une clé binaire réellement aléatoire, qui ne sera pas nécessairement représentable en UTF-8. La clé binaire choisie dans cet exemple a été au contraire choisie pour être facilement visualisable en UTF-8.
- 3 encodage de transport de type base64 "urlsafe" (RFC 4648)
- 4 après connexion, redirection automatique du client vers votre module de prise de RDV
Voici la liste des étapes à mettre en place :
1 Le processus commence sur votre site
Le client doit être loggué sur votre site internet (session authentifiée active).
Lorsque le client clique sur le bouton "prendre RDV" de votre site internet, vous allez générer une balise iframe dans la page courante, ayant pour source une URL spécifique de votre site, notée pour l'exemple https:.
Le résultat doit être similaire à :
<iframe src="https://www.votre-serveur.com/sso-clicrdv"
style="width: 600px; height: 500px; border: 0">
<p class="fallback_message">
La prise de rendez-vous est impossible sur votre
navigateur internet (iframe non supportée).
</p>
</iframe>
Important Il est fortement recommandé de mettre une hauteur et une largeur par défaut à l'iframe (largeur minimale : 470px), car le module de prise de rendez-vous s'affiche dans cette iframe en fin de processus d'identification SSO.
Note Remplacez https: par l'URL correspondant à votre page spécifique.
2 Préparation des paramètres de connexion SSO sur votre serveur
L'URL https:, appelée en GET par l'iframe, exécute sur votre serveur un processus qui a pour objectif de générer une URL SSO ClicRDV valide permettant de logguer votre client sur le serveur ClicRDV.
Tout commence par la création d'un objet contenant a minima les propriétés suivantes (strings en UTF-8) :
| Champ | Type | Description |
|---|---|---|
| uid | string(255) | Identifiant de votre client sur votre SI |
| iat | integer | Clé de sécurité "issued at" Il s'agit d'un timestamp (au format unix time) représentant la date et heure de génération de la requête, et assurant une protection contre les replay attacks. |
Cet objet doit être ensuite sérialisé au format JSON. Vous obtenez alors une chaîne de caractères UTF-8 du type (les guillemets simples matérialisent la chaîne de caractère, mais n'en font pas partie) :
'{ "uid": "1234576", "iat": 1474987884 }'
Vous allez ensuite transformer cette chaîne de caractères en un blob (= "chaîne binaire") crypté via l'agorithme AES 128 bits, en mode CBC, avec un padding PKCS7 et avec un vecteur d'initialisation binaire créé pour cette requête.
On utilise par exemple l'iv binaire suivant (128 bits générés aléatoirement) :
10011000100111001111100000100001000111001100001111011001001010101001010110001011010011011110001010110010000001110111001001001000
Le cryptage AES ainsi réalisé, vous obtenez la chaîne binaire suivante :
001110001101101000010111010111011011000000101001000111101000001001110101110001100000011100111110001100010001111000010101101101110001011110010010111010000001011100011010100001001010111101101010010001100011101100010100001101100100001010001101101011101000101000001101010011111010010000101000101110101010000011100100000010011101011011011111010100111101101111101110111111111000101010100010
Cette chaîne binaire devra être transmise via le paramètre d'URL :data, ce qui n'est pas possible en l'état, le binaire n'étant pas autorisé dans les URL.
Vous devez donc en plus l'encoder en base64 (on a choisi la variante "urlsafe"), ce qui donne :
ONoXXbApHoJ1xgc-MR4VtxeS6BcahK9qRjsUNkKNrooNT6QouqDkCdbfU9vu_4qi
De même, vous devez encoder en base64 le vecteur d'initialisation. Vous obtenez (on a choisi la variante "urlsafe") :
mJz4IRzD2SqVi03isgdySA==
C'est le paramètre :iv que vous passerez dans l'URL de connexion SSO.
3 Réponse de votre serveur
Après avoir généré les paramètres :data et :iv, votre serveur doit déclencher une redirection HTTP 302 ayant pour cible l'URL de login SSO sur le serveur ClicRDV :
:identifier.json?data=:data&iv=:iv&redirect=:redirect
Dans l'exemple, en supposant que vous souhaitiez rediriger vers votre module de prise de RDV situé au chemin d'URL "/ma-boutique" (avec l'option "?popin=1" permettant un affichage du module adapté à l'iframe), vous utiliserez dans l'URL les valeurs :
:identifier: demo:data: ONoXXbApHoJ1xgc-MR4VtxeS6BcahK9qRjsUNkKNrooNT6QouqDkCdbfU9vu_4qi:iv: mJz4IRzD2SqVi03isgdySA==:redirect: /ma-boutique?popin=1
Les paramètres d'URL :data, :iv et :redirect doivent de plus être URL-encodés avant d'être intégrés dans l'URL. Ce n'est pas nécessaire pour les paramètres :data et :iv si vous choisissez la variante "urlsafe" de base64, ce que nous avons fait.
L'URL de login SSO devient :
Note Remplacez :identifier par l'identifiant fourni par ClicRDV, et :redirect par le chemin d'URL de votre page de prise de RDV.
4 Connexion SSO et rendu du module de prise de RDV dans l'iframe
La redirection HTTP 302 aura lieu dans l'iframe créée à l'étape 1. Le serveur ClicRDV va alors décoder le blob crypté, authentifier votre client à partir de l'uid que vous avez spécifié, puis rediriger le client vers le module de prise de RDV (qui s'affiche donc à l'intérieur de l'iframe).
A ce moment, l'iframe créée à l'étape 1 contiendra le code suivant :
<iframe src="https://www.clicrdv.com/ma-boutique?popin=1"
style="width: 600px; height: 500px; border: 0">
<html>
<!-- code du module de prise de rendez-vous ClicRDV -->
</html>
</iframe>