Referência da configuração de SSO

Tudo o que é configurável no início de sessão único, num só sítio. Os valores vivem nas linhas sso_connections de global.db (abrangem o servidor por conceção), editados através de Definições → Servidor → Início de sessão único ou das operações RPC sso.*. A linha guardada é a única fonte de verdade — não existe nenhum caminho por variáveis de ambiente CC_SAML_* / CC_OIDC_* (uma ligação que pudesse chegar de dois sítios é uma com que o ecrã de definições pode discordar).

Campos da ligação

Campo	Aplica-se a	Predefinição	Significado
enabled	ambos	desativado	os inícios de sessão podem usar esta ligação
idpMetadataXml	SAML	—	o XML EntityDescriptor do IdP (obrigatório para ativar)
spEntityId	SAML	<origin>/saml	o nosso ID de entidade, fixado quando a origem varia
emailAttribute	SAML	email	atributo que transporta o e-mail; um NameID com forma de e-mail é a alternativa
displayNameAttribute	SAML	displayName	atributo do nome de exibição
groupsAttribute	SAML	groups	atributo dos nomes dos grupos
clockSkewSeconds	SAML	90	tolerância de desvio na validação do tempo de vida
allowIdpInitiated	SAML	desativado	aceitar mensagens Response não solicitadas (sem InResponseTo)
wantResponseSigned	SAML	desativado	exigir uma assinatura na raiz da Response (as assinaturas de asserção são sempre exigidas)
issuer	OIDC	—	URL base do emissor (obrigatório para ativar)
clientId	OIDC	—	ID do cliente público (obrigatório para ativar)
clientSecret	OIDC	—	apenas para clientes confidenciais; guardado no ficheiro de segredos 0600, nunca na base de dados — só de escrita através de RPC (sso.getConfig indica clientSecretPresent)
groupsClaim	OIDC	groups	claim que transporta os nomes dos grupos
defaultRole	ambos	member	função quando nenhum grupo mapeia — nunca owner
groupRoleMap	ambos	{}	grupo → função; os mapeamentos de proprietário são recusados ao guardar
autoMember	ambos	ativado	adicionar automaticamente os utilizadores a todos os espaços de trabalho no primeiro início de sessão
allowJit	ambos	ativado	provisionar utilizadores desconhecidos no início de sessão

Configuração do processo

As ligações de SSO não são semeadas a partir do ambiente. Resta um parâmetro de processo que diz respeito à passagem para o navegador, não à linha da ligação:

Variável / parâmetro	Significado
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origem para a qual os callbacks de SSO reencaminham o navegador (a credencial viaja no fragmento do URL). Se não estiver definido, a passagem mantém-se na mesma origem.

O próprio URL do emissor tem de ser https (http só é aceite para emissores de loopback localhost, 127.0.0.1 e ::1).

Endpoints HTTP

Endpoint	Autenticação	Objetivo
GET /saml/login?relay=…	nenhuma (redirecionamento)	iniciar o início de sessão iniciado pelo SP; relay=desktop passa a sessão para a aplicação, relay=web-popup envia um postMessage para o separador de ligação à espera (que declara o seu client_origin, respeitado apenas quando a lista de permissões de origens confia nele)
POST /saml/acs	nenhuma (POST do IdP)	o consumidor de asserções — verifica, provisiona, emite
GET /saml/metadata	nenhuma	o nosso EntityDescriptor de SP
GET /oidc/login?relay=… / GET /oidc/callback	nenhuma	a ida e volta OIDC; relay=desktop passa a sessão para a aplicação, relay=web-popup para o separador de ligação à espera (a mesma convenção de client_origin)
GET /auth/providers	nenhuma, CORS *	a sondagem do ecrã de ligação: ligações de SSO oferecidas (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token SCIM)	Users — criar/obter/listar+filtrar/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	só de leitura; o envio de grupos responde 501 por conceção
/scim/v2/ServiceProviderConfig	Bearer	documento de capacidades

Operações RPC

Todas as operações sso.* têm âmbito de servidor e estão reservadas ao proprietário do servidor (o operador da instalação, ServerAuthority.serverOwner). Ser proprietário de um espaço de trabalho não chega; o emparelhamento por si só nunca as concede.

Operação	Objetivo
sso.getConfig	a ligação guardada para um tipo
sso.saveConfig	validar, persistir e aplicar em tempo real
sso.status	sinalizadores de ativado/configurado, presença do token SCIM, origem canónica
sso.testConnection	testar uma ligação sem chegar à ida e volta pelo navegador (SAML: análise dos metadados + construção do AuthnRequest; OIDC: descoberta do emissor), com valores opcionais ainda não guardados no ecrã
sso.spMetadata	emitir o EntityDescriptor de SP para uma origem
sso.setPairingEnabled	permitir/proibir o emparelhamento manual (códigos de convite, chaves de emparelhamento); recusar desativá-lo enquanto não existir nenhuma ligação de SSO funcional protege contra o bloqueio do acesso
sso.sessionPolicy	ler a idade máxima das credenciais de dispositivo e o tempo limite de inatividade da instalação (em minutos; 0 = não definido)
sso.setSessionPolicy	definir esses limites; aplicados na verificação do dispositivo, não anunciados aos clientes
sso.scimRegenerateToken	gerar + devolver o token bearer do SCIM (uma única vez)

Códigos de erro de validação

As falhas de cc_saml_verify_response trazem um código estável:

Código	Significado
signature	assinatura ausente/não fidedigna/adulterada, ou um algoritmo/transformação não permitido
expired	fora de NotBefore/NotOnOrAfter (além do desvio)
audience	a restrição de audiência não nos nomeia
destination	o destino da resposta não é o nosso ACS
request_match	o InResponseTo não corresponde a um pedido pendente, ou a resposta é não solicitada quando tal está desativado
issuer	o emissor não é o IdP configurado
recipient	o destinatário da confirmação do sujeito não é o nosso ACS
malformed	falha ao nível do XML/esquema
status	o estado comunicado pelo IdP não era Success
invalid / internal	tudo o resto / falha na interligação

Superfícies da base de dados

• sso_connections (global.db) — uma linha por tipo, ABRANGE TODOS OS ESPAÇOS DE TRABALHO POR CONCEÇÃO.
• users.sso_subject + users.sso_issuer — a fixação do sujeito do fornecedor, única por (issuer, subject) através de um índice parcial.
• users.deactivated_at — o carimbo de desativação do SCIM.
• O token bearer do SCIM e o segredo do cliente OIDC vivem no ficheiro de segredos 0600, nunca na base de dados.