Referência de configuração de SSO

Tudo o que é configurável no logon único, em um só lugar. Os valores ficam nas linhas de sso_connections de global.db (com escopo de servidor por design), editados em Configurações → Servidor → Início de sessão único ou pelas operações RPC sso.*. A linha salva é a única fonte de verdade — não existe caminho por variáveis de ambiente CC_SAML_* / CC_OIDC_* (uma conexão que pudesse chegar de dois lugares é uma conexão com a qual a tela de configurações poderia discordar).

Campos da conexão

Campo	Aplica-se a	Padrão	Significado
enabled	ambos	desativado	os logins podem usar esta conexão
idpMetadataXml	SAML	—	o XML EntityDescriptor do IdP (obrigatório para ativar)
spEntityId	SAML	<origin>/saml	nosso ID de entidade, fixado quando a origem varia
emailAttribute	SAML	email	atributo que carrega o e-mail; um NameID com formato de e-mail serve de alternativa
displayNameAttribute	SAML	displayName	atributo do nome de exibição
groupsAttribute	SAML	groups	atributo com os nomes dos grupos
clockSkewSeconds	SAML	90	tolerância de desvio na validação do tempo de vida
allowIdpInitiated	SAML	desativado	aceitar respostas não solicitadas (sem InResponseTo)
wantResponseSigned	SAML	desativado	exigir assinatura no elemento raiz Response (as assinaturas de asserção são sempre exigidas)
issuer	OIDC	—	URL base do emissor (obrigatória para ativar)
clientId	OIDC	—	ID do cliente público (obrigatório para ativar)
clientSecret	OIDC	—	apenas clientes confidenciais; guardado no arquivo de segredos 0600, nunca no banco de dados — somente gravação por RPC (sso.getConfig informa clientSecretPresent)
groupsClaim	OIDC	groups	claim que carrega os nomes dos grupos
defaultRole	ambos	member	papel quando nenhum grupo mapeia — nunca owner
groupRoleMap	ambos	{}	grupo → papel; mapeamentos para owner são recusados ao salvar
autoMember	ambos	ativado	adiciona automaticamente os usuários a todos os espaços de trabalho no primeiro login
allowJit	ambos	ativado	provisiona usuários desconhecidos no login

Configuração do processo

As conexões de SSO não são semeadas a partir do ambiente. Resta uma flag de processo, e ela diz respeito à transferência para o navegador, não à linha da conexão:

Variável / flag	Significado
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origem para a qual os callbacks de SSO devolvem o navegador (a credencial viaja no fragmento da URL). Sem definição, a transferência permanece na mesma origem.

A própria URL do emissor precisa ser https (http só é aceito para emissores de loopback localhost, 127.0.0.1 e ::1).

Endpoints HTTP

Endpoint	Autenticação	Finalidade
GET /saml/login?relay=…	nenhuma (redirecionamento)	inicia o login iniciado pelo SP; relay=desktop transfere para o app, relay=web-popup faz postMessage para a aba de conexão que está aguardando (ela declara seu client_origin, respeitado apenas quando a lista de origens permitidas confia nele)
POST /saml/acs	nenhuma (POST do IdP)	o consumidor de asserções — verifica, provisiona, emite
GET /saml/metadata	nenhuma	nosso EntityDescriptor de SP
GET /oidc/login?relay=… / GET /oidc/callback	nenhuma	a ida e volta do OIDC; relay=desktop transfere para o app, relay=web-popup para a aba de conexão que está aguardando (mesma convenção de client_origin)
GET /auth/providers	nenhuma, CORS *	a sondagem da tela de conexão: conexões de SSO oferecidas (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token do SCIM)	Users create/get/list+filter/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	somente leitura; o push de grupos responde 501 por design
/scim/v2/ServiceProviderConfig	Bearer	documento de capacidades

Operações RPC

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

Operação	Finalidade
sso.getConfig	a conexão salva de um tipo
sso.saveConfig	valida, persiste e aplica em tempo real
sso.status	flags de ativado/configurado, presença do token do SCIM, origem canônica
sso.testConnection	testa uma conexão sem a ida e volta pelo navegador (SAML: análise dos metadados + construção do AuthnRequest; OIDC: descoberta do emissor), com valores opcionais da tela ainda não salvos
sso.spMetadata	emite o EntityDescriptor de SP para uma origem
sso.setPairingEnabled	permite/proíbe o emparelhamento manual (códigos de convite, chaves de emparelhamento); recusar a desativação enquanto não existe nenhuma conexão de SSO funcional protege contra o bloqueio de acesso
sso.sessionPolicy	lê a idade máxima das credenciais de dispositivo da instalação e o tempo limite de inatividade (minutos; 0 = não definido)
sso.setSessionPolicy	define esses limites; aplicados na verificação do dispositivo, não anunciados aos clientes
sso.scimRegenerateToken	gera e retorna 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 confiável ou adulterada, ou um algoritmo/transformação não permitido
expired	fora de NotBefore/NotOnOrAfter (além do desvio)
audience	a restrição de audience não nos nomeia
destination	o destino da resposta não é o nosso ACS
request_match	InResponseTo não corresponde a uma requisição pendente, ou a resposta não foi solicitada enquanto isso é proibido
issuer	o emissor não é o IdP configurado
recipient	o destinatário da confirmação de sujeito não é o nosso ACS
malformed	falha no nível de XML/esquema
status	o status informado pelo IdP não foi Success
invalid / internal	qualquer outra coisa / falha na costura

Superfícies do banco de dados

• sso_connections (global.db) — uma linha por tipo, ENTRE ESPAÇOS DE TRABALHO POR DESIGN.
• users.sso_subject + users.sso_issuer — a fixação do sujeito do provedor, única por (issuer, subject) por meio 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 ficam no arquivo de segredos 0600, nunca no banco de dados.