SSO (SAML 2.0 + OIDC) and SCIM 2.0 stay off until they are enabled for your organization. To enable them, contact support.
Integrate ingestia.io with your company's identity provider (IdP): single sign-on (SSO) and automatic user provisioning/deprovisioning (SCIM).
What it is#
- SSO (SAML 2.0 / OIDC): people sign in via the corporate IdP (Okta, Microsoft Entra ID, Google Workspace…) without a local password. With JIT provisioning, the first login already creates the member in the workspace.
- SCIM 2.0: the IdP pushes user creation, updates and deactivations (and maps groups → roles) to ingestia.io, keeping the directory synchronized.
What it's for#
- Centralize access in the IdP (a person leaves the company → loses product access).
- Standardize roles by IdP group (e.g., group "BI-Admins" → role
admin). - Audit onboarding/offboarding without manual work.
Plan and permissions#
- Plan: from Scale (enabled on request) — see Planos.
- Who configures: owner of the workspace /
org_admin, together with the platform operator (IdP envs). - SCIM authentication: by service principal (token
sp_live_…) — not a data key. The provisioning scope is always the workspace/org of the service principal itself, never coming from the URL/body (anti cross-tenant).
Prerequisites#
- IdP with support for SAML 2.0 or OIDC and (to sync) SCIM 2.0.
- SSO enabled in the environment (handshake secret provisioned). Without this,
the SSO route responds
503and the SCIM route responds503in production — it never pretends to provision. - For SCIM: SCIM activation in the environment (done by us) and, optionally, the mapping of your IdP groups to product roles.
Step-by-step (overview)#
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).
SCIM endpoint (reference)#
Base: https://ingestia.io/api/scim/v2 · Content-Type application/scim+json.
| Method · route | Effect |
|---|---|
GET /Users (+?filter=) | lists members (filter userName/externalId eq) |
POST /Users | provisions member (role resolved from groups) |
PUT /Users/{id} | replaces member attributes |
PATCH /Users/{id} | active:false → deactivates (safe deprovisioning) |
DELETE /Users/{id} | safe deprovisioning → deactivates (never deletes data) |
GET /Groups · PATCH /Groups/{id} | mapped groups; add → group's role, remove → viewer |
GET /ServiceProviderConfig | discovery (no effect) |
Deprovisioning is always non-destructive
DELETE and PATCH active:false deactivate the member (access revoked immediately),
but never delete data. Data removal is a separate, explicit data deletion flow:
exclusão de dados.
Example (SCIM — synthetic)#
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,
},
)Expected result#
- SSO login creates/reuses the member (JIT) and opens the session.
POST /Usersresponds201with the member's SCIM resource.- Deactivation in the IdP is reflected as the member being
disabledin ingestia (access cut).
Security#
- Fail-closed: without a valid service principal →
401, no data touched; SCIM not enabled in production →503(never pretends). - Scope by SP: all effects use the
workspaceId/orgIdof the service principal itself — an IdP cannot provision into another org. - Owner protected: the owner's role is not downgraded by group synchronization.
- Role by group: unknown group in the map →
viewer(least privilege).
Limits#
- SCIM covers Users and Groups (group → role map); there is no custom business attribute schema via this channel.
- SCIM groups map to roles, not row-level security attributes (RLS) (row attributes are defined in the member profile).
Common errors and how to fix them#
| Symptom | Likely cause | What to do |
|---|---|---|
503 on SSO/SCIM | not enabled in the environment | request SCIM activation in the environment |
401 on SCIM | token is not a valid service principal | use Authorization: Bearer sp_live_… |
| Person signs in with wrong role | IdP group not mapped | adjust the group → role map |
| I deactivated in the IdP and the person disappears from the list | expected behavior (deactivation) | the member becomes disabled; data preserved |
Related#
Last review: 2026-09-08.