Saltar al contenido principal
Con el inicio de sesión único SAML, tu institución maneja una sola API key en lugar de una clave por médico. Tu proveedor de identidad (Microsoft Entra ID, Okta, ADFS…) autentica al médico. Telepatia recibe la respuesta SAML firmada, devuelve el navegador a tu aplicación con un código de un solo uso, y tu backend canjea ese código por un token de sesión del médico. Todos los endpoints de negocio siguen igual. Solo cambia el valor de Authorization.

Cómo funciona

  1. Tu aplicación envía el navegador a GET /v1/sso/login/{institutionId} con un relayState que generó tu aplicación.
  2. Telepatia envía el navegador a tu proveedor de identidad (IdP) con una solicitud SAML.
  3. El médico inicia sesión. El IdP envía (POST) la respuesta SAML firmada a la URL de ACS de tu institución en Telepatia, POST /v1/sso/acs/{institutionId}.
  4. Telepatia verifica la respuesta y redirige el navegador (302) a la URL de retorno de tu institución con ?code=…&state=….
  5. Tu backend compara state con el valor que generó en el paso 1. Luego llama a POST /v1/sso/token con la clave secreta de tu institución y el code.
  6. Telepatia devuelve un access token del médico y un refresh token. Tu backend los usa en la API y los renueva con POST /v1/sso/refresh.
La respuesta SAML nunca pasa por tu backend, y la API key nunca pasa por el navegador.

Requisitos previos

  • Una clave secreta de institución (sk_…) creada con el permiso SAML SSO exchange (la casilla saml:exchange en la página de API Keys de la plataforma).
  • Acceso a Plataforma → Developers → SSO. Desde ahí copias los valores de Telepatia.
  • Una ruta en tu aplicación que reciba la redirección a la URL de retorno y que pueda llamar a la API desde tu backend.
  • El médico ya debe existir en tu institución, con el mismo email que envía tu IdP. El SSO autentica médicos; no los crea.

Datos del Service Provider

Copia estos valores del recuadro Detalles del proveedor de servicios en Plataforma → Developers → SSO. Cada valor tiene un botón para copiarlo. Las URL ya incluyen el ID de tu institución. Telepatia acepta una respuesta SAML solo en la URL de ACS de la institución a la que corresponde la respuesta.

Configurar tu proveedor de identidad

Microsoft Entra ID

  1. En el centro de administración de Entra, abre Enterprise applications → New application → Create your own application. Selecciona Integrate any other application you don’t find in the gallery (Non-gallery).
  2. Abre Single sign-on y selecciona SAML.
  3. En Basic SAML Configuration, configura estos valores:
  4. En Attributes & Claims, verifica que el Unique User Identifier (Name ID) sea el email del médico, con el formato Email address. El valor predeterminado es user.userprincipalname. Si el UPN de tus usuarios no es su email, usa user.mail.
  5. En SAML Certificates, descarga Certificate (Base64). Copia también la App Federation Metadata Url.
  6. En Set up tu aplicación, copia la Login URL y el Microsoft Entra Identifier.
  7. En Users and groups, asigna los médicos que pueden iniciar sesión.
Entra puede leer los valores de Telepatia desde un archivo. Descarga el archivo de la URL de metadatos del SP y selecciona Upload metadata file en la página de Single sign-on.

Otros proveedores de identidad

Usa los mismos dos valores: el ID de entidad del SP (audiencia) es la audiencia (Okta: Audience URI; ADFS: Relying party identifier), y la URL de ACS (URL de respuesta) es la dirección que recibe la respuesta SAML con el binding HTTP-POST (Okta: Single sign-on URL; ADFS: SAML Assertion Consumer endpoint). Envía el email del médico como NameID.

Configurar la plataforma

En Plataforma → Developers → SSO, activa Activar SSO SAML y guarda estos valores:
Importar desde la URL de metadatos del IdP completa los campos del IdP a partir de la App Federation Metadata Url de Entra. Revisa los valores y pega el certificado antes de guardar.
Después de guardar, la tarjeta de resumen muestra los valores guardados. Revisa estas dos filas:
  • URL de retorno: tu dirección, o Sin configurar — el inicio de sesión en el navegador está apagado.
  • Inicio de sesión iniciado por el IdP: Permitido, o No permitido — solo inicios de sesión iniciados en Telepatia.
La plataforma guarda todos los valores SAML juntos. Cuando cambies un valor, revisa la URL de retorno y la opción de inicio desde el IdP antes de guardar.

Iniciar la sesión

Envía el navegador a la URL de inicio de sesión que copiaste de la plataforma y agrega ?relayState=. En este ejemplo, INSTITUTION_ID es el ID de tu institución:
  • relayState es opcional, pero úsalo. Genera un valor aleatorio nuevo para cada inicio de sesión (por ejemplo, 32 bytes aleatorios en base64url) y guárdalo en la sesión del navegador del usuario en tu aplicación. Telepatia te lo devuelve como state.
  • relayState puede tener como máximo 80 bytes. No pongas datos personales en él.
  • El enlace no lleva API key. Telepatia envía el navegador a tu IdP con un 302.
  • Demasiados intentos de inicio de sesión desde una misma red reciben 429 con un encabezado Retry-After.

Procesar la URL de retorno

Después de que el médico inicia sesión, Telepatia envía el navegador a tu URL de retorno:
Telepatia conserva los parámetros que ya tiene tu URL de retorno. Reemplaza un code o un state que ya esté en ella. En la ruta que recibe esta redirección:
  1. Compara state con el valor que guardaste en el paso 1. Si falta o es diferente, detén el proceso y muestra un error.
  2. Elimina el valor de state de la sesión, para que se use una sola vez.
  3. Envía code a tu backend y canjéalo de inmediato.

Inicio de sesión desde el IdP

Un inicio de sesión también puede empezar en el IdP, por ejemplo desde el portal My Apps de Entra. En ese caso Telepatia recibe una respuesta SAML sin una solicitud SAML.
  • Cuando Permitir inicio de sesión iniciado por el IdP está desactivado (el valor por defecto), Telepatia rechaza estas respuestas con la página de error saml_idp_initiated_not_allowed.
  • Cuando está activado, Telepatia envía el navegador a tu URL de retorno con un code y sin state. Tu aplicación no inició este proceso, así que no tiene un valor para comparar. Acéptalo solo si tu aplicación permite inicios de sesión que empiezan en el IdP.
Para empezar desde el mosaico de My Apps sin activar esta opción, configura la Sign on URL de Entra con la página de inicio de sesión de tu aplicación. Así, el mosaico abre tu aplicación, y tu aplicación inicia la sesión con un state.

Canjear el código

Llama a este endpoint desde tu backend con la clave secreta de tu institución:
Cuerpo de la solicitud:
Respuesta 200:
  • documentId es la cuenta del médico.
  • expiresIn es la vida del access token, en segundos. Léelo en cada respuesta. No uses un valor fijo en tu código.
  • El código es válido por 90 segundos y para un solo uso. Solo funciona con una clave de la institución en la que el médico inició sesión. Un código vencido, ya usado o desconocido recibe 401.

Requisitos de la aserción

  • La aserción está firmada (RSA-SHA256, firma envuelta) con el certificado configurado para tu institución.
  • El Issuer coincide con el entity ID del IdP configurado para tu institución.
  • El Audience coincide con el ID de entidad del SP indicado arriba.
  • El Destination y el Recipient coinciden con la URL de ACS de tu institución.
  • Cuando el inicio de sesión empieza en /v1/sso/login, la respuesta lleva el InResponseTo de esa solicitud SAML. Una solicitud SAML es válida por 5 minutos y para una sola respuesta.
  • La ventana de validez (NotBefore / NotOnOrAfter) cubre el momento en que Telepatia recibe la respuesta.
  • La aserción incluye un AttributeStatement; los IdP estándar siempre lo incluyen.
  • El email del médico llega como NameID del sujeto (formato emailAddress), o en el atributo indicado por el ajuste opcional email attribute.

Renovar la sesión

El refresh token es la credencial; no se envían la clave de la institución ni el código:
La respuesta tiene la misma estructura de sesión que la de /v1/sso/token. Los refresh tokens rotan: el anterior se revoca cuando se emite el par nuevo, y reutilizarlo devuelve 401.

Llamar a la API como el médico

Usa el access token exactamente donde iría la API key:

Notas de seguridad

  • Verifica state. Compáralo con el valor que tu aplicación guardó para ese navegador. Así evitas que un atacante envíe a una víctima a tu URL de retorno con el código del atacante.
  • Canjea el código solo en tu backend. La clave sk_ nunca debe llegar al navegador. No muestres el código, no lo registres en logs y no lo guardes después de canjearlo.
  • El código dura poco. Es válido por 90 segundos y para un solo uso. Canjéalo apenas la ruta de tu URL de retorno lo reciba.
  • Mantén desactivado el inicio de sesión desde el IdP si no lo necesitas. Un inicio de sesión que empieza tu aplicación lleva state y un InResponseTo que Telepatia verifica.
  • Guarda los tokens en tu backend. El access token y el refresh token dan acceso a los datos del médico.

Respuestas de error

Página de error del inicio de sesión

/v1/sso/login y /v1/sso/acs le responden al navegador, así que un error es una página HTML y no JSON. La página muestra un mensaje, un código de error y un ID de solicitud. Nunca redirige a tu URL de retorno. Comparte el código y el ID de solicitud con el soporte de Telepatia.

Errores del canje del código

/v1/sso/token le responde a tu backend con el formato de error JSON:

Ejemplo: código de inicio de sesión inválido

Migrar desde /exchange

POST /v1/sso/exchange sigue disponible, pero es el flujo anterior. Tu backend debe tener la respuesta SAML firmada y enviarla a Telepatia. Un IdP estándar envía la respuesta SAML al navegador, así que este flujo necesita un endpoint SAML en tu aplicación. El flujo de esta página elimina ese endpoint.
  1. En la plataforma, configura la URL de SSO del IdP y la URL de retorno. Agrega a tu aplicación la ruta de la URL de retorno (consulta Procesar la URL de retorno).
  2. En tu IdP, agrega la URL de ACS (URL de respuesta) de la plataforma como Reply URL y márcala como predeterminada. Conserva la Reply URL anterior (/v1/sso/exchange) hasta terminar el cambio.
  3. Cambia el botón de inicio de sesión de tu aplicación para que envíe el navegador a la URL de inicio de sesión, con ?relayState=STATE.
  4. Cuando todos los inicios de sesión usen el flujo nuevo, elimina la Reply URL anterior y el código que llama a /v1/sso/exchange.
La respuesta con los tokens, la renovación y el token del médico son iguales en los dos flujos.

Solicitud de exchange anterior

El Destination de una aserción para /v1/sso/exchange es https://scribe-api.telepatia.ai/v1/sso/exchange.
La respuesta es igual a la de /v1/sso/token. Cada aserción es de un solo uso. Un segundo intercambio con la misma aserción devuelve 403.