Desarrolladores
Especificación de integración SSO y SCIM
Valores y comportamiento necesarios para la integración OIDC, SAML 2.0 y SCIM 2.0.
Para el orden de configuración en pantalla, consulte SSO y SCIM.
En las tablas, {API} es la dirección de la API de Keural del entorno que utiliza (por ejemplo, https://api.keural.ai). Para obtener el valor exacto, use la dirección que aparece en Gestión de la organización → Configuración de SSO.
Resumen de valores de registro
| Elemento | Valor |
|---|---|
| URI de redirección OIDC | {API}/api/sso/callback |
| Inicio de sesión OIDC·SAML | {API}/api/sso/{orgId}/login |
| EntityID del SP SAML | {API}/api/sso/saml/metadata |
| URL de ACS SAML | {API}/api/sso/saml/callback |
| URL base de SCIM | {API}/scim/v2 |
El inicio de sesión siempre empieza en Keural (SP-initiated). Si introduce un correo de un dominio registrado en la pantalla de inicio de sesión, se le redirige a la dirección de inicio de sesión. Si el inicio de sesión se completa, vuelve a la pantalla principal de Keural; si falla, regresa a /login?error=sso.
OIDC
| Elemento | Comportamiento |
|---|---|
| Flujo | Authorization Code |
| Solicitud authorize | response_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce |
| state · nonce | De un solo uso y válidos durante 10 minutos. Si deja la ventana de inicio de sesión abierta más de 10 minutos, tendrá que volver a iniciar sesión desde el principio. |
| Intercambio de token | POST al token endpoint, application/x-www-form-urlencoded. La autenticación del cliente es client_secret_post (client_id y client_secret en el cuerpo). |
| Firma del ID token | Solo acepta RS256. La clave se busca en jwks_uri mediante kid. |
| Validación del ID token | Firma, exp, aud que incluya el client_id, nonce coincidente, y iss igual a la Issuer URL (se ignora la / final). |
| Correo | La notificación email del ID token. Si no existe, se consulta el userinfo endpoint con Authorization: Bearer <access_token> y se lee email. |
| Nombre | La notificación name del ID token |
| Endpoints | Se localizan en /.well-known/openid-configuration de la Issuer URL. Si el IdP no se encuentra, introduzca manualmente las direcciones de authorization, token, JWKS y userinfo en Mostrar ajustes avanzados. |
| Tiempo límite | 15 segundos por cada llamada al IdP |
La aplicación del IdP debe permitir client_secret_post. Si la configuración solo permite client_secret_basic o private_key_jwt, el intercambio de token fallará.
SAML 2.0
| Elemento | Comportamiento |
|---|---|
| Solicitud | Envía un AuthnRequest mediante el enlace HTTP-Redirect. La solicitud no se firma. |
| Contenido de la solicitud | Destination=URL de SSO del IdP, AssertionConsumerServiceURL=URL de ACS, ProtocolBinding=HTTP-POST, Issuer=EntityID del SP, NameIDPolicy Format=…:nameid-format:unspecified, AllowCreate=true |
| Respuesta | Enlace HTTP-POST con SAMLResponse y RelayState. El RelayState debe devolverse exactamente como lo envió Keural. |
| Firma | La respuesta o la aserción debe tener una firma válida. La clave de verificación es solo el certificado registrado en la pantalla. |
| Aserción | La respuesta debe contener exactamente una aserción. No se aceptan aserciones cifradas (EncryptedAssertion). |
| Estado | StatusCode igual a urn:oasis:names:tc:SAML:2.0:status:Success |
| Issuer | Si introdujo el EntityID del IdP, debe coincidir con el Issuer de la aserción |
| Condiciones | NotBefore y NotOnOrAfter (tolerancia de 300 segundos), Audience=EntityID del SP |
| SubjectConfirmationData | Recipient=URL de ACS, NotOnOrAfter (tolerancia de 300 segundos), InResponseTo=ID de la solicitud enviada por Keural |
| Correo | Un atributo cuyo Name o FriendlyName sea uno de los siguientes (sin distinguir mayúsculas): email, mail, emailAddress, E-Mail-Addresses, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Si no existe, se usa el NameID que contenga @. |
| Nombre | displayName, name, cn, http://schemas.microsoft.com/identity/claims/displayname |
| Certificado | Un certificado X.509. Puede estar en PEM o en Base64 (DER). Para cambiarlo, introduzca el nuevo certificado y guarde. |
| Metadatos | En lugar de subir el XML de metadatos del IdP, introduzca tres valores: EntityID del IdP, URL de SSO del IdP y certificado. |
Determinación del usuario
| Elemento | Comportamiento |
|---|---|
| Criterio para enviar a SSO | Cuando la parte del correo que sigue a @ coincide exactamente con una entrada de la lista de dominios de correo (sin distinguir mayúsculas). Los subdominios se registran por separado. |
| Búsqueda de la cuenta | Se busca la cuenta de Keural con el correo (en minúsculas) que envía el IdP. |
| Si no existe la cuenta | Si Crear usuarios automáticamente en el primer inicio de sesión (JIT) está activado, se crea; si está desactivado, se rechaza el inicio de sesión. |
| Incorporación a la organización | Si no es miembro de la organización, se incorpora como miembro. Si los puestos están completos o la cuenta pertenece a otra organización, no se incorpora y solo se permite el inicio de sesión. |
| Condición para guardar el dominio de correo | Dominio verificado mediante TXT en DNS, excepto los dominios de correo públicos |
Verificación de dominio
| Elemento | Valor |
|---|---|
| Tipo de registro | TXT |
| Host | El dominio registrado tal cual (por ejemplo, acme.com). No use subdominios de prefijo. |
| Valor | keural-verify=<UUID>, exactamente como aparece en la pantalla |
| Momento de comprobación | Se consulta una vez al hacer clic en Confirmar verificación. |
SCIM 2.0
| Elemento | Valor |
|---|---|
| URL base | {API}/scim/v2 |
| Autenticación | Authorization: Bearer <token SCIM>. El token empieza por scim_ y solo se muestra una vez, al emitirlo. |
| Content-Type | Solicitud application/scim+json o application/json; respuesta application/scim+json |
| Códigos de estado | Se devuelven los códigos HTTP reales. El cuerpo del error tiene el formato SCIM Error (schemas, status, detail, scimType). |
Endpoints
| Método | Ruta | Comportamiento |
|---|---|---|
GET | /Users | Lista. filter=userName eq "…", startIndex (predeterminado 1), count (predeterminado 100, máximo 200) |
GET | /Users/{id} | Consulta de un usuario |
POST | /Users | Creación (201). Si ya existe el mismo correo, devuelve 409. |
PATCH | /Users/{id} | Modifica active, displayName, name.formatted y name.givenName |
PUT | /Users/{id} | Aplica displayName, name y active. Si omite active, se considera activo. |
DELETE | /Users/{id} | Suspende la cuenta (204). No borra los datos. |
GET | /Groups, /Groups/{id} | Consulta de los dos grupos fijos. filter=displayName eq "…" |
PATCH | /Groups/{id} | Añade, quita o reemplaza miembros |
GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | Consulta de las funciones admitidas |
Atributos de usuario
| Atributo | Uso |
|---|---|
userName | Correo. Si no existe, se usa emails[0].value. |
displayName · name.formatted · name.givenName+name.familyName | Nombre para mostrar |
active | false suspende la cuenta (bloquea el inicio de sesión); true la restaura |
id | ID de usuario de Keural. Se incluye en la respuesta. |
No se guarda externalId. Para buscar un usuario desde el IdP, use el filtro userName.
Grupos
| id | displayName | Si se añade un miembro | Si se quita un miembro |
|---|---|---|---|
keural-admins | Keural Admins | Administrador | Miembro |
keural-members | Keural Members | Miembro | Sin cambios |
El rol del propietario de la organización no cambia mediante SCIM. La creación y eliminación de grupos (POST·DELETE /Groups) devuelve 501. El value de un miembro del grupo es el ID de usuario de Keural (id de /Users).
Alcance de la compatibilidad
| Función | Compatible |
|---|---|
| PATCH | Sí |
| Filtros | userName eq, displayName eq |
| Bulk · ordenación · ETag · cambio de contraseña | No |
Errores
| Estado | scimType | Causa |
|---|---|---|
400 | invalidValue | Faltan userName y emails |
401 | — | El token falta o es incorrecto, o el aprovisionamiento SCIM está desactivado |
404 | — | El usuario o el grupo no pertenece a esta organización |
409 | uniqueness | Ya existe una cuenta con el mismo correo, o se superó el número de puestos |
501 | — | Creación o eliminación de grupos |
Integración de complementos y servidores MCP
Cómo conectar a Keural un servidor MCP propio y crear un paquete de complemento para la aplicación de escritorio.
Preguntas frecuentes
Preguntas y respuestas sobre inicio de sesión, límites de uso, archivos, respuestas, aplicaciones, organizaciones y facturación.