API de Login único

Informa à página de entrada como um endereço de e-mail faz login ou se cadastra. sso, required e provider_name são decididos apenas pelo domínio do endereço, com base nos domínios verificados das organizações que têm uma conexão de provedor de identidade ativada: sso é true quando uma organização desse tipo possui o domínio. required é true quando essa organização exige login único, o que recusa o login com senha e passkey para o domínio (createDashboardSession responde sso_required); seus administradores de emergência (break-glass) mantêm o login com passkey. provider_name é o nome de exibição da conexão, presente apenas quando sso é true. account é true quando uma pessoa ativa possui o endereço, verificado ou não, e false quando ninguém o possui: a página faz o login da pessoa quando é true e oferece o cadastro (POST /api/signups) quando é false e sso é false.

Limitado por endereço de cliente.

Inicia um login único pelo provedor de identidade da organização que tem o domínio do endereço e responde o endereço do provedor, para o qual a página navega. A resposta define o cookie __Host-screenrig-sso (HttpOnly, Secure, SameSite=Strict, Path=/, 10 minutos) que vincula este navegador ao login.

Em uma conexão OIDC, o fluxo solicitado é authorization code com PKCE S256, um nonce e response_mode form_post; uma conexão SAML recebe um AuthnRequest HTTP-Redirect.

O provedor responde enviando por POST para o /api/sso/oidc/{connection_id}/callback ou o /api/sso/saml/{connection_id}/acs da conexão, e o login termina em /api/sso/finish. return_to é um caminho sob /dashboard/ em que o login termina; ausente termina em /dashboard/. invitation_token é um convite que o login aceita assim que a pessoa está conectada. prompt none pede ao provedor um login silencioso, que termina em /dashboard/#sso_error=interaction_required quando a pessoa precisa agir; prompt login faz o provedor autenticar a pessoa novamente.

Um endereço cujo domínio não tem conexão ativada é not_found. Limitado por endereço de cliente.

O OIDC redirect URI de uma conexão. O provedor de identidade envia por POST para cá a partir de outro site (response_mode form_post), então nenhum cookie do dashboard chega. A rota não autentica ninguém: responde uma página que envia por POST os mesmos membros e o id da conexão para /api/sso/finish a partir da origem do dashboard, onde o cookie da transação chega.

Uma resposta conclui apenas um login que esta conexão iniciou; qualquer outro termina em /dashboard/#sso_error=bad_state. Quando o discovery document do provedor define authorization_response_iss_parameter_supported, uma resposta sem iss (RFC 9207) termina em /dashboard/#sso_error=verification_failed.

A página executa um script em linha protegido por um nonce e traz um botão noscript; sua Content-Security-Policy é estrita, Cache-Control é no-store e Referrer-Policy é no-referrer. Um id que nenhuma conexão tem é not_found.

Os metadados do provedor de serviço SAML de uma conexão. Seu entityID é o endereço desta rota e seu assertion consumer service é /api/sso/saml/{connection_id}/acs com o binding HTTP-POST. Um administrador do provedor de identidade os importa, ou copia os mesmos valores de service_provider da conexão. Um id que nenhuma conexão tem é not_found.

O assertion consumer service SAML de uma conexão. O provedor de identidade envia por POST para cá a partir de outro site, então nenhum cookie do dashboard chega. A rota não autentica ninguém: responde uma página que envia por POST o SAMLResponse, seu RelayState e o id da conexão para /api/sso/finish a partir da origem do dashboard, onde o cookie da transação chega.

Uma resposta conclui apenas um login que esta conexão iniciou. A página executa um script em linha protegido por um nonce e traz um botão noscript; sua Content-Security-Policy é estrita, Cache-Control é no-store e Referrer-Policy é no-referrer. Um id que nenhuma conexão tem é not_found.

Conclui um login único na origem do dashboard, onde o cookie __Host-screenrig-sso chega. O formulário é state, a conexão para a qual a resposta chegou e a resposta do provedor de identidade como a página de callback a copiou: code, error, error_description e iss para OIDC, SAMLResponse para SAML (state é o RelayState).

A rota vincula state ao cookie, recusa uma resposta que chegou para outra conexão que não aquela pela qual o login foi iniciado, verifica o token ou a asserção do provedor, aplica as regras de adoção e vinculação de contas, verifica a política de login da organização e responde 303.

Um login, uma renovação ou uma reautenticação emite uma sessão do dashboard com auth_method sso, que dura 24 horas a partir deste login e não é prorrogada pelo uso, aceita o convite que o login traz, define o cookie __Host-screenrig-dashboard, expira o cookie da transação e redireciona para return_to, ou para /dashboard/.

Uma vinculação (link) adiciona a identidade à conta da pessoa conectada e mantém a sessão dela. Um teste registra o resultado na conexão (last_test) e não autentica ninguém. Toda falha também responde 303, para /dashboard/#sso_error=<code>, e nunca com um documento de problema.

Os códigos são no_email, email_unverified, domain_not_allowed, account_exists (a pessoa faz login como antes e vincula a partir da conta dela), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (uma renovação silenciosa precisa da pessoa), provider_refused, provider_unavailable, verification_failed e deactivated (SSOErrorCode).

Inicia um login único para a pessoa conectada e responde o endereço do provedor de identidade, como POST /api/sso/starts faz para um endereço, definindo o cookie __Host-screenrig-sso. intent renew renova, em silêncio (prompt none), uma sessão iniciada por login único antes de suas 24 horas terminarem; o dashboard faz isso quando 12 horas se passaram. intent reauth faz o provedor autenticar a pessoa novamente (prompt login), o que dá à sessão o login recente de que a prova sso precisa. intent link vincula a identidade da pessoa no provedor à conta existente dela. renew e reauth exigem uma sessão iniciada por login único, e link exige uma conexão ativada em um domínio verificado da pessoa; caso contrário, a resposta é resource_conflict. return_to é um caminho sob /dashboard/.

Um administrador designado lê a conexão de login único da organização: seu protocolo e provedor, os valores do provedor de serviço a informar no provedor de identidade (o OIDC redirect URI, o SAML entity ID, os endereços do assertion consumer service e dos metadados), sua política de login e o resultado do último teste.

O client secret nunca é retornado; client_secret_set indica se há um armazenado. ready_to_require é true quando a organização tem um domínio verificado e um teste ou um login real teve sucesso pela identidade atual da conexão (seu issuer, tenant, entity ID e kind); Require SSO só é aceito enquanto ele é true. O ETag carrega a revisão.

Uma organização sem conexão é not_found. Qualquer outra pessoa é recusada como nas demais rotas de administração da organização. Somente pessoas; agentes e credenciais bearer não têm rota.

Um administrador designado cria a conexão da organização ou a altera; uma organização tem uma.

If-Match carrega a revisão da conexão obtida em GET, ou 0 quando a organização não tem nenhuma, e é obrigatório; um valor desatualizado é revision_conflict com current_revision. 201 cria e 200 altera. proof é obrigatório: uma prova recente de passkey ou de senha vinculada a uma reautenticação do tipo identity_provider_change com o ID da organização como subject_id, ou {type: sso} de uma sessão iniciada por login único há no máximo 10 minutos (caso contrário, reauthentication_required).

OIDC com o preset entra recebe tenant_id e monta o issuer a partir dele; o preset generic recebe issuer. Omitir oidc.client_secret mantém o segredo armazenado.

Para SAML, metadata_xml é lido para obter o entity ID do provedor de identidade, o endereço de login e os certificados de assinatura, e idp_entity_id, idp_sso_url e certificates_pem os informam diretamente; certificates_pem substitui a lista armazenada, que tem no máximo 4 para que um novo certificado possa se sobrepor ao antigo durante a rotação.

Enquanto Require SSO está em vigor, uma mudança de identidade (issuer, tenant, entity ID ou kind) é resource_conflict e a rotação de certificado e de client secret é permitida; fora dele, uma mudança de identidade faz ready_to_require passar a false até um teste ou login ter sucesso. Retorna a conexão com o seu ETag. Somente pessoas; agentes e credenciais bearer não têm rota.

Criar a primeira conexão (If-Match 0) é o recurso de login único, que o plano Enterprise inclui; uma organização cujo plano não o inclui é recusada com feature_not_in_plan (402).

Alterar uma conexão existente, como trocar um certificado ou segredo do cliente ou atualizar os metadados, ler, testar e remover uma conexão estão disponíveis em todos os planos, e uma conexão existente continua permitindo que as pessoas façam login.

Um administrador designado remove a conexão da organização após prova recente (o corpo traz proof, como em PUT). É resource_conflict enquanto Require SSO está em vigor, remoção agendada incluída, e not_found quando a organização não tem conexão. Somente pessoas; agentes e credenciais bearer não têm rota.

Um administrador designado inicia um login de teste pela conexão da organização, para comprovar que ela funciona antes de exigi-la. Responde o endereço do provedor de identidade para a página navegar e define o cookie __Host-screenrig-sso.

A resposta do provedor termina em /api/sso/finish, que registra o resultado na conexão (last_test; um sucesso permite que ready_to_require passe a true) e devolve o navegador ao dashboard. Um teste não autentica ninguém. Uma organização sem conexão é not_found. Somente pessoas; agentes e credenciais bearer não têm rota.

Um administrador designado ativa ou desativa Require SSO e indica os administradores de emergência (break-glass). required true recusa o login com senha e passkey nos domínios verificados da organização (sso_required) e requer um domínio verificado e ready_to_require na conexão, caso contrário resource_conflict; incrementa policy_revision. required false não suspende a exigência de imediato: agenda a remoção para 72 horas após a requisição (enforcement_ends_at) e envia e-mail a todos os administradores, e DELETE .../sso-policy/removal a cancela. break_glass_user_ids indica no máximo 2 administradores designados que têm uma passkey, caso contrário invalid_request; eles mantêm o login com passkey enquanto o SSO é exigido, e cada login desse tipo é auditado.

If-Match carrega policy_revision e é obrigatório; um valor desatualizado é revision_conflict com current_revision. proof é obrigatório: uma prova recente de passkey ou de senha vinculada a uma reautenticação do tipo sso_policy_change com o ID da organização como subject_id, ou {type: sso} de uma sessão iniciada por login único há no máximo 10 minutos.

Retorna a política com o seu ETag. Somente pessoas; agentes e credenciais bearer não têm rota. Definir required true é o recurso de login único, que o plano Enterprise inclui; uma organização cujo plano não o inclui é recusada com feature_not_in_plan (402). required false é sempre aceito, e o Require SSO que está ativado continua sendo aplicado até ser desativado.

Qualquer administrador designado cancela uma remoção agendada de Require SSO, que então permanece em vigor. Sem remoção agendada, nada muda. Responde a política. Somente pessoas; agentes e credenciais bearer não têm rota.