SSO empresarial e SCIM — ingestia.io Documentation

This page has not been translated yet — you are reading the Portuguese version. View in Portuguese

Selo de estado: Preview — SSO (SAML 2.0 + OIDC) e SCIM 2.0 são Preview: funcionam e são documentados, sem SLA, e ficam INERTES até serem ligados de propósito no ambiente. Atualizado em 2026-09-08. Fonte de estado: matriz de estados do produto (SSO empresarial; SCIM 2.0). Limite atual do produto da limite atual do produto = Preview.

Integre o ingestia.io ao provedor de identidade (IdP) da sua empresa: login único (SSO) e provisionamento/deprovisionamento automático de pessoas (SCIM).

O que é#

SSO (SAML 2.0 / OIDC): a pessoa entra pelo IdP corporativo (Okta, Microsoft Entra ID, Google Workspace…) sem senha local. Com JIT provisioning, o primeiro login já cria o membro no workspace.
SCIM 2.0: o IdP empurra criação, atualização e desativação de usuários (e mapeia grupos → papéis) para o ingestia.io, mantendo a base sincronizada.

Para que serve#

Centralizar acesso no IdP (uma pessoa sai da empresa → sai do produto).
Padronizar papéis por grupo do IdP (ex.: grupo "BI-Admins" → papel admin).
Auditar entrada/saída de pessoas sem trabalho manual.

Plano e permissões#

Plano: a partir de Scale (Preview) — ver Planos.
Quem configura: owner do workspace / org_admin, junto ao operador da plataforma (envs do IdP).
Autenticação do SCIM: por service principal (token sp_live_…) — não é chave de dados. O escopo do provisionamento é sempre o workspace/org do próprio service principal, nunca vindo da URL/corpo (anti entre clientes).

Pré-requisitos#

IdP com suporte a SAML 2.0 ou OIDC e (para sincronizar) a SCIM 2.0.
SSO ligado no ambiente (segredo de handshake provisionado). Sem isso, a rota de SSO responde 503 e a de SCIM responde 503 em produção — nunca finge provisionar.
Para SCIM: a ativação do SCIM no ambiente (feita por nós) e, opcionalmente, o mapa de grupos do seu IdP para papéis do produto.

Passo a passo (visão geral)#

Ligar o SSO no ambiente
O operador provisiona o segredo de handshake e as configurações do IdP. Enquanto não ligado, o SSO fica inerte (503) — pode ser implantado sem ativar nada.
Configurar o IdP
No IdP, cadastre o ingestia.io como aplicação SAML/OIDC. Defina o mapeamento de atributos (e-mail, nome) e os grupos que virarão papéis.
Ativar o SCIM (opcional)
Peça a ativação do SCIM e gere um service principal para o IdP usar como token Bearer no endpoint SCIM. Configure o mapa de grupos → papéis.
Testar entrada e saída
Faça um login de teste (JIT cria o membro) e uma desativação no IdP (SCIM desativa o membro no ingestia — nunca apaga dados).

Endpoint SCIM (referência)#

Base: https://ingestia.io/api/scim/v2 · Content-Type application/scim+json.

Método · rota	Efeito
`GET /Users` (+`?filter=`)	lista membros (filtro `userName`/`externalId eq`)
`POST /Users`	provisiona membro (papel resolvido pelos grupos)
`PUT /Users/{id}`	substitui atributos do membro
`PATCH /Users/{id}`	`active:false` → desativa (deprovisioning seguro)
`DELETE /Users/{id}`	deprovisioning seguro → desativa (nunca apaga dados)
`GET /Groups` · `PATCH /Groups/{id}`	grupos mapeados; add → papel do grupo, remove → `viewer`
`GET /ServiceProviderConfig`	discovery (sem efeito)

Deprovisioning é sempre não-destrutivo

DELETE e PATCH active:false desativam o membro (perde o acesso na hora), mas nunca deletam dados. A remoção de dados é um fluxo separado e explícito de exclusão de dados.

Exemplo (SCIM — sintético)#

curl -X POST https://ingestia.io/api/scim/v2/Users \
  -H "Authorization: Bearer sp_live_EXEMPLO" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "ana@example.com",
    "displayName": "Ana Souza",
    "active": true
  }'

await fetch("https://ingestia.io/api/scim/v2/Users", {
  method: "POST",
  headers: {
    Authorization: "Bearer sp_live_EXEMPLO",
    "Content-Type": "application/scim+json",
  },
  body: JSON.stringify({
    schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"],
    userName: "ana@example.com",
    displayName: "Ana Souza",
    active: true,
  }),
});

import requests

requests.post(
    "https://ingestia.io/api/scim/v2/Users",
    headers={
        "Authorization": "Bearer sp_live_EXEMPLO",
        "Content-Type": "application/scim+json",
    },
    json={
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName": "ana@example.com",
        "displayName": "Ana Souza",
        "active": True,
    },
)

Resultado esperado#

Login SSO cria/reaproveita o membro (JIT) e abre a sessão.
POST /Users responde 201 com o recurso SCIM do membro.
Desativação no IdP reflete em membro disabled no ingestia (acesso cortado).

Segurança#

Fail-closed: sem service principal válido → 401, sem tocar dados; SCIM não ligado em produção → 503 (nunca finge).
Escopo pelo SP: todo efeito usa o workspaceId/orgId do próprio service principal — um IdP não provisiona em org alheia.
Owner protegido: o papel do dono não é rebaixado por sincronização de grupo.
Papel por grupo: grupo desconhecido no mapa → viewer (menor privilégio).

Limites#

SSO e SCIM são Preview — sem SLA; podem mudar.
SCIM cobre Users e Groups (mapa grupo → papel); não há esquema custom de atributos de negócio por esta via.
Grupos SCIM mapeiam papéis, não atributos de RLS (atributos de linha são definidos no perfil do membro).

Erros comuns e diagnóstico#

Sintoma	Causa provável	O que fazer
`503` no SSO/SCIM	não ligado no ambiente	peça a ativação do SCIM no ambiente
`401` no SCIM	token não é service principal válido	use `Authorization: Bearer sp_live_…`
Pessoa entra com papel errado	grupo do IdP não mapeado	ajuste o mapa de grupos → papéis
Desativei no IdP e a pessoa some da lista	comportamento esperado (desativação)	o membro fica `disabled`; dados preservados

Relacionados#

Última revisão: 2026-09-08.

Estado & evidência: SSO empresarial e SCIM 2.0 = Preview (fail-closed, escopados por workspace, inertes até ligados). Fonte: matriz de estados do produto.