Ouverture de session à authentification unique via SAML dans MyGeotab
Integration Guide
0 mins to read
Découvrez comment MyGeotab prend en charge l’authentification unique des utilisateurs via la spécification SAML 2.0, y compris les exigences et procédures de configuration d’une application IdP et de préparation d’une base de données MyGeotab pour accepter l’authentification. Consultez les questions fréquemment posées et examinez les solutions aux problèmes de dépannage les plus courants.
Guide d’intégration SAML 2.0
Juillet 2021
Table des matières
Introduction
MyGeotab (version 5.7.2101 et plus récente) prend en charge l’authentification unique (SSO) d’utilisateur par l’entremise de la spécification SAML 2.0 avec des liaisons de protocole initiées à la fois par le fournisseur d’identité (IdP, Identity Provider en anglais) et le fournisseur de services (SP, Service Provider en anglais), comprenant l’authentification SAML pour Geotab Drive.
Ce document décrit les exigences et les procédures de Geotab pour la création et la configuration d’une application IdP, la préparation d’une base de données MyGeotab pour accepter l’authentification de cet IdP, la configuration des utilisateurs MyGeotab pour l’authentification SAML, ainsi que les questions fréquemment posées et les conseils de dépannage.MyGeotab prend en charge l’authentification des utilisateurs à l’aide de SAML 2.0 uniquement, comme décrit dans ce document. Les méthodes OpenID Connect (OIDC), authentification Web sécurisée, OAuth 2.0, résolution des artéfacts, liaison des artéfacts ou d’autres ne sont pas prises en charge.
Étant donné que SAML est une norme publiée, ce document suppose que l’intégration de l’authentification fonctionne avec tout IdP qui offre SAML comme méthode d’authentification unique. Dans la mesure du possible, tous les paramètres référencés comprennent un nom descriptif générique et le nom de l’élément SAML correspondant, tel qu'il apparaîtrait dans une assertion SAML. Les paramètres dans lesquels un fournisseur d’IdP particulier utilise un terme suffisamment différent sont également notés.
Prérequis et hypothèses
Les intégrations SAML 2.0 réussies nécessitent les éléments suivants :
- Accès administratif à un IdP existant avec les capacités suivantes :
- la configuration des applications à l’aide d’une méthode d’ouverture de session SAML 2.0;
- la gestion des affectations d’utilisateur à cette application; et
- l’accès à toute restriction de politique d’ouverture de session pertinente pouvant être mise en œuvre dans la configuration du fournisseur.
- Accès administratif à une base de données d’entreprise Geotab (MyGeotab, MyPreview, etc.) avec la capacité d’accéder et de modifier les utilisateurs et les paramètres sous Administration > Système > Paramètres du système (en particulier les certificats).
- Capacité de se connecter et d’agir en tant qu’utilisateur dans les environnements IdP et MyGeotab afin de tester l'intégration.
- Connaissance des exigences ou limitations propres à Geotab suivantes :
- La valeur « Utilisateur (courriel) » de MyGeotab doit correspondre exactement à un identifiant d’utilisateur IdP.
- L’identifiant d’utilisateur IdP doit être envoyé comme contenu d’un attribut/réclamation spécifique à Geotab à créer pour l’application appelée « Courriel ». Cet attribut SAML n’existera pas par défaut.
- Aucune méthode d’authentification unique autre que SAML n’est prise en charge.
- Les processus de gestion des utilisateurs de Geotab ne changeront pas; il n’y a actuellement aucune prise en charge de SCIM ni d’autres provisionnement ou création automatisés d’utilisateurs.
- Si une application IdP est créée pour la connexion à Geotab qui permet d’envoyer des attributs d’utilisateur de prénom et de nom de famille, ces noms doivent correspondre au prénom et au nom de famille de l’utilisateur dans la base de données MyGeotab. L’envoi de ces attributs de nom n’est pas recommandé.
- Les étapes fournies dans ce document comprennent les valeurs et les procédures connues pour fonctionner dans au moins quatre IdP couramment utilisés. D’autres variations peuvent être possibles, mais sont encore inconnues.
Configuration de l’application IdP
Création de l’intégration d’applications
Sur l’interface utilisateur de l’IdP, procédez de la manière suivante pour lancer la création d’une nouvelle application au moyen de sa fonction « Créer une Intégration d’Application/Nouvelle Application » ou une fonction similaire :
- Sélectionnez SAML ou SAML 2.0 comme méthode ou propriété SSO. Toutes les autres options ne sont pas valides.
- Précisez les paramètres généraux de l’IdP pour le nom, le logo, le symbole ou la visibilité, au besoin.
- Spécifiez les paramètres SAML courants requis comme suit :
- URL du service à la clientèle de l’application (ACS) : peut également être présentée sous forme d’URL d’authentification unique, d’URL de réponse, d’URL de destination, d’URL du destinataire ou de multiples de ces URL. Pour chacune de ces options, entrez https://my.geotab.com/apiv1/authenticateSaml?redirect=true comme URL (si vous utilisez l’ACS par défaut). Cela est affiché dans les assertions des éléments « Destination de la réponse » et « Destinataire ». Reportez-vous au sujet URL de FAQ du Service client des applications (ACS, Application Consumer Service en anglais) pour connaître les possibilités supplémentaires pour cette valeur, y compris celles liées aux fédérations autres que https://my.geotab.com.
- Restriction de l’auditoire, URI de l’auditoire, identificateur, ID d’entité : recommander https://my.geotab.com/. Dans Azure, cet élément est « Identifiant (ID d’entité) ». Pour certains IdP, cette valeur doit correspondre exactement à la valeur envoyée par Geotab en tant que « Émetteur » dans une demande SAML pour la connexion lancée par SP. Voici quelques exemples :Production Geotab : https://my.geotab.com/Aperçu Geotab : https://mypreview.geotab.com/Gouvernement Geotab : https://gov.geotab.com/
- RelayState par défaut : aucune valeur n’est requise ni recommandée. Il s’agit de la valeur par défaut courante dans les IdP.
- Format d’ID de nom : soit « non spécifié », soit « EmailAddress ».
- Nom d’utilisateur de l’application (élément « objet » SAML) : le courriel d’utilisateur IdP est l’option privilégiée.
Configuration des paramètres SAML avancés pour l’IdP
Les paramètres SAML avancés fonctionnent généralement correctement avec leurs paramètres IdP par défaut. Voici deux points à noter :
- Signer la réponse et l’assertion : s’assurer que l’assertion SAML est signée pour fonctionner correctement avec MyGeotab.
- Spécifier la valeur d’ID d’émetteur SAML (saml2:Issuer) : les ID basées dans le nuage, comme Okta et Azure utilisent des valeurs par défaut, composées d’URL génériques se terminant par des ID d’entité alphanumériques générées, qui sont utilisées pour identifier (nommer) un certificat téléversé dans MyGeotab. La spécification de la valeur de l’élément d’assertion « saml2:Issuer » à quelque chose de descriptif peut être utile dans les situations où plusieurs certificats sont utilisés, ou pour lier un certificat installé à une instance d’application IdP spécifique. Par exemple, un émetteur par défaut peut être « http://app.idpvendor.com/exkpa1k1izkCKeDS85d6 », qui peut être réglé à « TestCertForLocationLimitedSignOn ».
Remarque : La spécification de la valeur saml2:Issuer est entièrement facultative pour les besoins spécifiques de la fonction utilisateur, et aucune recommandation supplémentaire ne s’applique.
Configuration d’attributs IdP supplémentaires
Configurez d’autres attributs de IdP comme suit :
- Attributs requis : ajouter un attribut ou une réclamation incluant les éléments suivants :
- Nom : courriel
- Format de nom : non spécifié (aucun format spécifique requis)
- Attribut Valeur/utilisateur : courriel de l’utilisateur (user.email/user.mail comme option de l’IdP sélectionnable pour l’utilisateur ou l’attribut source de l’utilisateur)
- Attributs facultatifs : si vous gérez l’accès à plusieurs bases de données Geotab, surtout lorsqu’un nom d’utilisateur IdP peut exister dans plusieurs bases de données, ajoutez l’attribut ou la réclamation suivants pour définir la base de données pour laquelle l’utilisateur doit être authentifié (et donc connecté) :
- Nom : restriction de base de données
- Format de nom : non spécifié (aucun format spécifique requis)
- Valeur/attribut d’utilisateur : le nom de connexion de l’utilisateur de la base de données Geotab doit être limité à cela (sous forme d’entrée de texte libre)
Finalisation de l’intégration
Une fois les attributs et les paramètres ci-dessus complétés, vous devriez être au point où l’intégration de l’application peut être enregistrée et terminée. Si on vous demande de publier ou de fournir des commentaires, les réponses indiquant que vous ajoutez une demande interne pour usage interne compléteront le processus. Assurez-vous de ce qui suit :
- Compléter les affectations d’utilisateur : l’application doit être attribuée aux utilisateurs ou aux groupes autorisés à utiliser l’application, incluant au moins un utilisateur disponible pour tester la nouvelle application. Tous les utilisateurs affectés à l’application doivent également exister dans la base de données cible de MyGeotab, avec des noms d’utilisateur ou des courriels identiques à l’identifiant d’utilisateur IdP sélectionné pour l’envoi dans l’attribut Courriel.
- Noter les propriétés de configuration du SP : l’interface IdP de la nouvelle application Geotab comprend une option d’accès ou d’affichage des instructions ou des propriétés de configuration du SP. Ces renseignements doivent être notés pour leur entrée dans l’IU de MyGeotab, car l’utilisation de l’échange de métadonnées avec l’IdP n’est pas prise en charge. Les propriétés requises sont les suivantes :
- Émetteur du fournisseur d’identité : entrez la valeur dans l’interface utilisateur de MyGeotab comme « Émetteur du certificat », qui correspond à la valeur de l’ID d’émetteur SAML décrite ci-dessus.
* REMARQUE : C’est ce qu’on appelle « Identifiant AD Azure » dans Microsoft Azure.
- URL d’authentification unique IdP : point d’extrémité de destination utilisé pour l’authentification par le SP. Entrez la valeur dans l’interface utilisateur de MyGeotab comme « URL de connexion ».
- Certificat X.509 : signature du certificat à téléverser dans Geotab en tant que fichier. Le certificat doit être téléchargé à partir de l’IdP pour se préparer au téléversement. Il devrait avoir l’extension .cer (renommez .cer si vous l’avez téléchargé en .cert). Si une option d’encodage est offerte (Azure), base64 et Raw devraient fonctionner.
* REMARQUE : Certains clients ont proposé des rapports contradictoires selon lesquels l’un a fonctionné lorsque l’autre pas.
Installation du certificat MyGeotab
Procédez comme suit en tant qu’utilisateur administrateur dans la base de données de MyGeotab :
- Dans le menu principal, sélectionnez Administration > Système > Paramètres du système.
- Cliquez sur l’onglet Politique relative aux comptes utilisateurs et activez Autoriser la connexion SAML.
- Cliquez sur l’onglet Certificats et cliquez sur Ajouter un nouveau certificat.
Téléversez votre fichier .cer correctement formaté. Vous verrez un message indiquant que le fichier de clé de certificat <nom de votre fichier>.cer a été accepté.
* REMARQUE : Cela indique un chargement de fichier réussi seulement; le contenu du fichier n’est pas validé.
- Dans le champ Émetteur du certificat, entrez Émetteur IdP pour la valeur de l’émetteur du fournisseur d’identité, ce qui indique les options de signature pour la réponse et l’assertion.
- Dans le champ URL de connexion, entrez l’URL d’authentification unique IdP, qui est le point d’extrémité de destination utilisé pour l’authentification initialisée par le SP.
- Dans le champ URL de déconnexion, entrez l’URL à laquelle l’utilisateur doit être redirigé après s’être déconnecté de MyGeotab. Une URL de déconnexion fournie par l’IdP peut exister, mais ce champ est facultatif et peut correspondre à n’importe quelle URL valide. Si le champ est laissé vide, la boîte de dialogue d’ouverture de session MyGeotab s’affiche lors de la déconnexion.
- Sélectionnez Enregistrer, sur la page Certificats.
- Cliquez sur Enregistrer dans la page Paramètres système.
Gestion de la base de données d’utilisateurs MyGeotab
Configuration de l’authentification SAML pour un utilisateur nouveau ou existant
Les comptes MyGeotab doivent être configurés pour l’authentification SAML afin que cette intégration fonctionne.
✱ REMARQUE : Le fichier de certificat MyGeotab doit être téléversé avec succès avant de compléter cette procédure.
Procédez comme suit pour configurer un utilisateur MyGeotab pour l’authentification SAML :
- Lors de l’ajout ou de la modification d’un utilisateur dans MyGeotab, sélectionnez SAML comme Type d’authentification.
- L’interface sera mise à jour pour supprimer les options de mot de passe et les remplacer par une liste déroulante d’émetteurs de certificats. Notez ce qui suit :
- Si un seul certificat existe, il sera le certificat sélectionné par défaut.
- S’il existe plusieurs certificats, assurez-vous de sélectionner le bon certificat pour l’application qui a été attribuée à l’utilisateur dans l’IdP.
- Plusieurs certificats MyGeotab peuvent exister dans la base de données, mais un seul peut être attribué à un utilisateur donné.
- L’enregistrement de l’utilisateur complète la modification. Si l’utilisateur existait déjà avec l’authentification de base, son mot de passe n’existe plus, ni l’option d’ouverture de session avec un mot de passe. Il est possible de ramener l’utilisateur à l’authentification de base, mais, pour cette utilisation par mot de passe, il faudra effectuer une réinitialisation du mot de passe administratif ou utiliser l’option « forcer la modification du mot de passe à la prochaine ouverture de session ».
En raison du risque de perdre temporairement l’accès à un compte d’utilisateur pendant les essais initiaux de l’intégration de l’authentification, il est fortement recommandé de créer un utilisateur d’essai dans MyGeotab et l’IdP pour confirmer la fonction avant son déploiement aux utilisateurs actifs. De même, un utilisateur administrateur d’authentification de base doit toujours exister en guise de sauvegarde en cas de défaillance catastrophique (p. ex., perte d’accès à la fonction IdP, invalidation de certificat, suppression accidentelle de l’application IdP, etc.).
Options supplémentaires pour l’activation de l’authentification SAML pour les utilisateurs
La modification des utilisateurs est possible via l’interface d’API de Geotab, comme indiqué dans la trousse de développement logiciel SDK MyGeotab. Les procédures spécifiques échappent à la portée du présent document, à l’exception de la prise de notes de l’existence des entités et des propriétés d’entité suivantes :
- L’entité Certificat est l’objet stocké lorsqu’un certificat est enregistré dans l’interface utilisateur. Si elle est examinée par le résultat d’une méthode Get(), sa propriété id est la valeur utilisée pour associer le certificat à un utilisateur.
- L’entité Utilisateur possède les propriétés suivantes propres à l’authentification SAML :
- UserAuthenticationType (type d’authentification d’utilisateur) est une propriété de chaîne existante qui peut être changée de « BasicAuthentication » (authentification de base) à « SAML »
- issuerCertificate (certificat de l’émetteur) est un objet qui possède les propriétés suivantes :
- Id : défini à l’identificateur d’une entité de certificat dans la base de données.
- IsRoot : (est racine) réglé à « false » (faux)
Un exemple d’appel d’API de chemin de SDK de Geotab pour changer un utilisateur de base à SAML par la configuration de userAuthenticationType et de issuerCertificate est le suivant :
api.multiCall([["Get",{
"typeName": "User",
search: {name: "May282021User@nomail.com"} /*remplacer par le nom de l’utilisateur réel*/
}],],
function(results)
{ var SAMLUser = results[0] && results[0][0] ? results[0][0] : null;
if (SAMLUser){
SAMLUser.userAuthenticationType = "SAML";
SAMLUser.issuerCertificate = {
id : "a6mATltOsVUGge8CjPyoPfQ"}; /*utiliser l’ID du certificat réel*/
api.call("Set",{
typeName : "User",
entity : SAMLUser}),
console.log("User \"" + SAMLUser.name + "\" certificat attribué \"" + SAMLUser.issuerCertificate.id +"\"");}
else {
console.log("Utilisateur introuvable!");
}},
console.error);
Il existe également un outil Add-In d’ajout de modification en bloc qui devrait permettre la manipulation de plusieurs utilisateurs dans une base de données, y compris l’option de définir l’authentification SAML avec un certificat installé. Reportez-vous à Comment accéder au nouvel Add-In de modification en bloc? Dans la communauté Geotab pour obtenir plus d’informations sur l’installation de l’Add-In pour votre environnement.
Tests de l’intégration
Une fois la configuration d’intégration terminée, vous devriez maintenant tester le processus d’authentification SAML 2.0.
Authentification SAML sur MyGeotab (initiée par IdP)
Procédez comme suit :
- Cliquez sur le lien de l’application lorsque vous êtes connecté au portail d’applications IdP en tant qu’utilisateur. Le compte d’utilisateur doit :
- avoir un accès assigné à l’application Geotab créée dans l’IdP; et
- être configuré dans MyGeotab pour l’authentification SAML et avoir reçu un certificat créé dans l’IdP correspondant à l’application.
Résultat : le navigateur ouvre une session dans MyGeotab en tant que l’utilisateur spécifié.
Authentification SAML sur MyGeotab (initiée par SP)
Procédez comme suit :
- Allez au site https://my.geotab.com où la boîte de dialogue d’ouverture de session devrait s’afficher.
- Entrez un utilisateur (ou courriel) de Geotab qui possède une valeur d’URL d’ouverture de session valide associée au certificat installé.
- Cliquez sur Suivant.
Résultat : le navigateur ouvre une nouvelle fenêtre ou un nouvel onglet avec l’URL d’ouverture de session IdP, où une connexion réussie entraîne l’ouverture de l’IU MyGeotab.
Authentification SAML sur Geotab Drive
Procédez comme suit :
- Ouvrez Geotab Drive et entrez un nom d’utilisateur configuré pour répondre à toutes les exigences ci-dessus pour les connexions initiées par IdP et SP.
- Cliquez sur Suivant.
Résultat : la fenêtre du navigateur ouvre une nouvelle fenêtre ou un nouvel onglet avec l’URL de connexion IdP, où une connexion réussie entraîne l’ouverture de l’IU Geotab Drive.
Dépannage
! IMPORTANT : Pour tous les autres problèmes d’authentification, communiquez avec le soutien Geotab (ou toute autre personne-ressource pertinente) pour indiquer le problème rencontré, l’IdP utilisé, la base de données Geotab, le nombre d’utilisateurs concernés, un exemple d’utilisateur concerné, et une copie d’une assertion SAML saisie dans l’activité réseau du navigateur lorsque le problème s’est produit. Une copie du fichier de certificat utilisé pour l’installation dans la base de données Geotab serait également utile.
Authentification rejetée par Geotab
Problème : l’utilisateur ne peut pas être authentifié.
Symptôme : la réponse JSON à l’adresse URL https://my.geotab.com/apiv1/authenticateSaml?redirect=true indique « Identifiants de connexion incorrects » avec le nom « InvalidUserException » et le code « 32000 ».
Cause : quelque chose au sujet de l’assertion SAML fournie ne correspond pas à la combinaison attendue d’attributs requis pour compléter l’authentification de l’utilisateur.
Dépannage : toutes les exigences de ce document peuvent être examinées pour s’assurer qu’elles sont remplies dans les interfaces utilisateurs pertinentes. S’il n’est pas facile d’identifier le problème, installez un Add-In de traceur SAML au navigateur ou utilisez la console du développeur de ce dernier pour examiner l’assertion SAML envoyée. Elle doit être identifiable comme SAML à partir d’un attribut d’en-tête.
Les éléments à examiner dans l’assertion comprennent ce qui suit :
- saml2:Issuer : doit être identique à la valeur de l’émetteur du certificat entrée pour le certificat dans MyGeotab. S’il est mal orthographié dans Geotab, un certificat installé n’existe pas avec le nom correct.
- saml2:AttributeStatement : doit contenir saml2:Attribute Name="Email", la valeur de l’attribut étant définie au nom d’utilisateur de l’utilisateur Geotab à connecter. S’il est incorrect dans un aspect quelconque, l’utilisateur n’existe pas.
- saml2:Attribute Name="databaseRestriction" : la valeur spécifiée (le cas échéant) doit correspondre au nom de la base de données dans laquelle l’utilisateur est connecté. Si cette valeur est mal orthographiée dans l’application IdP, la base de données n’existe pas.
Il est également possible d’avoir des problèmes avec des certificats ou des relations de confiance de certificat. Cela se produit généralement dans les situations où une intégration précédemment correctement fonctionnelle a soudainement échoué pour tous les utilisateurs SAML. Si aucune autre cause n’est identifiable, il sera alors pertinent de voir si le remplacement du certificat résout le problème ou de confirmer sa fonction avec un autre SP si disponible.
Authentification refusée par l’IdP
Problème : l’utilisateur ne peut pas être authentifié.
Symptôme : les symptômes possibles sont spécifiques à un IdP.
Cause : inconnue, sauf indication contraire dans l’IdP, mais les suspicions les plus immédiates ne visent aucune affectation à l’utilisateur, ou l’utilisateur ne respecte pas les politiques d’authentification spécifiques à l’IdP limitant l’accès par emplacement, heure de la journée, plateforme, etc. Cela peut également se produire avec des attentes erronées autour des relations parent-enfant entre les groupes de répertoires intégrés utilisés pour l’attribution d’applications. Geotab ne peut pas causer ces défaillances; aucune assertion SAML ne devrait être envoyée pour l’authentification lorsque cela se produit.
Dépannage : ouvrez une session sur le portail IdP directement à titre d’utilisateur concerné et essayez de lancer l’application; vérifiez si l’erreur générée fournit des conseils.
L’utilisateur authentifié est invité à procéder à une nouvelle authentification
Problème : l’utilisateur authentifié par SAML est invité à procéder à une nouvelle authentification lors de l’utilisation de la fonctionnalité « Ouvrir le lien dans un nouvel onglet » dans l’IU MyGeotab ou lorsqu’il clique sur un lien Add-In ouvrant un nouvel onglet ou une nouvelle fenêtre vers l’IU Geotab.
Cause : les sessions authentifiées par SAML sont gérées différemment des sessions de base (par mot de passe). Les nouvelles instances de l’interface utilisateur MyGeotab ne font pas l’acquisition de jetons stockés pour les sessions authentifiées par SAML, qui nécessitent une nouvelle authentification au moyen de l’URL d’ouverture de session.
Dépannage : l’entrée du nom d’utilisateur de l’utilisateur authentifié SAML doit immédiatement terminer le processus si l’utilisateur a un identifiant valide à jour dans l’IdP.
Foire aux questions
Q : Quelle extension de navigateur peut saisir les échanges SAML dans plusieurs onglets et fenêtres, et fournir des assertions de décodage SAML et des vues de sommaire?
R : Les extensions de navigateur suivantes sont recommandées :
- Extension SAML-tracer pour Google Chrome (une extension réelle, et non l’onglet SAML dans la console du développeur)
- Supplément SAML-tracer pour Firefox
Q : Geotab est-il un fournisseur de services pour toute autre méthode d’authentification unique autre que SAML 2.0?
R : Non. Geotab prend en charge uniquement le protocole de SP HTTP-Redirect avec des interactions de liaison HTTP-POST d’IdP.
Q : Geotab prend-il en charge l’intégration SAML sortante, où Geotab est l’IdP?
R : Non. Geotab comprend l’importance de prendre en charge ce type de configuration et cherche à devenir un IdP pour une mise en œuvre de SSO standard de l’industrie. OAuth sera probablement la priorité initiale.
Q : Geotab prend-il en charge la connexion SAML initiée par SP, où les utilisateurs peuvent être redirigés de la page d’accueil de MyGeotab vers la page d’ouverture de session de l’IdP?
R : Oui. Cette fonctionnalité est disponible dans MyGeotab version 2101 et ultérieure.
Q : Geotab applique-t-il des restrictions sur l’ouverture de session des utilisateurs au moyen de SAML, comme l’emplacement de l’utilisateur, la plateforme, l’heure de la journée, l’adhésion au groupe d’annuaires, les exigences d’authentification à facteurs multiples, etc.?
R : Geotab ne met pas directement ces restrictions en œuvre et accepte toute assertion SAML autrement valide envoyée par l’IdP. Toute politique d’ouverture de session mise en œuvre dans l’IdP (ou dans le répertoire via l’IdP, ou par un autre module intégré à l’IdP) qui empêchera l’envoi de cette assertion empêchera également l’ouverture de session dans MyGeotab.
Q : Est-il possible de modifier un certificat MyGeotab une fois qu’il a été téléversé dans la base de données?
R : Oui. Cette fonctionnalité est disponible pour MyGeotab version 2101 et ultérieure. L’ouverture d’un certificat installé dans l’interface utilisateur affiche maintenant une option « Modifier le certificat » qui permet de télécharger un nouveau fichier de certificat pour permettre l’extraction de la clé contenue et son association avec l’entité de certificat existante.
Q : L’authentification à la fois de base et via SAML peut-elle être attribuée à un compte MyGeotab?
R : Non. Un utilisateur ne peut être affecté qu’à un seul type d’authentification. Dans certains cas, il peut être logique de créer deux comptes d’utilisateur MyGeotab pour un utilisateur.
Q : Dans quelles circonstances ne voudrions-nous pas utiliser l’URL par défaut du Service aux consommateurs d’applications (ACS)?
R : Il y a deux circonstances particulières dans lesquelles vous ne voulez pas utiliser https://my.geotab.com/apiv1/authenticateSaml?redirect=true comme URL de l’ACS :
- Si vous utilisez un serveur sur une autre fédération Geotab différenciée par un chemin d’accès non desservi par https://my.geotab.com, l’URL doit alors être modifiée pour pointer vers cette fédération. Par exemple, si vous avez une base de données de tests dans l’environnement mypreview.geotab.com, vous devez remplacer my.geotab.com par mypreview.geotab.com, mypreview2.geotab.com, etc., comme il convient à votre situation.
- Si vous développez ou utilisez une intégration d’application qui souhaite recevoir une authentification LoginResult Geotab sans réponse de redirection au navigateur, par exemple, pour avoir une session de compte de service avec accès à l’API Geotab, laissez la partie ?redirect=True de l’URL. Plus précisément :
- L’assertion doit être envoyée à MyGeotab dans un formulaire standard HTTP POST-de liaison SAML à l’ACS suivant :
https://<URL de fédération Geotab>/apiv1/authenticateSaml
. - La réponse HTTP aura un code d’état 200 et le corps sera un LoginResult.
- La fonctionnalité d’une application IdP utilisant ce mécanisme doit être confirmée dans un navigateur Web standard avant toute autre utilisation, et seule la fonctionnalité de navigateur Web peut être prise en charge par Geotab. Dans toute autre application, l’application doit fonctionner comme un agent utilisateur SAML (comme un navigateur le ferait), en tenant compte des éléments suivants :
- La modification du contenu d’une assertion de réponse SAML émise par un IdP avant la soumission par l’intermédiaire d’un HTTP POST ne fonctionnera pas et ne sera pas prise en charge.
- L’assertion de réponse doit être conforme aux exigences définies pour le noyau SAML dans https://www.oasis-open.org/committees/download.php/56777/sstc-saml-core-errata-2.0-wd-07-diff.pdf. Notamment (mais sans s’y limiter) la section 2.5 Conditions et les conditions NotBefore et NotOnOrAfter.
- L’assertion de réponse doit être conforme aux exigences définies pour la liaison SAML POST HTTP (c.-à-d. le côté réponse d’une liaison Demande/Réponse HTTP-Redirect/HTTP-POST) à la section 3.5 de https://www.oasis-open.org/committees/download.php/56780/sstc-saml-bindings-errata-2.0-wd-06-diff.pdf. Notamment (sans s’y limiter) aux sections 3.5.4, Codage des messages, et 3.5.5.2, Considérations de sécurité.
Q : Est-il possible d’ajouter un certificat via le SDK de l’API de Geotab?
R : Oui. Ce qui doit être envoyé comme propriété de « clé » d’une méthode Add() pour une entité de certificat est en fait une chaîne représentant le contenu entier d’un fichier de certificat X.509 converti d’ASCII à hexadécimal. La « clé » envoyée est ensuite convertie à la réception en la valeur stockée en tant que « clé » pour l’entité créée dans la base de données. La valeur envoyée est le bon format si elle commence par “2D2D2D2D2D424547494E204345525449” et se termine par “43455254494649434154452D2D2D2D2DA” (c.-à-d. “-----BEGIN CERTI“ et “CERTIFICATE-----“).L’exemple de code suivant serait exécuté dans le SDK Runner pour ajouter un certificat à une base de données. Pour une utilisation réelle, remplacez toutes les valeurs de propriété de l’exemple par celles applicables à votre application et au certificat de l’IdP :
api.call("Add", {
typeName : "Certificate",
entity : {
"issuer": "IdPIssuerIDForGeotab",
"logInUrl": "https://loginurl.myidp.com",
"logOffUrl": "https://logoff.tosomeurl.com",
"key": "[certificat X.509 ici]",
"id": null
}
}, function () {
console.log("Certificat ajouté ");
}, console.error);
Il est également possible de mettre à jour un certificat , p. ex., s’il arrive à échéance, vers une nouvelle propriété de clé au moyen d’un appel multiple à Get() un certificat avec un Set() sur l’entité pour remplacer la clé telle que soumise dans l’exemple Add(). Cet exemple permettrait de modifier l’émetteur ou la clé du certificat installé dans l’exemple ci-dessus, mais comme prévu, il n’exécuterait et ne changerait rien, car il s’agit du même certificat).
api.multiCall([["Get",{
"typeName": "Certificate",
search: {issuer: "IdPIssuerIDForGeotab"} /*remplacer avec l’émetteur réel*/
}],],
function(results)
{ var SAMLCert = results[0] && results[0][0] ? results[0][0] : null;
if (SAMLCert){
SAMLCert.issuer = "IdPIssuerIDForGeotab"; /*Modifier ici si l’ID d’émetteur change aussi*/
SAMLCert.key = "[Certificat X.509 ici]"
api.call("Set",{
typeName : "Certificate",
entity : SAMLCert}),
console.log("Certificate\"" + SAMLCert.issuer + "\" clé donnée \"" + SAMLCert.key +"\"");}
else {
console.log("certificat introuvable!");
}},
console.error);
Intégration assistée dans Geotab
Dans le cas où le dépannage de la configuration Geotab serait nécessaire pour aider à l’intégration de SAML, la liste des éléments ci-dessous assurera un progrès efficace de l’effort :
Personnel
Jusqu’à trois rôles peuvent être pourvus par une seule personne, mais chaque rôle doit être représenté lors de la ou des visites. Si la mise en œuvre est urgente, il est essentiel que tous les rôles suivants soient disponibles du début à la fin, y compris par courriel et pour tout appel connexe.
- Administrateur IdP : administrateur de l’IdP avec accès à l’application Geotab et au répertoire des utilisateurs de l’IdP.
- Administrateur de la base de données Geotab : un administrateur de la base de données des clients Geotab avec la possibilité de modifier les paramètres du système et de créer ou modifier des utilisateurs.
- Utilisateur d’essai : un utilisateur d’essai pertinent configuré dans l’IdP et la base de données Geotab. Cet utilisateur devrait avoir accès à des fonctions de navigateur comme la console du développeur et la possibilité d’ajouter des extensions de navigateur.
Configuration
Renseignements utiles relatifs à la configuration :
- Fournisseur IdP : Azure, Okta, OneLogin, Google Workspace, SiteMinder, PingFederate, etc.
- Base(s) de données cliente(s) :
URL lors de la connexion (p. ex., https://my###.geotab.com/<nomdebasededonnées>).
- Instructions de configuration ou métadonnées : instructions de configuration du fournisseur de services IdP ou métadonnées IdP, y compris :
- EntityDescriptor : "Émetteur du fournisseur d’identité", "identificateur AD Azure", "ID d’entité", "ID d’émetteur SAML", etc. Ce sera l’« émetteur » dans l’interface utilisateur MyGeotab.
- SingleSignOnService : "URL d’authentification unique du fournisseur d’identité", "URL d’ouverture de session", "URL SSO », etc. Spécifiquement pour la liaison HTTP-Redirect si différente de HTTP-POST). Ceci est la valeur de l’URL de connexion dans l’interface utilisateur MyGeotab.
- Copie du certificat X509 à téléverser dans Geotab.
- L’assertion doit être envoyée à MyGeotab dans un formulaire standard HTTP POST-de liaison SAML à l’ACS suivant :
- Éléments spécifiques à l’application tels que configurés dans l’IdP:
- Un lien permettant à l’utilisateur d’accéder directement à l’application à partir d’un emplacement à l’extérieur de l’IdP. Peut être appelé « URL d’accès utilisateur », « lien intégré à l’application », etc. Utilisé lors de la confirmation des fonctionnalités créées par IdP et par SP.
- URL du service à la clientèle des applications (ACS) telle qu’entrée. Normalement https://my.geotab.com/apiv1/authenticateSaml?redirect=true.
- ID d’entité/URL de restriction d’audience telle qu’entrée. Normalement https://my.geotab.com/.
- Construction de l’attribut/assertion nommé « Courriel », avec le format du nom et la valeur comme propriété de l’utilisateur (user.email, user.login, user.userprincipalname, etc.)
- Éléments spécifiques à l’utilisateur d’essai :
- Nom d’utilisateur Geotab identifié comme « utilisateur (courriel) » dans l’IU MyGeotab.
- « Type d’authentification : » vérifié en tant que SAML.
- « Émetteur du certificat : » vérifié comme correspondance pour EntityDescriptor à partir de 3a ci-dessus.
- Identifiant d’utilisateur principal dans l’IdP (« nom d’utilisateur », « nom d’utilisateur principal », « nom d’utilisateur », etc.). Identité entrée pour l’ouverture de session IdP.
- Valeur de la propriété de l’utilisateur sélectionnée pour l’envoi en tant qu’attribut « courriel » pour la partie 4a ci-dessus.
- Confirmation de l’affectation de l’utilisateur à l’application dans l’IdP.
- L’utilisateur d’essai doit avoir une extension de traceur SAML ou Add-On installé sur le navigateur à utiliser pour les essais.
✱ REMARQUE : les liens sont disponibles dans la FAQ.