API Enterprise SSO

L’Enterprise SSO (Single Sign-On) permet aux membres de l’organisation de s’authentifier en utilisant leur identity provider d’entreprise existant plutôt qu’un nom d’utilisateur et un mot de passe. Auris supporte à la fois le protocole SAML 2.0 et OIDC, basés sur le brokering IdP de Keycloak.

Le flux SSO fonctionne ainsi :

1. Un admin crée une connexion SSO pour une organisation, en fournissant la configuration IdP (métadonnées SAML ou URL de discovery OIDC).
2. L’admin ajoute et vérifie un ou plusieurs domaines email (ex. acme-corp.com) via des enregistrements DNS TXT.
3. Une fois la connexion activée, les utilisateurs avec un email de domaine vérifié sont automatiquement redirigés vers l’IdP à la connexion.
4. Lors de la première connexion SSO, Auris effectue le provisionnement JIT (Just-In-Time) — crée le compte utilisateur, le lie à l’organisation et émet les tokens Auris, le tout de manière transparente.

Tous les endpoints SSO admin requièrent l’en-tête x-tenant et un token Bearer valide.

Connexions SSO

Réponse de succès

{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "name": "Acme Corporate IdP",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml-abc123",
      "domains": ["acme-corp.com", "acme.io"],
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-02-01T14:30:00Z"
    }
  ]
}

États de la connexion SSO :

Configuration SAML 2.0

Pour SSO basé sur SAML, fournis les métadonnées de l’Identity Provider. Tu peux fournir un metadataUrl (recommandé — Auris le récupère et l’analyse automatiquement) ou fournir les champs individuels manuellement.

Corps de la requête — SAML avec URL de métadonnées

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Corps de la requête — SAML avec configuration manuelle

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----"
  }
}

Configuration OIDC

Corps de la requête — OIDC

{
  "type": "oidc",
  "name": "Acme OIDC Provider",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client-id",
    "clientSecret": "auris-sp-client-secret"
  }
}

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Codes d’erreur

Activer et Désactiver

Codes d’erreur

Vérification de Domaine

La vérification de domaine prouve que tu contrôles un domaine email avant d’activer la redirection automatique SSO pour ce domaine. La vérification se fait via un enregistrement DNS (TXT ou CNAME). Une fois un domaine vérifié, tout utilisateur se connectant avec une adresse email sur ce domaine est automatiquement redirigé vers le provider SSO de l’organisation.

Réponse de succès

{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z",
      "createdAt": "2025-01-20T10:00:00Z"
    }
  ]
}

États de vérification du domaine :

Corps de la requête

{
  "domain": "acme-corp.com"
}

Réponse de succès

{
  "ok": true,
  "data": {
    "id": "dom_ghi789",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-mno345pqr678",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-mno345pqr678"
    }
  }
}

Codes d’erreur

Endpoints SSO Publics

Ces endpoints sont utilisés par la page de connexion hébergée d’Auris et le SDK pour exécuter le flux SSO. Ils ne requièrent pas d’authentification.

Corps de la requête

{
  "email": "[email protected]"
}

Réponse — SSO disponible

{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/acme-saml-abc123"
  }
}

Réponse — aucun SSO

{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

La réponse est toujours 200 OK quelle que soit la configuration SSO du domaine, pour prévenir la divulgation d’informations sur quelles organisations utilisent SSO.

Cet endpoint est une redirection navigateur, pas un appel API. Le flux typique :

1. Le client détecte SSO via POST /api/auth/sso/detect
2. Le client redirige le navigateur vers le loginUrl de la réponse de détection
3. Auris redirige vers la page de connexion de l’IdP
4. L’utilisateur s’authentifie auprès de l’IdP
5. L’IdP redirige vers le callback d’Auris
6. Auris émet les tokens et redirige vers l’URL callback de l’application

Provisionnement JIT (Just-In-Time)

Lorsqu’un utilisateur s’authentifie via SSO pour la première fois et n’a pas encore de compte Auris, Auris automatiquement :

1. Crée un nouveau compte utilisateur en utilisant les attributs de l’assertion SSO (email, prénom, nom)
2. Lie l’utilisateur à l’organisation propriétaire de la connexion SSO
3. Assigne le rôle membre par défaut (MEMBER)
4. Émet des tokens d’accès et de rafraîchissement Auris standard

Lors des connexions suivantes, l’enregistrement utilisateur existant est mis en correspondance par email et les tokens sont émis directement.

Gestion des Erreurs

Si l’assertion SSO n’est pas valide, l’utilisateur est redirigé vers le callback avec des paramètres d’erreur :

https://app.votredomaine.com/callback?error=sso_failed&error_description=SAML+assertion+validation+failed&state=original_state

Référence des Permissions

Notes d’Implémentation

Brokering IdP Keycloak : Auris crée et gère les configurations d’Identity Provider Keycloak. Chaque connexion SSO correspond à un IdP Keycloak avec un alias unique.

Rotation des Certificats : Pour les connexions SAML, mets à jour le champ certificate dans la configuration de la connexion lorsque l’IdP fait tourner son certificat de signature. Auris ne détecte pas automatiquement les changements de certificat.

Cache Discovery OIDC : Lors de l’utilisation d’OIDC, Auris met en cache le document de discovery. Le cache expire après environ 1 heure.

Corrélés

• Guide Enterprise SSO — Configuration des connexions SAML 2.0 et OIDC
• Single Sign-On — Procédure d’intégration SSO
• Enterprise SSO — Configure les connexions SSO depuis la Console
• API Organisations — Endpoints des organisations auxquelles appartiennent les connexions SSO