Développeurs
Spécification d'intégration SSO et SCIM
Valeurs et comportement de l'intégration OIDC, SAML 2.0 et SCIM 2.0 utiles au responsable IdP et aux développeurs.
Pour l'ordre de configuration à l'écran, voir SSO et SCIM.
Dans le tableau ci-dessous, {API} est l'adresse de l'API Keural de l'environnement que vous utilisez (par exemple, https://api.keural.ai). Pour obtenir la valeur exacte, copiez l'adresse affichée dans Gestion de l'organisation → Paramètres SSO.
Récapitulatif des valeurs d'enregistrement
| Élément | Valeur |
|---|---|
| URI de redirection OIDC | {API}/api/sso/callback |
| Démarrage de la connexion OIDC·SAML | {API}/api/sso/{orgId}/login |
| EntityID du SP SAML | {API}/api/sso/saml/metadata |
| URL ACS SAML | {API}/api/sso/saml/callback |
| URL de base SCIM | {API}/scim/v2 |
La connexion démarre toujours depuis Keural (SP-initiated). Si vous saisissez sur l'écran de connexion une adresse e-mail d'un domaine enregistré, vous êtes redirigé vers l'adresse de démarrage de la connexion. En cas de réussite, vous arrivez sur l'écran d'accueil de Keural ; en cas d'échec, vous êtes redirigé vers /login?error=sso.
OIDC
| Élément | Comportement |
|---|---|
| Flux | Authorization Code |
| Requête authorize | response_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce |
| state · nonce | À usage unique et valables 10 minutes. Si la fenêtre de connexion reste ouverte plus de 10 minutes, il faut recommencer la connexion depuis le début. |
| Échange de jeton | POST vers le token endpoint, application/x-www-form-urlencoded. L'authentification du client est client_secret_post (client_id et client_secret dans le corps). |
| Signature de l'ID token | Seul RS256 est accepté. La clé est recherchée dans jwks_uri à l'aide du kid. |
| Vérification de l'ID token | Signature, exp, aud contenant le client_id, nonce identique, et iss égal à l'Issuer URL (la / finale est ignorée). |
La revendication email de l'ID token. Si elle est absente, le userinfo endpoint est interrogé avec Authorization: Bearer <access_token> et email y est lu. | |
| Nom | La revendication name de l'ID token |
| Endpoints | Recherchés dans /.well-known/openid-configuration de l'Issuer URL. Si l'IdP ne les trouve pas, saisissez manuellement les adresses authorization, token, JWKS et userinfo dans Ouvrir les paramètres avancés. |
| Délai | 15 secondes par appel à l'IdP |
L'application IdP doit autoriser client_secret_post. Si la configuration n'autorise que client_secret_basic ou private_key_jwt, l'échange de jeton échoue.
SAML 2.0
| Élément | Comportement |
|---|---|
| Requête | Envoie un AuthnRequest via le binding HTTP-Redirect. La requête n'est pas signée. |
| Contenu de la requête | Destination=URL SSO de l'IdP, AssertionConsumerServiceURL=URL ACS, ProtocolBinding=HTTP-POST, Issuer=EntityID du SP, NameIDPolicy Format=…:nameid-format:unspecified, AllowCreate=true |
| Réponse | Binding HTTP-POST avec SAMLResponse et RelayState. Le RelayState doit être renvoyé exactement tel que Keural l'a envoyé. |
| Signature | La Response ou l'Assertion doit porter une signature valide. La clé de vérification est uniquement le certificat enregistré à l'écran. |
| Assertion | La réponse doit contenir exactement une assertion. Les assertions chiffrées (EncryptedAssertion) ne sont pas acceptées. |
| Statut | StatusCode égal à urn:oasis:names:tc:SAML:2.0:status:Success |
| Issuer | Si vous avez saisi l'EntityID de l'IdP, il doit correspondre à l'Issuer de l'assertion |
| Conditions | NotBefore et NotOnOrAfter (tolérance de 300 secondes), Audience=EntityID du SP |
| SubjectConfirmationData | Recipient=URL ACS, NotOnOrAfter (tolérance de 300 secondes), InResponseTo=ID de la requête envoyée par Keural |
Un attribut dont Name ou FriendlyName est l'une des valeurs suivantes (sans tenir compte de la casse) : email, mail, emailAddress, E-Mail-Addresses, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Sinon, le NameID contenant @ est utilisé. | |
| Nom | displayName, name, cn, http://schemas.microsoft.com/identity/claims/displayname |
| Certificat | Un certificat X.509. Au format PEM ou Base64 (DER). Pour le remplacer, saisissez le nouveau certificat et enregistrez. |
| Métadonnées | Au lieu d'importer le XML de métadonnées de l'IdP, saisissez trois valeurs : EntityID de l'IdP, URL SSO de l'IdP et certificat. |
Détermination de l'utilisateur
| Élément | Comportement |
|---|---|
| Critère d'orientation vers le SSO | Lorsque la partie de l'e-mail qui suit @ est exactement identique à une entrée de la liste des domaines e-mail (sans tenir compte de la casse). Les sous-domaines s'enregistrent séparément. |
| Recherche du compte | Recherche du compte Keural à partir de l'e-mail (en minuscules) fourni par l'IdP. |
| Si le compte n'existe pas | Si Créer automatiquement les utilisateurs lors de la première connexion (JIT) est activé, le compte est créé ; s'il est désactivé, la connexion est refusée. |
| Rattachement à l'organisation | Si la personne n'est pas membre de l'organisation, elle y entre en tant que membre. Si les sièges sont pleins ou si le compte appartient à une autre organisation, elle n'y entre pas et la connexion seule est autorisée. |
| Condition d'enregistrement du domaine e-mail | Domaine vérifié par enregistrement TXT DNS, à l'exception des domaines e-mail publics |
Vérification du domaine
| Élément | Valeur |
|---|---|
| Type d'enregistrement | TXT |
| Hôte | Le domaine enregistré tel quel (par exemple, acme.com). N'utilisez pas de sous-domaine préfixé. |
| Valeur | keural-verify=<UUID>, exactement comme affichée à l'écran |
| Moment de la vérification | Interrogé une fois, au clic sur Confirmer la vérification. |
SCIM 2.0
| Élément | Valeur |
|---|---|
| URL de base | {API}/scim/v2 |
| Authentification | Authorization: Bearer <jeton SCIM>. Le jeton commence par scim_ et n'est affiché qu'une seule fois, au moment de son émission. |
| Content-Type | Requête application/scim+json ou application/json ; réponse application/scim+json |
| Codes d'état | Les codes HTTP réels sont renvoyés. Le corps d'erreur suit le format SCIM Error (schemas, status, detail, scimType). |
Endpoints
| Méthode | Chemin | Comportement |
|---|---|---|
GET | /Users | Liste. filter=userName eq "…", startIndex (par défaut 1), count (par défaut 100, maximum 200) |
GET | /Users/{id} | Consultation d'un utilisateur |
POST | /Users | Création (201). Si l'e-mail existe déjà, renvoie 409. |
PATCH | /Users/{id} | Modifie active, displayName, name.formatted et name.givenName |
PUT | /Users/{id} | Applique displayName, name et active. Si active est omis, l'utilisateur est considéré comme actif. |
DELETE | /Users/{id} | Suspend le compte (204). Les données ne sont pas supprimées. |
GET | /Groups, /Groups/{id} | Consultation des deux groupes fixes. filter=displayName eq "…" |
PATCH | /Groups/{id} | Ajoute, retire ou remplace des membres |
GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | Consultation des fonctions prises en charge |
Attributs utilisateur
| Attribut | Usage |
|---|---|
userName | E-mail. S'il est absent, emails[0].value est utilisé. |
displayName · name.formatted · name.givenName+name.familyName | Nom affiché |
active | false suspend (bloque la connexion) ; true rétablit |
id | ID utilisateur Keural. Il figure dans la réponse. |
externalId n'est pas stocké. Pour retrouver un utilisateur depuis l'IdP, utilisez le filtre userName.
Groupes
| id | displayName | Ajout d'un membre | Retrait d'un membre |
|---|---|---|---|
keural-admins | Keural Admins | Administrateur | Membre |
keural-members | Keural Members | Membre | Aucun changement |
Le rôle du propriétaire de l'organisation n'est pas modifié par SCIM. La création et la suppression de groupes (POST·DELETE /Groups) renvoient 501. La value d'un membre de groupe est l'ID utilisateur Keural (id de /Users).
Périmètre de prise en charge
| Fonction | Prise en charge |
|---|---|
| PATCH | Oui |
| Filtres | userName eq, displayName eq |
| Bulk · tri · ETag · changement de mot de passe | Non |
Erreurs
| Statut | scimType | Cause |
|---|---|---|
400 | invalidValue | userName et emails absents |
401 | — | Jeton absent ou incorrect, ou provisionnement SCIM désactivé |
404 | — | L'utilisateur ou le groupe n'appartient pas à cette organisation |
409 | uniqueness | Un compte avec le même e-mail existe déjà, ou le nombre de sièges est dépassé |
501 | — | Création ou suppression de groupes |
Intégration des plugins et des serveurs MCP
Comment connecter votre propre serveur MCP à Keural et créer un paquet de plugin pour l'application de bureau.
FAQ
Questions et réponses sur la connexion, les limites d'utilisation, les fichiers, les réponses, les applications, les organisations et la facturation.