Como configurar SCIM para provisionamento de usuários na Nvoip

Este artigo explica como funciona o SCIM da Nvoip, quais URLs usar e o que acontece quando o provedor cria, atualiza ou desativa usuários.

Resumo: SCIM não é login. SCIM é provisionamento de usuários. O login continua acontecendo por OIDC ou SAML.

O que é SCIM?

SCIM significa System for Cross-domain Identity Management. É um padrão usado por provedores como Microsoft Entra ID e Okta para criar, atualizar e desativar usuários em aplicativos externos.

Com SCIM, o administrador da empresa pode controlar o ciclo de vida do usuário no diretório corporativo. Quando o usuário entra na empresa, o provedor cria o acesso na Nvoip. Quando muda dados ou é desativado, o provedor envia essa alteração para a Nvoip.

Quando usar SCIM

Quando a empresa tem muitos usuários e não quer criar acessos manualmente.
Quando o desligamento de usuários precisa desativar o acesso automaticamente.
Quando o diretório corporativo deve ser a origem dos dados básicos do usuário.
Quando a empresa usa Microsoft Entra ID, Okta ou outro provedor compatível com SCIM 2.0.

Pré-requisitos

Conta Nvoip de cliente final no plano Pro.
SSO corporativo configurado na Nvoip por OIDC ou SAML.
Token SCIM criado na aba SCIM da Nvoip.
Provedor de identidade com suporte a SCIM 2.0.

URLs do SCIM da Nvoip

Item	Valor
Base URL	`https://painel.nvoip.com.br/api/scim/v2`
ServiceProviderConfig	`https://painel.nvoip.com.br/api/scim/v2/ServiceProviderConfig`
Usuários	`https://painel.nvoip.com.br/api/scim/v2/Users`

Autenticação

Use Bearer Token no header Authorization:

Authorization: Bearer TOKEN_SCIM_GERADO_NA_NVOIP

O token é exibido somente no momento da criação. Se perder o token, revogue o token antigo e gere outro.

Como criar token SCIM na Nvoip

Acesse Configurações > SSO corporativo.
Abra a aba SCIM.
Informe um nome para o token, como Microsoft Entra ID ou Okta.
Clique em Criar token.
Copie o token exibido e cole no provedor.

Operações suportadas

Operação	Endpoint	Efeito na Nvoip
Listar usuários	`GET /Users`	Retorna usuários da conta para o provedor.
Buscar usuário	`GET /Users/{id}`	Retorna um usuário específico.
Criar usuário	`POST /Users`	Cria usuário secundário se o e-mail ainda não existir.
Atualizar usuário	`PUT /Users/{id}`	Atualiza dados básicos do usuário.
Atualização parcial	`PATCH /Users/{id}`	Usado principalmente para alterar `active`.
Remover usuário	`DELETE /Users/{id}`	Desativa o usuário na Nvoip. Não apaga permanentemente.

Atributos recomendados

Atributo SCIM	Uso
`userName`	E-mail principal do usuário. É o principal identificador usado para localizar ou criar o usuário.
`emails[0].value`	E-mail do usuário, usado como fallback se necessário.
`name.givenName` e `name.familyName`	Nome e sobrenome.
`displayName`	Nome completo exibido.
`active`	Quando `false`, o usuário é bloqueado/desativado na Nvoip.

SCIM e permissões

Na implementação atual, usuários criados pelo SCIM entram como usuário secundário. O SCIM não aplica permissões detalhadas do painel nem mapeia grupos para permissões internas.

Para controlar quem pode entrar, use as regras do SSO:

Domínio verificado.
Grupo permitido vindo do IdP.
SSO forçado após validação.

Para controlar o que o usuário pode acessar dentro do painel, ajuste as permissões do usuário na Nvoip depois que ele for criado.

Como testar com segurança

Configure SSO e valide o login com um usuário de teste.
Crie o token SCIM.
No provedor, configure a conexão SCIM.
Use Test Connection no provedor.
Provisione um único usuário de teste.
Confira se o usuário apareceu na Nvoip como usuário secundário.
Altere o nome do usuário no provedor e valide atualização.
Desative o usuário no provedor e valide se ele foi bloqueado na Nvoip.

Erros comuns

Erro	Causa provável
401 ou não autorizado	Token ausente, token revogado ou token copiado incorretamente.
Usuário duplicado no provedor	O provedor pode estar enviando outro identificador. Use e-mail corporativo em `userName`.
Usuário criado, mas sem permissões esperadas	SCIM cria usuário secundário; permissões detalhadas precisam ser configuradas na Nvoip.
Usuário não consegue logar após SCIM	SCIM não autentica. Confirme se OIDC ou SAML está ativo e se o usuário passa nas regras de domínio/grupo.