Configurar o provisionamento SCIM

Esta página mostra como conectar um sistema de provisionamento, como uma plataforma de RH ou um diretório de identidades, ao BreezeAuth. Os primeiros passos são feitos no console de administração do BreezeAuth, e os últimos no sistema de provisionamento.

Antes de começar

Permissões. Criar usuários de serviço e credenciais exige o papel Proprietário ou Administrador. Veja Papéis administrativos.
Verifique os seus domínios primeiro. As pessoas cujo e-mail está em um domínio verificado são criadas como usuários gerenciados. Todas as outras são convidadas e recebem um e-mail de convite. Se você conectar o sistema de provisionamento antes de verificar o seu domínio, todos os seus colegas serão convidados.
Confira o que o sistema de provisionamento suporta. Ele precisa falar SCIM 2.0 e conseguir obter tokens de acesso OAuth 2.0 com o fluxo client credentials. Veja a autenticação abaixo.

1. Crie um usuário de serviço para o sistema de provisionamento

Na barra lateral, selecione Usuários e depois Novo Usuário.
Em Tipo de usuário, escolha Usuário de serviço.
Informe um Nome que identifique o sistema de provisionamento, por exemplo “Provisionamento do RH”.
Em Papel administrativo, escolha Provisionador SCIM.
Selecione Criar usuário de serviço.

O papel Provisionador SCIM inclui exatamente o que o SCIM precisa, e nada além disso: ler, criar, atualizar e excluir usuários e grupos, e gerenciar os membros dos grupos. Não use o papel Administrador para o provisionamento: se a credencial vazasse, ela daria acesso a muito mais do que os seus usuários e grupos.

Veja Criar e gerenciar usuários de serviço para saber mais sobre usuários de serviço.

2. Crie uma credencial

Abra o usuário de serviço e selecione a aba Credenciais e depois Nova credencial.
Informe um Nome, por exemplo “Produção”, e, opcionalmente, uma data em Expira em.
Selecione Criar.
Copie o ID do cliente e o Client secret e guarde-os com segurança. O secret é exibido uma única vez.

Veja Credenciais de usuários de serviço para saber como guardar, rotacionar e desativar credenciais.

3. Encontre a sua URL base do SCIM

Cada organização tem a sua própria URL base do SCIM:

https://api.breezeauth.com/organizations/<ID da organização>/scim/v2

Para encontrar o ID da organização, selecione Organização na barra lateral do console de administração. O ID aparece abaixo do nome da organização, no topo da página Gerenciar Organização. Selecione o ícone de cópia ao lado dele (Copiar UUID) para copiá-lo.

Por exemplo, se o ID da sua organização for 0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d, a sua URL base do SCIM é:

https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2

4. Configure o sistema de provisionamento

No sistema de provisionamento, crie uma conexão SCIM, às vezes chamada de “aplicação SCIM” ou “conector de provisionamento”, com estas configurações:

Configuração	Valor
Versão do SCIM	2.0
URL base (tenant URL)	A sua URL base do SCIM, do passo anterior.
Método de autenticação	OAuth 2.0, concessão client credentials
URL do token (token endpoint)	`https://api.breezeauth.com/oauth/token`
Client ID e client secret	A credencial que você criou.
Identificador único de usuários	`userName`, que deve conter o endereço de e-mail da pessoa.
Identificador único de grupos	`displayName`

Importante: o BreezeAuth não emite tokens de API de longa duração. Os tokens de acesso expiram depois de alguns minutos, então o sistema de provisionamento precisa solicitá-los sozinho na URL do token, com o client ID e o secret, sempre que precisar de um novo. Um sistema que só permite colar uma única vez um “bearer token” ou uma “chave de API” fixa vai parar de funcionar quando esse token expirar. Nesse caso, os seus desenvolvedores podem manter um pequeno conector que obtém os tokens e repassa as requisições SCIM. Veja Obter tokens de acesso.

Mapeie os atributos

A maioria dos sistemas de provisionamento permite escolher quais dos seus atributos preenchem cada atributo SCIM. Mapeie pelo menos:

Atributo SCIM	Mapeie para
`userName`	O e-mail de trabalho da pessoa. Obrigatório.
`name.givenName`, `name.familyName`	Nome e sobrenome.
`active`	Se a pessoa deve ter acesso.
`externalId`	O identificador da pessoa no sistema de provisionamento.

Os outros atributos suportados, como cargo, telefones, departamento ou gestor, estão listados em Provisionar usuários.

5. Teste a conexão

A maioria dos sistemas de provisionamento tem um botão Testar conexão. Se quiser testar à mão, os seus desenvolvedores podem solicitar um token e ler a configuração do seu endpoint SCIM:

curl https://api.breezeauth.com/organizations/<ID da organização>/scim/v2/ServiceProviderConfig \
  -H 'Authorization: Bearer <token de acesso>'

Uma resposta 200 OK com um documento ServiceProviderConfig significa que a URL e a credencial estão corretas.

6. Comece o provisionamento

Comece com algumas pessoas de teste, por exemplo limitando o sistema de provisionamento a um pequeno grupo de teste.
No console de administração, confira em Usuários e Grupos se elas aparecem como esperado, com o Tipo de conta correto.
Nos Logs de Auditoria, filtre pelo usuário de serviço para ver cada mudança que ele fez.
Dê aos grupos provisionados acesso às suas aplicações.
Estenda o provisionamento a todos.

Mantenha a conexão segura

Restrinja de onde ela se conecta. Se o sistema de provisionamento faz as chamadas a partir de endereços IP conhecidos, limite os usuários de serviço a essas redes. Veja Restringir as redes de onde os usuários de serviço se conectam.
Rotacione a credencial regularmente, sem interrupção. Veja Rotacionar uma credencial.
Pare o provisionamento na hora desativando o usuário de serviço ou a credencial dele. O provisionamento para na próxima requisição; nada do que já foi provisionado é desfeito.