Aller au contenu principal

Provisionnement d’utilisateurs SCIM 2.0

fremforge implémente SCIM 2.0 (RFC 7643/7644) afin que votre IdP puisse provisionner automatiquement des utilisateurs Forgejo dans votre organisation : création à l’embauche, mise à jour lorsqu’un attribut change, désactivation au départ. Fini les « Jean vient de partir, quelqu’un a-t-il pensé à révoquer son accès à fremforge ? » La désactivation dans votre IdP fait basculer l’indicateur SCIM active, et fremforge désactive l’utilisateur Forgejo dans la minute.

SCIM complète OIDC ; il ne le remplace pas. SCIM est le protocole de provisionnement. Il pousse les fiches utilisateur vers fremforge. Les utilisateurs se connectent toujours par le processus de connexion que vous configurez séparément (OIDC). La plupart des petites équipes n’ont pas du tout besoin de SCIM. La gestion manuelle des utilisateurs dans l’interface de Forgejo suffit. Ne mettez SCIM en place que lorsque « nous venons d’embaucher cinq personnes, quelqu’un a-t-il pensé à les ajouter à fremforge ? » devient un vrai problème.

Cette page est le guide pratique pour connecter Okta, Entra, Authentik ou n’importe quel IdP SCIM 2.0. Prêt à l’emploi pour les principaux IdP ; fonctionne avec tout client SCIM 2.0.

Fonctionnalités

FonctionnalitéPrise en charge
POST /Users (provisionnement)✓
GET /Users/:id (consultation)✓
GET /Users (liste, avec filtre userName eq)✓
PATCH /Users/:id (opérations RFC 7644 §3.5.2)✓
PUT /Users/:id (remplacement complet)✓
DELETE /Users/:id (désactivation, pas de suppression définitive)✓
GET /ServiceProviderConfig✓
GET /ResourceTypes, GET /Schemas (découverte)✓
POST /Groups / GET /Groups / GET /Groups/:id✓
PATCH /Groups/:id (ajout/retrait de membres)✓
PUT /Groups/:id (remplacement complet)✓
DELETE /Groups/:id (suppression de l’équipe Forgejo + suppression logique de la correspondance)✓
Filtre de groupe displayName eq✓
Points de terminaison bulk✗ Pas encore
Opérateurs de filtre autres que eq✗ Utilisez plusieurs requêtes
Groupes imbriqués✗ Forgejo ne les modélise pas

Configuration

Étape 1 : activer SCIM dans fremforge

  1. Administration de l’organisation → SSO → Provisionnement d’utilisateurs SCIM 2.0 → cliquez sur Activer SCIM et créer un jeton.
  2. La page qui s’affiche après le clic montre le jeton bearer une seule fois. Copiez-le ; vous en aurez besoin pour votre IdP. Le jeton n’est jamais placé dans une URL, et fremforge ne l’affiche plus : seul son hachage SHA-256 est stocké. Si vous le perdez, cliquez sur Renouveler le jeton pour en créer un nouveau.
  3. Notez l’URL de base affichée sur la page ; elle ressemble à ceci :
    https://frem.sh/<your-org>/scim/v2

Étape 2 : connecter votre IdP

Okta

  1. Applications → Create App Integration → SCIM 2.0 Test App (Header Auth).
  2. Onglet Provisioning → Configure API Integration :
    • Base URL : https://frem.sh/<your-org>/scim/v2
    • Authentication Mode : HTTP Header
    • HTTP Header Name : Authorization
    • HTTP Header Value : Bearer <token from step 1>
  3. Test API Credentials doit indiquer une réussite.
  4. Onglet To App → activez Create, Update, Deactivate.
  5. Affectez des utilisateurs à l’application. Okta les enverra à fremforge par POST.

Microsoft Entra (Azure AD)

  1. Enterprise Applications → New application → Non-gallery → nommez-la « fremforge ».
  2. Provisioning → Get started → mode = Automatic :
    • Tenant URL : https://frem.sh/<your-org>/scim/v2
    • Secret Token : <token from step 1> (collez-le sans le préfixe Bearer ; Entra l’ajoute)
  3. Test Connection → coche verte.
  4. Mappings → utilisez le mappage User par défaut ; le seul champ qu’il faut souvent ajuster est userName, à définir sur userPrincipalName (l’identifiant de connexion de l’utilisateur, en forme d’adresse e-mail).
  5. Save & Start provisioning.

Authentik

  1. Applications → Providers → Create → SCIM Provider :
    • URL : https://frem.sh/<your-org>/scim/v2
    • Token : <token from step 1>
  2. Associez le fournisseur à votre application ; affectez un groupe ; les utilisateurs de ce groupe seront provisionnés.

IdP SCIM 2.0 générique

Tout client qui prend en charge la forme standard Authorization: Bearer <token> sur une URL de base SCIM 2.0 fonctionne. fremforge annonce ses fonctionnalités à l’adresse :

GET /<your-org>/scim/v2/ServiceProviderConfig
  • examinez cette réponse pour vérifier ce qui est pris en charge avant l’intégration.

Ce qui se passe lors du provisionnement

Lorsque votre IdP envoie un utilisateur par POST :

  1. fremforge crée un utilisateur Forgejo (nom d’utilisateur dérivé du userName SCIM ; les noms en forme d’adresse e-mail sont normalisés selon les règles [a-z0-9-] de Forgejo, par exemple alice@acme.example → alice-acme-example).
  2. L’utilisateur est ajouté à l’équipe Members par défaut de l’organisation. Il n’est PAS promu propriétaire. La promotion au rang d’administrateur reste du ressort de l’opérateur.
  3. L’utilisateur se connecte par votre source d’authentification OIDC existante (configurée séparément sur la page SSO). SCIM crée la fiche utilisateur ; le processus de connexion côté IdP le connecte.
  4. fremforge enregistre une ligne audit_events avec l’action scim.user.create, visible dans l’onglet d’administration Journal d’audit.

Lorsque votre IdP désactive un utilisateur (PATCH active=false ou DELETE) :

  1. fremforge définit prohibit_login=true sur l’utilisateur Forgejo. Les sessions sont révoquées et les connexions futures refusées.
  2. Les clés SSH de l’utilisateur restent dans Forgejo (elles ne permettent pas de pousser, car l’utilisateur est verrouillé).
  3. L’appartenance à l’organisation est conservée pour la piste d’audit. Pour le retirer définitivement, un administrateur de l’organisation clique sur Remove from org dans l’interface de Forgejo.

Provisionnement des groupes

Lorsque votre IdP crée un groupe SCIM, fremforge :

  1. Crée une équipe Forgejo dans l’organisation de votre tenant. Le nom de l’équipe est dérivé du displayName du groupe (normalisé selon les règles [a-z0-9_-] de Forgejo, 30 caractères au maximum).
  2. Enregistre la correspondance dans scim_groups afin que les opérations PATCH/PUT/DELETE ultérieures pointent vers la même équipe Forgejo.
  3. Accepte les opérations PATCH sur members avec op=add / op=remove (RFC 7644 §3.5.2 + la forme abrégée members[value eq "<id>"]).
  4. DELETE /Groups/:id supprime l’équipe Forgejo sous-jacente. La ligne en base de données fait l’objet d’une suppression logique (deleted_at), de sorte que la correspondance externalId↔équipe survit à la recréation du même groupe IdP.

Par défaut, chaque équipe Forgejo donne à ses membres un accès en écriture à tous les dépôts de l’organisation (un groupe « Backend » obtient donc un accès en écriture à chaque dépôt). Un accès plus fin, dépôt par dépôt, se configure côté opérateur dans les paramètres d’équipe de Forgejo ; le SCIM de fremforge ne pousse pas d’autorisations limitées à un dépôt, car SCIM 2.0 ne définit aucun standard pour les attributs d’autorisation sur les dépôts.

Limites au lancement :

  • L’e-mail est la clé de l’utilisateur. SCIM identifie les utilisateurs par externalId, dont nous attendons qu’il corresponde à l’adresse e-mail principale de l’utilisateur. Cela s’aligne sur notre paramètre OIDC username_claim existant.
  • Pas de groupes imbriqués. Le modèle d’équipes de Forgejo est plat (un utilisateur est dans une équipe ou n’y est pas). Les hiérarchies de groupes imbriqués de votre IdP sont aplaties : un utilisateur de Engineering → Backend → API devient membre des trois équipes Forgejo correspondantes.

Rotation du jeton

Les jetons bearer SCIM doivent être renouvelés régulièrement. fremforge prend en charge une rotation sans interruption grâce à une période à deux jetons :

  1. Administration de l’organisation → SSO → SCIM → cliquez sur Renouveler le jeton.
  2. Le nouveau jeton s’affiche une seule fois, sur la page qui s’affiche après le clic (jamais dans une URL) ; copiez-le.
  3. Le jeton précédent reste valide jusqu’à ce que vous cliquiez sur Supprimer le jeton précédent. Cette période permet à votre IdP de passer au nouveau jeton sans perdre d’appel de provisionnement en cours.
  4. Mettez à jour votre IdP avec le nouveau jeton.
  5. Après avoir vérifié que le nouveau jeton fonctionne (contrôlez l’état du provisionnement côté IdP pendant quelques cycles), cliquez sur Supprimer le jeton précédent.

Fréquence recommandée : tous les 90 jours, ou lors de changements de personnel qui justifient une rotation des identifiants.

Désactiver SCIM

Administration de l’organisation → SSO → SCIM → cliquez sur Désactiver SCIM. fremforge :

  • Efface les hachages du jeton actuel et du jeton précédent (toute requête IdP en attente reçoit 401)
  • Marque la ligne enabled=false (visible dans l’audit)
  • Laisse intactes les lignes scim_users (une réactivation reprovisionne depuis votre IdP)

Les utilisateurs Forgejo eux-mêmes ne sont PAS désactivés. Si vous voulez tous les bloquer, faites-le d’abord depuis votre IdP, puis désactivez SCIM.

Dépannage

« Authorization: Bearer required » (401) sur chaque requête

Le jeton bearer n’atteint pas fremforge. Causes fréquentes :

  • Mauvais nom d’en-tête : il doit être exactement Authorization.
  • Préfixe Bearer manquant : Okta l’ajoute automatiquement ; certains clients non. Vérifiez ce que votre IdP envoie réellement avec un tcpdump ou les journaux détaillés de l’IdP.
  • Jeton révoqué : si vous avez effectué une rotation puis supprimé le précédent, l’ancien jeton n’est plus valide. Collez à nouveau le jeton actuel.

« userName is required » (400) sur un POST

Votre IdP n’associe pas userName à une valeur pertinente. Dans Entra, cela signifie souvent que l’UPN de l’utilisateur n’est pas défini ; associez userName à mail ou à un attribut similaire non vide.

Utilisateurs provisionnés, mais impossible de se connecter

SCIM ne crée que la fiche utilisateur. Le processus de connexion utilise votre source d’authentification OIDC configurée séparément. Vérifiez :

  1. Que l’utilisateur dispose d’une source d’authentification OIDC configurée sous Administration de l’organisation → SSO → Sources d’authentification.
  2. Que l’identité de l’utilisateur côté IdP (e-mail, nom principal) correspond au userName provisionné par SCIM.
  3. Que l’écran de connexion à frem.sh/user/login?redirect_to=/<your-org> affiche le bouton SSO.

Le filtre ne fonctionne pas pour email eq ou d’autres opérateurs

Nous ne prenons en charge que userName eq "<value>". Tout autre filtre renvoie une liste vide. La plupart des IdP n’ont besoin que de userName eq pour le dédoublonnage ; vérifiez dans leurs journaux de provisionnement quelles formes de filtre ils émettent, et dites-nous si vous avez besoin d’autres opérateurs (écrivez à support@frem.sh).

Piste d’audit

Chaque action pilotée par SCIM est enregistrée dans le journal d’audit de l’organisation avec actor=system (l’acteur étant « votre IdP » et non un utilisateur connecté) et l’une des actions suivantes :

  • scim.enabled / scim.disabled : actions dans l’interface opérateur
  • scim.token.rotated / scim.token.previous-dropped : actions dans l’interface opérateur
  • scim.user.create : POST de l’IdP
  • scim.user.update / scim.user.replace : PATCH/PUT de l’IdP
  • scim.user.deactivate / scim.user.reactivate : changement de l’indicateur active par l’IdP
  • scim.group.create / scim.group.update / scim.group.replace / scim.group.delete : cycle de vie des groupes côté IdP
  • les mêmes actions figurent dans la partie audit de l’archive d’export de données

Renvois