Sistemas Externos
Registre sistemas da sua organização que implementam o contrato de acesso publicado pelo Sincroniza e passe a controlar as permissões deles a partir dos dados de RH — sem instalar código específico do cliente no Sincroniza.
O que é um Sistema Externo
Um Sistema Externo é uma aplicação do cliente cujo acesso o Sincroniza gerencia através de um contrato REST publicado (ADR-0016). Em vez de importar código ou montar um conector genérico, o Sincroniza define o formato da API, o sistema do cliente o implementa, e um único executor genérico embutido atende a todos os sistemas conformes. Nada específico de um cliente é distribuído: o recurso é genérico para todas as instalações.
Depois de registrado:
- As permissões do sistema (o que ele chama de permissão, papel, perfil de acesso — cada sistema informa seu próprio rótulo) tornam-se Recursos no Sincroniza. Elas entram em Pacotes de Atribuição, são resolvidas pelas Regras de Atribuição e aparecem nas Auditorias, exatamente como grupos e licenças.
- O Sincroniza concede e revoga essas permissões seguindo os dados de RH, identificando o colaborador pelo identificador que o registro declara.
- Opcionalmente, o Sincroniza também administra o ciclo de vida do usuário no sistema (criar, atualizar, habilitar, desabilitar).
Sistema Externo x Provedor de Identidade
Um Provedor de Identidade (Active Directory, Entra ID, Google Workspace) é dono das contas dos colaboradores. Um Sistema Externo não é dono de contas — ele apoia-se na identidade que o colaborador já tem em um provedor (o AD, o Entra ID ou o Google) e só administra as permissões concedidas dentro dele.
Pré-requisitos
Antes de registrar:
- [ ] O sistema alvo implementa o contrato de acesso do Sincroniza (verifique com a equipe de TI que constrói a API).
- [ ] Uma credencial de API OAuth2 (fluxo client credentials) cadastrada em Credenciais, com o client id, o client secret, o endpoint de token e os escopos que o sistema concede.
- [ ] Uma origem de identificador definida: um Provedor de Identidade já configurado (AD, Entra ID ou Google) e o tipo de identificador que a API do sistema aceita para casar usuários.
Registrando um Sistema Externo
- Acesse Configurações → Sistemas Externos
- Clique em Registrar Sistema
- Informe a URL base do sistema e clique em Buscar manifesto
O Sincroniza lê o manifesto público do sistema ({URL base}/.well-known/sincroniza-manifest.json, com opção de sobrescrever a URL) e pré-preenche o formulário com o nome sugerido, o rótulo da permissão, os tipos de identificador aceitos e a sugestão de endpoint de token.
Campos do registro
| Campo | Descrição |
|---|---|
| Chave | Identificador permanente do sistema. Não pode ser alterado após o registro — só o Nome é renomeável. É a identidade estável usada internamente (ex.: nos identificadores de recurso {chave}:{permissão}). |
| Nome de exibição | Nome mostrado na interface. Editável a qualquer momento. |
| URL base | Endereço da API do sistema. Também fixo após o registro. |
| URL do manifesto (opcional) | Sobrescreve o caminho .well-known padrão. |
| Credencial de API | A credencial OAuth2 usada em toda chamada a este sistema. Use Criar credencial para cadastrar uma nova sem sair da tela. |
| Rótulo da permissão | A palavra que o próprio sistema usa para sua unidade concedível (ex.: "Permissão", "Perfil de Acesso"), exibida em toda a interface onde as permissões dele aparecem. |
| Autoridade do identificador | O Provedor de Identidade de onde o identificador é lido (Active Directory, Entra ID ou Google Workspace). |
| Tipo de identificador | Um dos tipos que o manifesto declara aceitar, restrito aos que a autoridade escolhida sabe ler: Active Directory aceita objectGuid, sAMAccountName ou userPrincipalName; Entra ID aceita entraObjectId ou userPrincipalName; Google Workspace aceita o e-mail primário (googlePrimaryEmail). O registro fixa um par (autoridade, tipo) e o contrato envia exatamente ele. |
| Gerenciar usuários neste sistema | Liga o mastering de usuários (ver abaixo). |
Escopos da credencial
A credencial não deve pedir escopos que o sistema nunca concede. O contrato nomeia três níveis — read, entitlements:manage e users:manage. Um sistema que não implementa o ciclo de vida de usuários (usersManage: false no manifesto) nunca concede users:manage; peça apenas read e entitlements:manage.
Verificação de conformidade
O Sincroniza executa uma verificação de conformidade ao registrar e sob demanda (menu do sistema → Executar verificação de conformidade). Ela prova, com sondagens somente leitura, que a API atende ao contrato antes de você confiar nela.
O Relatório de Conformidade lista cada regra com Passou, Falhou ou Ignorada (mais o motivo em caso de falha):
| Regra | O que valida |
|---|---|
| Manifesto acessível e válido | O .well-known responde e tem o formato esperado |
| Versão do contrato suportada | O sistema declara a versão que o Sincroniza fala (v1) |
| Aquisição de token com os escopos necessários | A credencial obtém um token no emissor configurado |
| Endpoint de saúde autenticado | GET /v1/health responde — prova alcance, autenticação e aceitação de escopo em uma sondagem |
| Catálogo de permissões legível | GET /v1/entitlements retorna a primeira página |
| Permissões contêm id, name e displayName | O formato do primeiro item é válido |
| Snapshot de usuários legível | GET /v1/users retorna a primeira página |
| Membros das permissões legíveis | GET /v1/entitlements/{id}/members retorna |
O selo do card é validade de configuração, não saúde em tempo real
O selo Conforme / Falha de conformidade / Não verificado no card reflete o resultado da última verificação de conformidade — não o estado de disponibilidade do sistema no momento. A saúde em tempo real (falha e recuperação) é monitorada em segundo plano e notificada à parte; ela pausa automaticamente as ações do sistema durante uma indisponibilidade.
Gerenciamento de usuários (mastering)
O interruptor Gerenciar usuários neste sistema segue a mesma semântica das Propriedades de Sincronização:
- Ligado — o Sincroniza cria o usuário no sistema sob demanda, na primeira vez que as regras concedem algo a ele, e mantém o perfil fixo do contrato (nome de exibição, e-mail, departamento e cargo) em dia com o RH.
- Desligado — os usuários aparecem pelo processo próprio do sistema; o Sincroniza apenas concede e revoga permissões e executa o ciclo de vida opcional de habilitar/desabilitar (por exemplo, desabilitar e revogar acesso na detecção de desligamento).
Quando o manifesto declara usersManage: false, o mastering é forçado a desligado e as opções de ciclo de vida ficam ocultas.
Congelar, desativar e excluir
- Desativar = congelar. O sistema fica invisível para a avaliação de regras — nada é concedido nem revogado. As atribuições existentes permanecem como estão, as auditorias e a verificação de saúde o ignoram, e ações pendentes são canceladas. Desativar nunca revoga em massa.
- Ativar volta a torná-lo visível para regras e auditorias.
- Excluir remove o registro, mas é bloqueado enquanto pacotes de atribuição referenciam as permissões do sistema. O histórico é sempre mantido.
Política de aprovação por sistema
Por padrão, toda ação de um Sistema Externo — conceder/revogar permissões e ciclo de vida de usuário — exige revisão: um sistema novo conquista confiança explicitamente. Você ajusta isso em Configurações → Fluxos de Aprovação, na seção Sistemas Externos, com dois interruptores por sistema:
- Ações de permissões — auto-aprovar conceder e revogar
- Ações de ciclo de vida — auto-aprovar criar, atualizar, habilitar e desabilitar usuários
As ações de Sistemas Externos não aparecem na lista de auto-aprovação global da página — cada sistema é configurado aqui. A proteção de lote continua valendo por cima: ações auto-aprovadas ainda contam para o limite de lote e podem ir para revisão.
Para a equipe de TI: o contrato de acesso
A API do sistema é construída pela equipe de TI do cliente (normalmente junto com o Sincroniza durante o engajamento de integração). O artefato normativo — em inglês, voltado a quem implementa a API — vive no repositório do Sincroniza:
- Especificação OpenAPI —
ai/docs/external-system-contract/openapi.yaml: a autoridade legível por máquina para endpoints, payloads e códigos de status. - Guia de conformidade —
ai/docs/external-system-contract/conformance-guide.md: o manifesto, o modelo de autenticação (incluindo o perfil Entra ID) e as regras de conformidade que o OpenAPI não expressa (idempotência, ids estáveis, semântica de saúde). - Implementação de referência —
src/Demo/demo-external-system/README.md: um servidor de exemplo executável (em memória) que a equipe pode ler, rodar e sondar, com um roteiro de conformidade copia-e-cola.
Próximos Passos
- Credenciais — cadastre a credencial de API OAuth2
- Pacotes de Atribuição — inclua permissões de Sistemas Externos nos pacotes
- Fluxos de Aprovação — ajuste a política de aprovação por sistema
- Auditorias — audite as atribuições e o estado das contas nos Sistemas Externos