Docs
Powered by

Authentification

Cette page décrit comment utiliser l'API d'authentification de GestSIS pour créer et gérer les tokens d'accès et de rafraîchissement.

Vue d'ensemble

L'API d'authentification GestSIS utilise un système de tokens JWT (JSON Web Tokens) pour sécuriser les accès. Deux types de tokens sont utilisés :

  • Access Token : Token de courte durée (8 heures) utilisé pour authentifier les requêtes API
  • Refresh Token : Token de longue durée (30 jours) utilisé pour renouveler l'access token

Base URL

L'API d'authentification est accessible via :

http://auth.gestsis.ch/api/v1

En production, l'URL sera différente selon votre configuration.

1. Connexion (Login)

Endpoint

POST /api/v1/login

Description

Permet à un utilisateur de se connecter et d'obtenir un access token et un refresh token.

Corps de la requête

{
  "email": "utilisateur@example.com",
  "password": "motdepasse"
}

Réponse en cas de succès (200 OK)

{
  "message": "Successful login",
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refreshToken": "a1b2c3d4e5f6g7h8",
  "user": {
    "id": 1,
    "name": "Jean Dupont",
    "email": "utilisateur@example.com",
    "email_verified_at": "2025-01-01T10:00:00.000000Z",
    "created_at": "2025-01-01T10:00:00.000000Z",
    "updated_at": "2025-01-01T10:00:00.000000Z"
  }
}

Réponse en cas d'erreur (401 Unauthorized)

{
  "error": "invalid credentials"
}

Ou en cas de validation échouée :

{
  "error": {
    "email": ["The email field is required."],
    "password": ["The password field is required."]
  }
}

Exemple avec cURL

curl -X POST http://auth.gestsis.ch/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "utilisateur@example.com",
    "password": "motdepasse"
  }'

Exemple avec JavaScript (fetch)

const response = await fetch('http://auth.gestsis.ch/api/v1/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'utilisateur@example.com',
    password: 'motdepasse'
  })
});

const data = await response.json();

if (response.ok) {
  console.log('Access Token:', data.accessToken);
  console.log('Refresh Token:', data.refreshToken);
  
  // Stocker les tokens (par exemple dans localStorage)
  localStorage.setItem('accessToken', data.accessToken);
  localStorage.setItem('refreshToken', data.refreshToken);
} else {
  console.error('Erreur de connexion:', data.error);
}

2. Rafraîchir le Token (Refresh Token)

Endpoint

POST /api/v1/refresh-token

Description

Permet de renouveler l'access token en utilisant le refresh token. Le refresh token est à usage unique : après utilisation, il est détruit et un nouveau refresh token est généré.

Corps de la requête

{
  "token": "a1b2c3d4e5f6g7h8"
}

Réponse en cas de succès (200 OK)

{
  "message": "Successful login",
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refreshToken": "x9y8z7w6v5u4t3s2",
  "user": {
    "id": 1,
    "name": "Jean Dupont",
    "email": "utilisateur@example.com",
    "email_verified_at": "2025-01-01T10:00:00.000000Z",
    "created_at": "2025-01-01T10:00:00.000000Z",
    "updated_at": "2025-01-01T10:00:00.000000Z"
  }
}

Réponse en cas d'erreur (401 Unauthorized)

{
  "error": "Refresh token expired"
}

Ou en cas de validation échouée :

{
  "error": {
    "token": ["The token field is required."]
  }
}

Exemple avec cURL

curl -X POST http://auth.gestsis.ch/api/v1/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6g7h8"
  }'

Exemple avec JavaScript (fetch)

const refreshToken = localStorage.getItem('refreshToken');

const response = await fetch('http://auth.gestsis.ch/api/v1/refresh-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    token: refreshToken
  })
});

const data = await response.json();

if (response.ok) {
  // Mettre à jour les tokens stockés
  localStorage.setItem('accessToken', data.accessToken);
  localStorage.setItem('refreshToken', data.refreshToken);
  
  console.log('Tokens renouvelés avec succès');
} else {
  console.error('Erreur de rafraîchissement:', data.error);
  // Si le refresh token a expiré, rediriger vers la page de connexion
  if (data.error === 'Refresh token expired') {
    window.location.href = '/login';
  }
}

Utilisation des Tokens

Structure de l'Access Token

L'access token est un JWT (JSON Web Token) signé avec RSA-256 qui contient les informations suivantes :

Structure complète

{
  "iss": "GestSIS_Auth",
  "aud": "GestSIS_API",
  "iat": 1702290000,
  "nbf": 1702289990,
  "exp": 1702318800,
  "data": {
    "id": 1,
    "admin": false,
    "validated": true,
    "pseudo": "Jean Dupont",
    "email": "jean.dupont@example.com",
    "permissions": {
      "test": [
        "intervention.lecture",
        "intervention.modification",
        "sapeur.lecture"
      ],
      "hs": [
        "intervention.lecture"
      ]
    },
    "mobiles": [
      "test",
      "hs"
    ],
    "sapeurs": {
      "test": 42,
      "hs": 108
    }
  }
}

Description des champs

Headers JWT standard :

  • iss (Issuer) : GestSIS_Auth - Émetteur du token
  • aud (Audience) : GestSIS_API - Destinataire du token
  • iat (Issued At) : Timestamp UNIX de la création du token
  • nbf (Not Before) : Timestamp UNIX à partir duquel le token est valide (10 secondes avant iat)
  • exp (Expiration) : Timestamp UNIX d'expiration (8 heures après iat)

Données utilisateur (data) :

  • id : Identifiant unique de l'utilisateur dans GestSIS_Auth
  • admin : Booléen indiquant si l'utilisateur est administrateur (a tous les droits sur tous les SIS)
  • validated : Booléen indiquant si l'email de l'utilisateur a été vérifié
  • pseudo : Nom d'affichage de l'utilisateur
  • email : Adresse email de l'utilisateur

Données multi-SIS :

  • permissions : Objet où chaque clé est l'api_key d'un SIS, contenant un tableau des permissions pour ce SIS
    • Exemple : {"test": ["intervention.lecture", "sapeur.modification"]}
    • Si l'utilisateur est admin, toutes les clés SIS contiennent ["admin"]
  • mobiles : Tableau simple contenant les api_key des SIS pour lesquels l'utilisateur peut recevoir des alertes mobiles
    • Exemple : ["test", "hs"]
  • sapeurs : Objet où chaque clé est l'api_key d'un SIS, contenant l'ID du sapeur associé à l'utilisateur dans ce SIS
    • Exemple : {"test": 42, "hs": 108}

Architecture multi-tenant

Important : Les permissions, mobiles et sapeurs sont organisés par SIS. Cela permet à un utilisateur :

  • D'avoir des permissions différentes selon le SIS
  • D'être sapeur dans plusieurs SIS avec des IDs différents
  • De recevoir des alertes mobiles uniquement pour certains SIS

Exemple : Un utilisateur peut être chef d'intervention dans le SDIS Jura mais simple sapeur dans le SDIS Neuchâtel.

Utiliser l'Access Token dans les requêtes API

Pour authentifier une requête API, incluez l'access token dans le header Authorization :

Authorization: Bearer {accessToken}

Exemple complet d'utilisation

// 1. Connexion
const loginResponse = await fetch('http://auth.gestsis.ch/api/v1/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'utilisateur@example.com',
    password: 'motdepasse'
  })
});

const loginData = await loginResponse.json();
localStorage.setItem('accessToken', loginData.accessToken);
localStorage.setItem('refreshToken', loginData.refreshToken);

// 2. Utiliser l'access token pour une requête protégée
const apiResponse = await fetch('http://apis.gestsis.ch/api/v1/protected-resource', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('accessToken')}`
  }
});

// 3. Si le token a expiré (erreur 401), le rafraîchir
if (apiResponse.status === 401) {
  const refreshResponse = await fetch('http://auth.gestsis.ch/api/v1/refresh-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: localStorage.getItem('refreshToken')
    })
  });
  
  const refreshData = await refreshResponse.json();
  localStorage.setItem('accessToken', refreshData.accessToken);
  localStorage.setItem('refreshToken', refreshData.refreshToken);
  
  // Réessayer la requête avec le nouveau token
  const retryResponse = await fetch('http://apis.gestsis.ch/api/v1/protected-resource', {
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('accessToken')}`
    }
  });
}

Bonnes Pratiques

Sécurité

  1. Ne jamais exposer les tokens : Ne jamais afficher les tokens dans les logs ou les messages d'erreur
  2. Stockage sécurisé : Utiliser des mécanismes sécurisés pour stocker les tokens (httpOnly cookies pour le web)
  3. HTTPS uniquement : Toujours utiliser HTTPS en production pour éviter l'interception des tokens
  4. Refresh token à usage unique : Le système utilise des refresh tokens à usage unique pour prévenir le vol de tokens

Gestion des Tokens

  1. Renouvellement automatique : Implémenter un mécanisme de renouvellement automatique avant l'expiration
  2. Gestion des erreurs : Rediriger vers la page de connexion si le refresh token a expiré
  3. Déconnexion : Supprimer les tokens stockés lors de la déconnexion
// Fonction utilitaire pour gérer le renouvellement automatique
async function fetchWithAuth(url, options = {}) {
  const token = localStorage.getItem('accessToken');
  
  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${token}`
    }
  });
  
  // Si le token a expiré, le rafraîchir et réessayer
  if (response.status === 401) {
    const refreshToken = localStorage.getItem('refreshToken');
    const refreshResponse = await fetch('http://auth.gestsis.ch/api/v1/refresh-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: refreshToken })
    });
    
    if (refreshResponse.ok) {
      const data = await refreshResponse.json();
      localStorage.setItem('accessToken', data.accessToken);
      localStorage.setItem('refreshToken', data.refreshToken);
      
      // Réessayer la requête originale
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${data.accessToken}`
        }
      });
    } else {
      // Refresh token expiré, rediriger vers login
      window.location.href = '/login';
      throw new Error('Session expirée');
    }
  }
  
  return response;
}

Durée de vie des Tokens

  • Access Token : 8 heures
  • Refresh Token : 30 jours
  • Reset Token : 1 heure
  • Confirmation Token : 30 jours

Autres Endpoints d'Authentification

Inscription

POST /api/v1/register

Permet de créer un nouveau compte utilisateur.

Confirmation d'Email

POST /api/v1/confirmer-email

Permet de confirmer l'adresse email d'un nouvel utilisateur.

Mot de Passe Oublié

POST /api/v1/forgotten-password

Demande un lien de réinitialisation de mot de passe.

Réinitialiser le Mot de Passe

POST /api/v1/reset-password

Réinitialise le mot de passe avec un token de réinitialisation.

Changer le Mot de Passe

POST /api/v1/change-password

Permet à un utilisateur authentifié de changer son mot de passe.

© Copyright 2026. All rights reserved.