Login externe - API

Avec le login externe, vous pouvez authentifier les utilisateurs dans une base d’utilisateurs existante via un appel API. Vous implémentez l’API ; FoxIDs l’appelle avec un nom d’utilisateur et un mot de passe, et l’API valide la combinaison et renvoie un succès ou un échec.
Utilisez une méthode d’authentification Login externe lorsque vous souhaitez exploiter un magasin d’utilisateurs existant comme source d’authentification dans FoxIDs. Après une connexion réussie, vous pouvez créer des utilisateurs externes et éventuellement afficher une boîte de dialogue pour capturer par ex. le nom ou l’e-mail.

Avec le temps, vous pouvez migrer les utilisateurs vers FoxIDs et supprimer progressivement l’API externe et le magasin d’utilisateurs.

Pour un aperçu des concepts d’utilisateurs (utilisateurs internes, utilisateurs externes et magasins d’utilisateurs externes), voir la vue d’ensemble des utilisateurs.

Le login externe prend en charge deux types d’identifiants utilisateur (nom d’utilisateur) :

• E-mail - l’e-mail de l’utilisateur
• Texte - un nom d’utilisateur texte libre

Si vous choisissez le type texte, le format n’est pas validé dans FoxIDs (formats mixtes autorisés, y compris les e-mails).
La home realm discovery (HRD) basée sur le domaine n’est disponible qu’avec le type e-mail.

UI de login externe par défaut avec un nom d’utilisateur basé sur le texte :

L’UI peut être personnalisée.

Implémenter l’API

Vous devez implémenter une API simple que FoxIDs appelle pour chaque requête d’authentification (voir exemple).

L’API a une URL de base ; la fonctionnalité est regroupée en dossiers. Actuellement, seul le dossier authentication (valider nom d’utilisateur/mot de passe) est pris en charge.
Des dossiers pour le changement de mot de passe et la création d’utilisateur pourront être ajoutés plus tard.

Si l’URL de base est https://somewhere.org/mystore, l’endpoint d’authentification est : https://somewhere.org/mystore/authentication

FoxIDs Cloud appelle votre API depuis l’IP 57.128.60.142.
Les IP peuvent changer ou être étendues.

Requête

Sécurisée avec l’authentification HTTP Basic : nom d’utilisateur external_login, mot de passe = secret configuré.

L’appel est un HTTP POST avec un corps JSON.

Vous pouvez configurer des paramètres supplémentaires ; ils sont inclus dans la charge utile JSON.

Requête pour le type e-mail :

{
  "usernameType": 100,
  "username": "user1@somewhere.org",
  "password": "testpass1"
}

Requête pour le type nom d’utilisateur texte :

{
  "usernameType": 200,
  "username": "user1",
  "password": "testpass1"
}

Codes de type de nom d’utilisateur :

• email = 100
• text = 200

Réponse

Succès
En cas de succès, l’API doit retourner le code HTTP 200 et, de manière optionnelle, une liste de claims pour l’utilisateur authentifié.

Par exemple, le sub de l’utilisateur (ID unique / nom d’utilisateur), prénom, nom, e-mail et éventuellement un rôle :

{
  "claims": [
    { "type": "sub", "value": "somewhere/user2" },
    { "type": "given_name", "value": "Joe" },
    { "type": "family_name", "value": "Smith" },
    { "type": "email", "value": "user2@somewhere.org" },
    { "type": "role", "value": "some_access" }
  ]
}

Erreur
L’API doit retourner le code HTTP 401 (Unauthorized) et une error (requise) si l’authentification Basic est rejetée. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

{
  "error": "invalid_api_id_secret",
  "ErrorMessage": "Invalid API ID or secret"
}

L’API doit retourner le code HTTP 400, 401 ou 403 et une error (requise) si la combinaison nom d’utilisateur/mot de passe est rejetée. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

{
  "error": "invalid_username_password",
  "ErrorMessage": "Invalid username or password."
}

Si d’autres erreurs surviennent, l’API doit retourner le code HTTP 500 ou un autre code d’erreur approprié.
Il est recommandé d’ajouter un message d’erreur technique ErrorMessage pour le diagnostic (il est seulement consigné ; jamais affiché à l’utilisateur final).

Exemple d’API

L’exemple ExternalLoginApiSample montre comment implémenter l’API en ASP.NET Core.

Collection Postman external-login-api.postman_collection.json pour appeler et tester votre API avec Postman.

Configurer

Configurez une méthode d’authentification login externe par API dans FoxIDs Control Client.

1. Allez dans l’onglet Authentication
2. Cliquez sur New authentication
3. Sélectionnez Show advanced
4. Sélectionnez External API Login
5. Ajoutez le Name
6. Sélectionnez Username type (par ex. Text)
7. Ajoutez l’URL de base de l’API sans le dossier authentication dans API URL
8. Ajoutez le API secret
9. Cliquez sur Create

Optionnellement, cliquez sur Show advanced en haut à droite de la section de configuration pour personnaliser l’UI de login.