DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Authentification

Cette page explique les trois types d'informations d'identification utilisés par Fundamentum et quand utiliser chacun. Elle montre aussi comment obtenir un token et appeler la Public API avec celui-ci.

Qui Informations d'identification Utilisées avec
Personnes Un compte Connect, connecté via le navigateur Hub, CLI fun, Public API
Intégrations, scripts et CI Un token de compte de service ou une clé API personnelle Public API, CLI fun
Appareils Un fichier de token de registre, une paire de clés d'appareil ou une clé de provisionnement Devices API et broker MQTT uniquement

Les tokens d'utilisateur et d'intégration ne fonctionnent jamais sur la Devices API. Les informations d'identification des appareils ne fonctionnent jamais sur la Public API.

Avant de commencer

Utilisateurs : se connecter avec Connect

Accès des utilisateurs et des applications : se connecter avec Connect, puis appeler la Public API avec un token

Connect est le service d'identité de Fundamentum. Vous vous connectez à https://oauth.fundamentum-iot.com/authx/login avec votre mot de passe, ou avec Google ou Microsoft. Le Hub et les autres applications Fundamentum vous y redirigent et reçoivent un token via le flux de code d'autorisation OAuth 2.0.

Se connecter depuis la ligne de commande

fun login vous connecte via le navigateur et stocke le token pour les commandes fun suivantes :

fun login

La CLI demande un nom de contexte et les endpoints. Les valeurs par défaut, https://api.fundamentum-iot.com et https://oauth.fundamentum-iot.com, conviennent à Fundamentum Cloud. La CLI ouvre ensuite votre navigateur et enregistre le token dans contexts.json, dans son répertoire de configuration (fun config dir affiche le chemin).

Vérifiez avec quel compte vous êtes connecté et quels rôles vous avez :

fun api v2 users introspect-user

Se connecter depuis votre propre application

Si vous développez une application qui connecte des utilisateurs, enregistrez-la comme client OAuth dans Connect. Votre organisation peut enregistrer deux types de clients :

Utilisez le flux de code d'autorisation. N'utilisez pas le flux implicite dans les nouvelles applications.

Intégrations : comptes de service et clés API

Pour tout ce qui s'exécute sans personne devant, comme un backend, un script ou une tâche CI, utilisez un token qui ne nécessite pas de navigateur.

Créer un compte de service

Dans Connect, ouvrez Service Accounts → Create Service Account, saisissez un identifiant d'au moins 3 caractères, attribuez un rôle, puis créez un token sous API Keys.

Vous pouvez faire la même chose avec la CLI fun :

  1. Créez le compte de service :

    fun api v2 service-accounts create-service-account --project-id <project-id> --body '{"name": "my-integration"}'

  2. Accordez-lui un rôle. Le rôle doit pouvoir être attribué sur le projet du compte de service :

    fun api v2 service-accounts create-service-account-role --project-id <project-id> \
  --service-account-id <service-account-id> --body '{"role_id": <role-id>}'

  3. Créez un token :

    fun api v2 service-accounts create-service-account-token --project-id <project-id> \
  --service-account-id <service-account-id> --body '{"name": "ci"}'

    La réponse contient le token dans data.accessToken. Stockez-le immédiatement dans votre gestionnaire de secrets : il n'est affiché qu'une seule fois. Si data.token.expires_at vaut null, le token n'expire pas.

Pour révoquer un token, listez les tokens avec list-service-account-tokens, puis supprimez-en un avec delete-service-account-token --token-id <token-id>.

Utiliser un token avec la CLI fun

Pour exécuter des commandes fun api avec un token de compte de service, par exemple en CI, définissez deux variables d'environnement au lieu d'exécuter fun login :

export FUN_CONTEXT_FUNDAMENTUM_IOT_ENDPOINT=https://api.fundamentum-iot.com
export FUN_CONTEXT_API_KEY=$TOKEN
fun api v1 registry list-registries --project-id <project-id>

La CLI affiche Using anonymous context from environment lorsqu'elle détecte ces variables.

Appeler la Public API

Chaque requête vers la Public API, en v1 comme en v2, transmet le token dans l'en-tête Authorization. Le même token fonctionne pour les deux versions.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.fundamentum-iot.com/v2/users/introspect

Les réponses réussies sont encapsulées sous la forme {"status": "success", "data": ...}, et les erreurs sous la forme {"status": "error", "message": ...}.

Statut Signification Que faire
401 Le token est absent, expiré ou appartient à un autre environnement. Reconnectez-vous, ou vérifiez le token et l'endpoint.
403 Le token est valide, mais ses rôles n'autorisent pas cette opération sur ce projet. Le message indique l'autorisation manquante, par exemple User <name> is not authorized to perform <container>:<action> in project <project-id>. Demandez à un gestionnaire de projet d'accorder un rôle disposant de cette autorisation.

Les autorisations sont limitées à un périmètre : un token disposant d'un rôle sur un projet est refusé sur un autre projet.

Vous pouvez parcourir l'API et essayer des requêtes dans Swagger UI à /v1/docs et /v2/docs. Les spécifications lisibles par machine se trouvent à /v1/api/swagger.json et /v2/api/openapi.json sur le même hôte. Consultez la référence de la Public API.

Appareils : informations d'identification des appareils

Sécurité des appareils : chaque appareil se connecte avec sa propre clé

Les appareils s'authentifient auprès de la Devices API (https://devices.fundamentum-iot.com) et du broker MQTT, jamais avec des tokens d'utilisateur ou de compte de service.

La spécification de la Devices API se trouve à https://devices.fundamentum-iot.com/api/v3/swagger.json, consultable dans Swagger UI. Consultez la référence de la Devices API v3.

Étapes suivantes