API de Inicio de sesión único

Indica a la página de entrada cómo inicia sesión o se registra una dirección de correo electrónico. sso, required y provider_name los decide únicamente el dominio de la dirección, según los dominios verificados de las organizaciones que tienen una conexión de proveedor de identidad habilitada: sso es true cuando una organización así tiene el dominio. required es true cuando esa organización exige el inicio de sesión único, lo que rechaza el inicio de sesión con contraseña y con passkey para el dominio (createDashboardSession responde sso_required); sus administradores de emergencia conservan el inicio de sesión con passkey. provider_name es el nombre para mostrar de la conexión, presente solo cuando sso es true. account es true cuando una persona activa tiene la dirección, verificada o no, y false cuando nadie la tiene: la página lleva a la persona a iniciar sesión cuando es true y ofrece el registro (POST /api/signups) cuando es false y sso es false.

Limitado por dirección cliente.

Comienza un inicio de sesión único a través del proveedor de identidad de la organización que tiene el dominio de la dirección y responde con la dirección del proveedor, a la que navega la página. La respuesta establece la cookie __Host-screenrig-sso (HttpOnly, Secure, SameSite=Strict, Path=/, 10 minutos) que vincula este navegador con el inicio de sesión.

A una conexión OIDC se le pide el flujo de código de autorización con PKCE S256, un nonce y response_mode form_post; una conexión SAML recibe una AuthnRequest HTTP-Redirect.

El proveedor responde enviando un POST a /api/sso/oidc/{connection_id}/callback o a /api/sso/saml/{connection_id}/acs de la conexión, y el inicio de sesión termina en /api/sso/finish. return_to es una ruta bajo /dashboard/ en la que termina el inicio de sesión; si se omite, termina en /dashboard/. invitation_token es una invitación que el inicio de sesión acepta una vez que la persona ha iniciado sesión. prompt none pide al proveedor un inicio de sesión silencioso, que termina en /dashboard/#sso_error=interaction_required cuando la persona debe actuar; prompt login hace que el proveedor autentique a la persona de nuevo.

Una dirección cuyo dominio no tiene ninguna conexión habilitada es not_found. Limitado por dirección cliente.

El URI de redirección OIDC de una conexión. El proveedor de identidad envía aquí un POST desde otro sitio (response_mode form_post), por lo que no llega ninguna cookie del panel. La ruta no inicia sesión a nadie: responde con una página que envía por POST los mismos miembros y el id de la conexión a /api/sso/finish desde el origen del panel, donde llega la cookie de transacción.

Una respuesta solo finaliza un inicio de sesión que esta conexión inició; cualquier otra termina en /dashboard/#sso_error=bad_state. Cuando el documento de descubrimiento del proveedor establece authorization_response_iss_parameter_supported, una respuesta sin iss (RFC 9207) termina en /dashboard/#sso_error=verification_failed.

La página ejecuta un script en línea protegido por un nonce y lleva un botón noscript; su Content-Security-Policy es estricta, Cache-Control es no-store y Referrer-Policy es no-referrer. Un id que ninguna conexión tiene es not_found.

Los metadatos del proveedor de servicios SAML de una conexión. Su entityID es la dirección de esta ruta y su servicio de consumo de aserciones es /api/sso/saml/{connection_id}/acs con el binding HTTP-POST. Un administrador del proveedor de identidad los importa, o copia los mismos valores del service_provider de la conexión. Un id que ninguna conexión tiene es not_found.

El servicio de consumo de aserciones SAML de una conexión. El proveedor de identidad envía aquí un POST desde otro sitio, por lo que no llega ninguna cookie del panel. La ruta no inicia sesión a nadie: responde con una página que envía por POST el SAMLResponse, su RelayState y el id de la conexión a /api/sso/finish desde el origen del panel, donde llega la cookie de transacción.

Una respuesta solo finaliza un inicio de sesión que esta conexión inició. La página ejecuta un script en línea protegido por un nonce y lleva un botón noscript; su Content-Security-Policy es estricta, Cache-Control es no-store y Referrer-Policy es no-referrer. Un id que ninguna conexión tiene es not_found.

Finaliza un inicio de sesión único en el origen del panel, donde llega la cookie __Host-screenrig-sso. El formulario es state, la conexión para la que llegó la respuesta, y la respuesta del proveedor de identidad tal como la copió la página de callback: code, error, error_description e iss para OIDC, SAMLResponse para SAML (state es el RelayState).

La ruta vincula state a la cookie, rechaza una respuesta que llegó para una conexión distinta de aquella con la que empezó el inicio de sesión, verifica el token o la aserción del proveedor, aplica las reglas de adopción y vinculación de cuentas, comprueba la política de inicio de sesión de la organización y responde 303.

Un inicio de sesión, una renovación o una reautenticación crea una sesión del panel con auth_method sso, que dura 24 horas desde este inicio de sesión y no se prolonga con el uso, acepta la invitación que lleva el inicio de sesión, establece la cookie __Host-screenrig-dashboard, hace expirar la cookie de transacción y redirige a return_to, o a /dashboard/.

Una vinculación añade la identidad a la cuenta de la persona con sesión iniciada y mantiene su sesión. Una prueba registra su resultado en la conexión (last_test) y no inicia sesión a nadie. Todo fallo también responde 303, a /dashboard/#sso_error=<code>, y nunca con un documento de problema.

Los códigos son no_email, email_unverified, domain_not_allowed, account_exists (la persona inicia sesión como antes y vincula desde su cuenta), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (una renovación silenciosa necesita a la persona), provider_refused, provider_unavailable, verification_failed y deactivated (SSOErrorCode).

Comienza un inicio de sesión único para la persona con sesión iniciada y responde con la dirección del proveedor de identidad, como hace POST /api/sso/starts para una dirección, y establece la cookie __Host-screenrig-sso. intent renew renueva de forma silenciosa (prompt none) una sesión que inició sesión mediante el inicio de sesión único, antes de que terminen sus 24 horas; el panel lo hace una vez transcurridas 12 horas. intent reauth hace que el proveedor autentique a la persona de nuevo (prompt login), lo que da a la sesión el inicio de sesión reciente que necesita la prueba sso. intent link vincula la identidad de la persona en el proveedor a su cuenta existente. renew y reauth necesitan una sesión que inició sesión mediante el inicio de sesión único, y link necesita una conexión habilitada en el dominio verificado de la persona; de lo contrario, la respuesta es resource_conflict. return_to es una ruta bajo /dashboard/.

Un administrador designado lee la conexión de inicio de sesión único de la organización: su protocolo y proveedor, los valores del proveedor de servicios que se ingresan en el proveedor de identidad (el URI de redirección de OIDC, el ID de entidad de SAML, el servicio de consumo de aserciones y las direcciones de metadatos), su política de inicio de sesión y el resultado de la última prueba.

El secreto de cliente nunca se devuelve; client_secret_set indica si hay uno almacenado. ready_to_require es true cuando la organización tiene un dominio verificado y una prueba o un inicio de sesión real se ha completado con éxito mediante la identidad actual de la conexión (su emisor, tenant, ID de entidad y tipo); Require SSO solo se acepta mientras sea true. El ETag lleva la revisión.

Una organización sin conexión es not_found. Cualquier otro es rechazado como en las otras rutas de administrador de la organización. Solo personas; los agentes y las credenciales portadoras no tienen ruta.

Un administrador designado crea la conexión de la organización o la modifica; una organización tiene una.

If-Match lleva la revisión de la conexión de GET, o 0 cuando la organización no tiene ninguna, y es obligatorio; un valor desactualizado es revision_conflict con current_revision. 201 crea y 200 modifica. proof es obligatorio: una prueba reciente de passkey o de contraseña vinculada a una reautenticación de tipo identity_provider_change con el id de la organización como subject_id, o {type: sso} de una sesión que inició sesión mediante el inicio de sesión único hace 10 minutos como máximo (de lo contrario, reauthentication_required).

OIDC con el preset entra toma tenant_id y construye el emisor a partir de él; el preset generic toma issuer. Omitir oidc.client_secret conserva el secreto almacenado.

Para SAML, metadata_xml se lee para obtener el ID de entidad, la dirección de inicio de sesión y los certificados de firma del proveedor de identidad, y idp_entity_id, idp_sso_url y certificates_pem los indican directamente; certificates_pem reemplaza la lista almacenada, que contiene como máximo 4 para que un certificado nuevo pueda solaparse con el anterior durante la rotación.

Mientras Require SSO está vigente, un cambio de identidad (emisor, tenant, ID de entidad o tipo) es resource_conflict y se permite la rotación de certificados y del secreto de cliente; fuera de él, un cambio de identidad hace que ready_to_require pase a false hasta que una prueba o un inicio de sesión se complete con éxito. Devuelve la conexión con su ETag. Solo personas; los agentes y las credenciales portadoras no tienen ruta.

Crear la primera conexión (If-Match 0) corresponde al inicio de sesión único, que incluye el plan Enterprise; una organización cuyo plan no lo incluye se rechaza con feature_not_in_plan (402).

Cambiar una conexión que ya existe, como rotar un certificado o un secreto de cliente o actualizar los metadatos, y leerla, probarla y eliminarla están abiertos en todos los planes, y una conexión que ya existe sigue permitiendo el inicio de sesión de las personas.

Un administrador designado elimina la conexión de la organización tras una prueba reciente (el cuerpo lleva proof, como en PUT). Es resource_conflict mientras Require SSO está vigente, incluida una eliminación programada, y not_found cuando la organización no tiene conexión. Solo personas; los agentes y las credenciales portadoras no tienen ruta.

Un administrador designado inicia una prueba de inicio de sesión a través de la conexión de la organización, para comprobar que funciona antes de exigirla. Responde con la dirección del proveedor de identidad a la que la página navega y establece la cookie __Host-screenrig-sso.

La respuesta del proveedor termina en /api/sso/finish, que registra el resultado en la conexión (last_test; un resultado correcto permite que ready_to_require pase a true) y devuelve el navegador al panel. Una prueba no inicia sesión a nadie. Una organización sin conexión es not_found. Solo personas; los agentes y las credenciales portadoras no tienen ruta.

Un administrador designado activa o desactiva Require SSO y nombra a los administradores de emergencia. required true rechaza el inicio de sesión con contraseña y con passkey en los dominios verificados de la organización (sso_required) y necesita un dominio verificado y ready_to_require en la conexión; de lo contrario, resource_conflict; incrementa policy_revision. required false no levanta el requisito de inmediato: programa la eliminación para 72 horas después de la solicitud (enforcement_ends_at) y envía un correo electrónico a todos los administradores, y DELETE .../sso-policy/removal la cancela. break_glass_user_ids nombra como máximo a 2 administradores designados que tengan un passkey; de lo contrario, invalid_request; conservan el inicio de sesión con passkey mientras se exige el inicio de sesión único, y cada uno de esos inicios de sesión se audita.

If-Match lleva policy_revision y es obligatorio; un valor desactualizado es revision_conflict con current_revision. proof es obligatorio: una prueba reciente de passkey o de contraseña vinculada a una reautenticación de tipo sso_policy_change con el id de la organización como subject_id, o {type: sso} de una sesión que inició sesión mediante el inicio de sesión único hace 10 minutos como máximo.

Devuelve la política con su ETag. Solo personas; los agentes y las credenciales portadoras no tienen ruta. Establecer required true corresponde al inicio de sesión único, que incluye el plan Enterprise; una organización cuyo plan no lo incluye se rechaza con feature_not_in_plan (402). required false siempre se acepta, y Require SSO, si está activado, sigue vigente hasta que se desactive.

Cualquier administrador designado cancela una eliminación programada de Require SSO, de modo que sigue vigente. Si no hay ninguna eliminación programada, no cambia nada. Responde con la política. Solo personas; los agentes y las credenciales portadoras no tienen ruta.