Provisione pessoas com SCIM

O que o provisionamento faz

• Quem entra. Atribua uma pessoa ao aplicativo no seu provedor e o screenRIG cria a conta dela e a torna membro da sua organização. Ela entra por login único e não tem senha. Ela fica sem projeto até que um grupo lhe dê um.
• Quem muda. Um grupo vinculado a um projeto dá esse projeto aos seus membros. Entrar no grupo ou sair dele adiciona ou remove o acesso.
• Quem sai. Desativar ou remover a atribuição de uma pessoa encerra as sessões e o acesso dela. Os agentes e os grants OAuth que uma pessoa aprovou continuam funcionando até que ela seja desativada, pelo provisionamento de usuários ou pela equipe do screenRIG: exigir login único e desativar a pessoa no seu provedor não os encerram.

Antes de começar

• Login único está configurado e a organização tem um domínio verificado. O provisionamento cria somente endereços nos seus domínios verificados.
• Você é administrador da organização.

Ativar

1. Em Configurações da organização, abra Provisionamento de usuários (SCIM) e escolha Ativar provisionamento. Copie a URL base, https://api.screenrig.ai/scim/v2. Ela fica na origem da API, não na do dashboard.
2. Em Tokens de provisionamento, escolha Criar token, informe um Nome do token (Entra, por exemplo) e confirme. Copie o token agora: srscim_ seguido de 43 caracteres, exibido uma única vez. O screenRIG guarda apenas um hash.

Ativar o provisionamento e criar um token pedem sua passkey ou senha. Uma sessão de login único conta, em vez disso, como login recente por 10 minutos, quando o seu provedor informa quando a pessoa se autenticou; caso contrário, o dashboard pede que a pessoa entre de novo no provedor.

Uma organização comporta até cinco tokens. Para rotacionar um, crie um novo token, cole-o no seu provedor e depois revogue o antigo; o provisionamento continua funcionando. A lista mostra quando cada token foi usado pela última vez. Desativar o provisionamento faz toda solicitação responder 403 e não altera o acesso de ninguém.

Microsoft Entra ID

1. Abra seu enterprise application (o que tem o login único), escolha Provisioning e defina Provisioning Mode como Automatic.
2. Em Admin Credentials, informe a base URL como Tenant URL e o token como Secret Token. Escolha Test Connection e depois Save.
3. Abra Mappings, Provision Microsoft Entra ID Users. Mapeie userName a partir de userPrincipalName (ou de mail quando seus user principal names não são os endereços com que as pessoas entram), emails[type eq "work"].value a partir de mail e deixe active no padrão, Switch([IsSoftDeleted], , "False", "True", "True", "False"). Mantenha os demais mapeamentos que o Entra propõe. O screenRIG usa o e-mail de trabalho, senão o e-mail principal, senão userName; esse endereço deve estar em um domínio verificado e ser o endereço que o seu login único envia.
4. Mantenha Provision Microsoft Entra ID Groups ativado para dar acesso por grupo.
5. Em Settings, defina Scope como Sync only assigned users and groups e depois atribua as pessoas e os grupos em Users and groups.
6. Defina Provisioning Status como On e salve. O Entra executa um primeiro ciclo e depois sincroniza aproximadamente a cada 40 minutos. Provision on demand sincroniza uma pessoa ou um grupo imediatamente.

Okta

1. Abra seu aplicativo screenRIG. Em General, edite App Settings e defina Provisioning como SCIM.
2. Abra Provisioning, Integration, Edit. Informe a base URL como SCIM connector base URL e userName como Unique identifier field for users, marque Push New Users, Push Profile Updates e Push Groups, e defina Authentication Mode como HTTP Header. Em um app SCIM personalizado, cole o token no campo HTTP Header. Onde o Okta pede um API Token (os apps de teste SCIM do Okta), informe Bearer, um espaço e o token. Os dois funcionam. Escolha Test Connector Configuration e depois Save.
3. Abra To App, Edit e ative Create Users, Update User Attributes e Deactivate Users. Deixe Sync Password desativado: o screenRIG ignora senhas.
4. Em Sign On, defina Application username format como Email.
5. Atribua as pessoas e os grupos em Assignments e faça o push dos grupos que você vincula em Push Groups.

O Okta desativa uma pessoa com active: false e nunca exclui.

Grupos e projetos

Os grupos provisionados aparecem em Configurações da organização, em Provisionamento de usuários (SCIM), em Grupos provisionados, com o número de membros e os projetos a que estão vinculados. Um grupo não dá acesso até que uma pessoa que pode aprovar em um projeto o vincule:

1. No projeto, abra Acesso e depois Grupos. Qualquer membro lê os vínculos; o proprietário do projeto, os membros que podem aprovar e os administradores da organização que são membros vinculam um grupo.
2. Em Vincular um grupo, escolha um Grupo e uma Função: Membro, uma associação simples, ou Aprovador, que também aprova revisões. Escolha Vincular grupo. Remover vinculação desvincula o grupo.

Uma vinculação também pode limitar o que concede a pastas de telas e telas, o mesmo escopo de telas a que um membro pode ser limitado: em Vincular um grupo, escolha Projeto inteiro ou Limitado a telas (uma vinculação de Aprovador nomeia apenas pastas). As telas de uma pessoa no projeto são a união dos escopos das suas vinculações, e toda vinculação sem escopo dá o projeto inteiro; a pessoa aprova apenas onde as suas vinculações de Aprovador cobrem todas essas telas, então Aprovador de uma pasta mais Membro do projeto inteiro faz dela um membro simples do projeto inteiro. O provisionamento nunca reduz um acesso concedido manualmente e não limita uma pessoa enquanto clientes de serviço que ela criou estiverem ativos: cada recusa desse tipo aparece na atividade recente do Provisionamento de usuários, e o escopo vale na próxima sincronização, depois que os clientes forem revogados. O escopo de uma vinculação é fixo; para alterá-lo, remova a vinculação e vincule o grupo de novo.

• Sem escopos, uma pessoa em vários grupos vinculados tem o papel mais alto: Aprovador acima de Membro.
• Entrar em um grupo ou sair dele adiciona ou remove a associação. Desvincular um grupo, ou excluí-lo no seu provedor, retira o que ele concedeu.
• O provisionamento remove apenas o que adicionou. Uma associação concedida manualmente permanece, e um membro que um grupo elevou a Aprovador volta ao que tinha ao sair do grupo.
• Uma organização comporta até 200 membros em todos os seus projetos, contando cada pessoa uma vez. Uma pessoa que ela recusa é registrada como falha nos eventos de provisionamento e nada mais muda.
• Os grupos concedem apenas papéis de projeto, nunca administrador da organização. Os administradores veem vínculos e nomes de projetos, não o conteúdo dos projetos.

Quem pode ser provisionado

• Um endereço em um domínio verificado sem conta cria uma, sem senha.
• Uma pessoa que não tem senha nem passkey, que sua organização gerencia ou que está em uma organização que exige login único tem a conta assumida e entra por login único.
• Uma pessoa que já tem um login próprio e é membro de um dos projetos da sua organização é vinculada somente para acesso, a menos que sua organização exija login único. O provisionamento gerencia o acesso dela aos seus projetos e nunca o nome, o e-mail ou o login.
• Qualquer outra pessoa é recusada com um erro que informa o motivo: uma conta com login próprio que não é membro dos seus projetos, uma pessoa que outra organização gerencia e a equipe do screenRIG. Convide essa pessoa para um dos seus projetos primeiro, e então o provisionamento a vincula para acesso.

Desativação e DELETE

active: false, enviado por PUT ou PATCH, e DELETE encerram o acesso de uma pessoa. active: true reverte uma desativação, como indicam as tabelas.

Uma pessoa desativada por qualquer um que não seja o seu provisionamento, como a equipe do screenRIG, continua desativada: active: true falha com 400 mutability. Um projeto de propriedade de uma pessoa nunca é transferido: uma pessoa vinculada mantém o acesso a ele, e o projeto de uma pessoa gerenciada aguarda com o restante da conta dela até a reativação. Transfira a propriedade antes de desativar o proprietário, se outras pessoas precisarem continuar a gerenciá-lo. O último administrador da organização não pode ser desativado como pessoa gerenciada; a requisição falha com 400 mutability, então adicione antes outro administrador.

Referência

URL base https://api.screenrig.ai/scim/v2. O token vai em Authorization: Bearer srscim_TOKEN, e um token sozinho também é aceito. As solicitações e respostas são application/scim+json; application/json é aceito.

Os filtros têm de um a quatro termos attribute eq value unidos por and. Um valor é uma string entre aspas, ou true ou false para active. Os usuários filtram por userName (sem distinção entre maiúsculas e minúsculas), externalId (exato), id, emails ou emails.value, displayName e active. Os grupos filtram por displayName, externalId, id e members ou members.value. Qualquer outra coisa é 400 invalidFilter.

PATCH lê as operações do jeito que o Entra e o Okta as enviam, com ou sem ?aadOptscim062020. Os nomes das operações não diferenciam maiúsculas de minúsculas, e os booleanos são true, false, "True" ou "False". Uma operação pode omitir path ou usar chaves com pontos, como {"name.givenName": "Ada"}. Os caminhos incluem emails[type eq "work"].value, members (add, replace e remove com um array de valores) e members[value eq "<id>"] (remove). Atributos que o screenRIG não usa são aceitos e ignorados.

Limites. Uma organização pode enviar 600 solicitações por minuto somando todos os seus tokens, e não por endereço, porque o Entra e o Okta compartilham endereços de origem. Acima do limite, a resposta é 429 com Retry-After. As autenticações com falha são limitadas a 30 a cada 10 minutos para cada endereço.

Os erros usam o envelope SCIM com scimType, como invalidFilter, uniqueness ou mutability:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "409", "scimType": "uniqueness", "detail": "…" }

O Provisionamento de usuários em Configurações da organização lista as 500 solicitações mais recentes, mantidas por 30 dias, incluindo as falhas com o motivo. Olhe lá primeiro quando algo não chegar.

Solução de problemas

Relacionado

• Login único: conecte Entra ID, Okta, Google Workspace ou outro provedor e torne-o obrigatório.
• Autenticação: como os agentes entram e como o acesso é aprovado.
• Referência da API: as rotas /scim/v2 e as de provisionamento.