# Para quem administra

> Como cuidar das pessoas, das empresas, dos sistemas e dos acessos na Central de Identidade, de
> acordo com o seu papel.

Quem administra a central nem sempre faz a mesma coisa: alguém do RH cuida de pessoas, alguém de
tecnologia cuida dos sistemas que usam a central para login. Por isso, cada seção desta página
começa dizendo **qual papel ela exige**. Se você não tem o papel, a seção não aparece no seu menu
e você pode pulá-la.

Nas telas de administração, o ícone de interrogação ao lado do título abre, em uma nova aba, a
seção desta página que explica aquela tela.

Para o básico de quem só usa a central (entrar, contas Google, emails), veja
[Para quem usa](/docs/users.md).

## Papéis

Os papéis aparecem no menu lateral, embaixo do seu nome. Cada um libera uma parte da central:

| Papel | O que libera |
|---|---|
| Leitor de pessoas | Menu "Pessoas" só para consulta: vê a lista e a página de cada pessoa, sem botões de alteração. |
| Administrador de pessoas | Tudo do leitor de pessoas, mais cadastrar e cuidar das pessoas, inclusive os grupos de cada uma. |
| Leitor de diretório | Menu "Diretório" só para consulta: empresas, grupos, permissões e sistemas, sem botões de alteração. |
| Administrador de diretório | Tudo do leitor de diretório, mais criar, editar e excluir nessas telas. |
| Administrador global | Tudo dos administradores de pessoas e de diretório, mais os menus "OAuth2" e "Auditoria" (com o "Relatório de acesso"). |
| Super administrador | Tudo do administrador global, mais impersonar outras pessoas. |

O papel "Administrador de sessões" ainda não libera nada: ele existe para uma função futura.

Você só consegue dar a alguém os papéis que você mesmo tem. Um administrador de pessoas, por
exemplo, só concede "Administrador de pessoas" e "Leitor de pessoas". Os papéis acima do seu nem aparecem na tela e
continuam como estão.

## Pessoas

*Exige: Leitor de pessoas para consultar; Administrador de pessoas para alterar.*

Tudo acontece em "Pessoas" › "Usuários". A lista mostra um cartão por pessoa, com email principal,
organização, organizações atendidas, papéis e os grupos a que a pessoa pertence diretamente.
Clicar em qualquer ponto do cartão abre a página da pessoa; o menu de ações (os três pontinhos)
fica no canto do cartão.

A página da pessoa (**"Visualizar"** no menu) reúne num lugar só emails, vínculo profissional,
papéis, grupos e permissões, contas Google e Slack, cada bloco com o atalho para editá-lo. O botão
"Ações" tem as demais ações, e "Voltar" retorna à lista.

Os filtros da lista só se aplicam ao clicar em "Filtrar"; "Limpar" volta ao que a lista mostra ao
abrir: só as pessoas ativas. O botão "Filtros" mostra quantos filtros estão aplicados, como
"Filtros (1)" (o status "Ativos" padrão conta; "Todos os status" não), mesmo com o painel fechado.
Todos se combinam:

- **Nome ou email**: busca por pedaços separados por espaço, e cada pedaço precisa aparecer no
  nome ou num email da pessoa: "jul bata" acha Juliano Borges, batata@gmail.com. Não diferencia
  maiúsculas nem acentos ("joao" acha "João") e vale qualquer email da pessoa, verificado ou não.
- **Papel** e **Status**: "Ativos" (o padrão), "Desativados" ou "Todos os status". Para ver quem
  foi desativado, troque o status.
- **Empresa contratante**: uma empresa, ou "Freelancer" para quem não tem empregador.
- **Empresa servida**: quem atende aquela empresa.
- **Grupo**: quem está naquele grupo ou em qualquer subgrupo dele.
- **Permissão**: quem tem aquela permissão, ou seja, os membros do grupo que a concede e de todos
  os grupos acima dele.

No cartão, o email principal vem primeiro. O confirmado leva um "✓" de "Verificado" e o que
ainda espera confirmação leva um "?" vermelho de "Pendente"; havendo outros emails, um selo como
"+2" os conta (passe o mouse para ver quais).

Acima dos cartões, o botão "Ordenar" escolhe entre "Nome" e "Organização", e o
botão ao lado inverte a ordem. Quem não tem organização (freelancer) vem primeiro
na ordem crescente, e empates saem por nome. Os filtros mantêm a ordenação; "Limpar" volta à ordem
por nome. A lista tem 24 pessoas por página, com a paginação numerada acima e abaixo dos cartões;
mudar a ordem volta à página 1.

Pessoa desativada aparece com o cartão apagado e um ícone de arquivo ("Usuário desativado");
quem tem Slack vinculado e quem é reclamável também levam seu ícone.

### Alguém de uma empresa do grupo vai começar a usar

**Você não precisa fazer nada.** Quem tem conta Google de uma empresa cadastrada na central se
cadastra sozinho no primeiro login. Depois disso, a pessoa já aparece na lista e você pode ajustar
o cadastro dela.

### Um freelancer precisa de acesso

Freelancers não têm conta Google de uma empresa do grupo, então precisam ser cadastrados antes:

1. Clique em "Novo usuário" e preencha nome e email.
2. Com "Enviar convite por email" marcada (o padrão), a central manda na hora um email de convite
   para esse endereço, com o link de entrada. Desmarque para cadastrar sem avisar a pessoa; ela
   continua podendo entrar depois, e você pode usar "Reenviar convite" quando quiser.
3. A pessoa entra com a conta Google **desse mesmo email**. Pode ser um Gmail ou uma conta Google
   criada com o endereço dela. Ao entrar, o cadastro passa a ser dela.

**Cadastre o email que a pessoa usa como conta Google.** Se ela entrar com uma conta Google de
outro email, o login é recusado. O convite não expira; se a pessoa perdeu o email, use "Reenviar
convite" no menu dela. Na lista, quem ainda não entrou aparece com uma folha azul de
"Reclamável".

Na mesma tela, a seção "Vínculo profissional" permite já informar empregador e empresas atendidas (veja abaixo); dá para ajustar depois. Freelancer é quem fica sem empregador.
A central não adivinha o empregador pelo email: se for preciso, escolha.

### Alguém perdeu acesso a todas as contas Google

1. No menu da pessoa, use "Tornar reclamável". O cadastro volta a funcionar como um convite.
2. Use "Reenviar convite" para avisar a pessoa. **"Tornar reclamável" sozinho não manda email.**
3. A pessoa entra com uma conta Google de qualquer email confirmado do cadastro e retoma o
   cadastro.

Nada se perde: emails, papéis, vínculo e contas Google que ainda existirem continuam lá.

É o mesmo caminho pra quem vê **"Já existe um cadastro com o email …"** ao entrar com uma conta
Google nova: a central não junta os cadastros sozinha. Se o email for de outra pessoa, que herdou o
endereço de alguém que saiu, **ainda não há como resolver isso pela tela**.

### Corrigir os dados de alguém

- **Nome, email e Slack**: "Editar". O email só aparece aqui enquanto a pessoa não tem nenhum
  email confirmado (convite pendente): é o endereço do convite, e dá para corrigi-lo livremente.
  Depois do primeiro email confirmado, o campo some e a tela aponta para "Emails". Na seção "Slack", informe o ID do usuário (começa com U ou W) e o
  ID do team (começa com T), **os dois ou nenhum**. A tela diz onde achar cada um. O mesmo par
  não pode estar em duas pessoas. Na lista de usuários, quem tem conta no Slack vinculada aparece
  com o ícone do Slack depois do nome.
- **Empresas**: "Vínculo profissional". "Empregador" é a empresa que
  contratou a pessoa (vazio quer dizer freelancer). "Organizações atendidas" são as empresas para
  as quais ela trabalha, que podem ser várias.

Os outros sistemas recebem esses dados quando a pessoa entra neles pela central.

### Cuidar dos emails de alguém

O item "Emails" do menu da pessoa abre a mesma tela que ela tem, com uma ação a mais:

- **Adicionar email**: a central manda para o endereço um link de confirmação, que vale por 2
  dias. Quem confirma é a pessoa, clicando no link. O email principal dela recebe um aviso do
  novo endereço.
- **Tornar primário**: muda o email principal, que é o que os outros sistemas veem. Só um email
  confirmado pode ser o principal. **Depois que a pessoa tem um email confirmado, esta é a
  única tela que troca o email principal**; o "Editar" não mostra mais o campo. O principal
  anterior recebe um aviso da troca.
- **Remover**: apaga um email que não seja o principal.
- **Verificar (override)**: marca um email como confirmado sem o link. **Use só quando a pessoa
  perdeu acesso à caixa de entrada**: a ação fica registrada na auditoria com o seu nome. Este
  caminho **não envia aviso**.

Um email confirmado pertence a uma pessoa só. Se outra pessoa já confirmou o endereço, ele não
pode ser confirmado em outro cadastro.

### Dar ou tirar um papel

Use "Papéis" no menu da pessoa e marque ou desmarque. A tela só mostra os papéis que você pode
conceder (veja [Papéis](#papéis)). **Cuidado ao mexer nos seus próprios papéis**: a central não
impede que você tire um papel de si mesmo.

### Colocar alguém em grupos

Use "Grupos" no menu da pessoa e marque os grupos a que ela pertence **diretamente**; ao salvar,
a lista fica exatamente como marcada. Os grupos e o que cada um libera são cuidados em
[Grupos](#grupos). Quem tem o papel de diretório também faz isso pelo lado do grupo.

### Alguém saiu da empresa

Use "Desativar" no menu da pessoa. A sessão dela na central é encerrada, ela **não consegue mais
entrar** e os acessos que a central tinha liberado para ela são revogados. O cadastro não é
apagado: o histórico continua e o email segue ocupado.

Desativar **pode ser desfeito**: "Reativar" devolve o acesso. Você não consegue desativar a si
mesmo.

## Diretório

*Exige: Leitor de diretório para consultar; Administrador de diretório para alterar.*

### Organizações

Uma organização é uma empresa do grupo. Ela tem nome e domínio.

O domínio é **o domínio do Google Workspace da empresa** (por exemplo, `vetorzero.com.br`).
Cadastrar uma organização libera o cadastro automático de **todo mundo** que entrar com uma conta
Google desse Workspace. O domínio é guardado em minúsculas e precisa ser um domínio válido, com
ponto (`"{domínio}" não é um domínio válido.` caso contrário).

**Uma organização não pode ser editada nem apagada depois de criada.** Confira o nome e o domínio
antes de salvar.

### Grupos

Grupos dizem onde a pessoa está na estrutura da empresa (por exemplo, Produção › 2D › Animação 2D)
e, com isso, o que ela pode nos outros sistemas. Em "Grupos" você vê a lista, com os subgrupos
recuados por um marcador, o slug, o número de membros e as permissões de cada grupo.

- **Estrutura**: cada grupo tem no máximo um "Grupo pai"; sem pai, é raiz de uma árvore. Pode haver
  várias árvores, e um grupo sem ninguém é válido (serve só de estrutura). Uma pessoa pode estar em
  vários grupos. Dá para mover um grupo para outro lugar, mas não para baixo dele mesmo.
- **Nome**: único entre todos os grupos, sem diferenciar maiúsculas nem acentos. Prefira
  "Diretoria de Vendas" a "Diretoria".
- **Slug**: a chave que os outros sistemas recebem e guardam. Único entre todos os grupos, só com
  letras minúsculas, dígitos e sublinhado ("animacao_2d"). Em branco na criação, é derivado do
  nome. **Trocá-lo faz com que os sistemas deixem de reconhecer o grupo** até serem atualizados;
  mudar o nome não muda o slug.
- **Permissões**: marque as que o grupo concede. **Cada grupo também recebe as permissões de todos
  os seus subgrupos**: quem está num grupo mais acima pode o que os de baixo podem. Na lista, as
  herdadas aparecem apagadas.
- **Membros**: "Membros" no menu do grupo abre a lista, com "Adicionar membro" e "Remover". Pessoa
  desativada continua na lista, com a linha apagada.
- **Página do grupo**: clicar no nome do grupo abre a página dele, com a árvore em que ele está,
  as permissões (as herdadas dizem de qual subgrupo vêm) e os membros, que levam à página de cada
  pessoa.
- **Mapa**: o botão "Mapa" no alto de "Grupos" (mesmo acesso da lista) desenha a estrutura da
  esquerda para a direita, com as pessoas ativas como folhas dos grupos a que foram atribuídas;
  quem está em vários grupos aparece em cada um, e passar o mouse sobre a pessoa destaca as outras
  ocorrências. Todo grupo aparece, mesmo sem ninguém, e pessoa desativada não entra.
  Clicar num grupo abre a página dele e numa pessoa, a página dela. Clicar numa permissão destaca
  onde ela foi dada (borda cheia) e quem a recebe de um subgrupo (borda tracejada); clicar de novo
  limpa. Quem administra o diretório vê ainda, no canto superior direito de cada grupo, os atalhos
  "Editar grupo" e "Adicionar pessoas" (aparecem ao passar o mouse ou focar o grupo; em telas de
  toque ficam sempre visíveis).
- **Excluir**: a central recusa enquanto o grupo tiver subgrupos ou membros.

### Permissões

Uma permissão é uma capacidade que os sistemas conferem, como `ferias.aprovar`. O catálogo vale
para todos os sistemas e deve ter **poucas permissões, abstratas**. Em "Permissões" você cria,
edita e exclui, e escolhe a quais grupos cada uma é dada.

- **Slug**: letras minúsculas e dígitos, palavras separadas por sublinhado e segmentos por ponto.
  Como no grupo, trocá-lo faz os sistemas deixarem de reconhecer a permissão.
- **Descrição**: o que ela libera, para quem for concedê-la.
- **Excluir**: a central recusa enquanto a permissão estiver dada a algum grupo.
- **Usuários** (menu da permissão, para quem vê pessoas): abre a lista de pessoas filtrada por
  essa permissão.

A pessoa leva **todas** as suas permissões para todo sistema que pedir o acesso a grupos, não só
as do sistema que ela está abrindo. Mudanças na estrutura aparecem no próximo login da pessoa nele.

### Apps

Os apps são os sistemas que aparecem na página inicial. Cada um tem:

- **Nome** e **descrição**, como aparecem na página inicial.
- **URL**: para onde a pessoa vai ao clicar. De preferência, a URL que já começa o login.
- **Client OAuth2** (opcional): o client que o sistema usa para login na central (veja
  [Clients OAuth2](#clients-oauth2)). Com ele, cada login pelo sistema conta como um acesso, e é
  isso que ordena a página inicial de cada pessoa.
- **Organizações**: "Todas" (o padrão) ou uma ou mais empresas. A página inicial mostra o app a
  quem atende alguma delas. Isso só esconde o app da lista: quem tiver o endereço ainda faz login
  nele, e abrir um app escondido conta como acesso. Não dá para misturar "Todas" com empresas
  específicas, nem deixar vazio.

Excluir um app apaga também as contagens de acesso e os favoritos de todo mundo nele.

## Clients OAuth2

*Exige: Administrador global.*

Um client é o cadastro de um sistema que usa a central para login. É assim que a central sabe que
um pedido de login vem mesmo daquele sistema. Os detalhes de cada campo estão em
[Para quem desenvolve](/docs/developers.md); aqui fica o que você precisa saber para cuidar
deles.

- **Lista**: a primeira coluna, sem cabeçalho, mostra ícones: cadeado fechado para client
  confidencial, cadeado aberto para público e, se estiver desativado, um ícone de arquivo
  ("Client desativado") com a linha inteira apagada.
- **Filtros**: o botão "Filtros" abre o painel com "Nome ou identificador" (vários termos, sem
  diferenciar maiúsculas nem acentos), "Tipo" (Confidenciais ou Públicos) e "Status". A lista abre
  só com os clients ativos; use "Todos os status" ou "Desativados" para ver os demais. Valem as
  mesmas regras dos filtros de usuários: só aplicam ao clicar em "Filtrar", e "Limpar" volta ao
  padrão.
- **Formulário**: o cadastro e a edição têm três seções lado a lado: "Identificação"
  (identificador, nome e confidencial), "OAuth2/OIDC" (grants, scopes, redirect URIs e
  post-logout URIs) e "API" (acesso à API, papéis e IPs). Na edição, "Confidencial" aparece
  desabilitado.
- **Novo client**: o identificador não muda depois. Um client **confidencial** recebe um secret,
  uma espécie de senha do sistema; um **público** não tem secret. Essa escolha também não muda
  depois.
- **Nome do identificador**: por convenção, `app-*` para sistema em que pessoas fazem login e
  `srv-*` para sistema que chama a API por conta própria, sem pessoa logada. O fim indica o
  ambiente: `-prod` em produção, `-dev-<nome>`, `-hml-<nome>` ou `-beta-<nome>` nos ambientes de
  quem desenvolve (ex: `app-ferias-prod`, `app-ferias-dev-maria`).
- **Duplicar** (no menu de ações da lista) abre o cadastro de novo client já preenchido com a
  configuração do original: nome, grants, scopes, redirect URIs, post-logout URIs, acesso à API
  (papéis e IPs) e se é confidencial. Falta só informar o identificador. O secret é sempre novo;
  vínculo com app, tokens e status (ativo ou desativado) não são copiados.
- **O secret aparece uma vez só**, na mensagem de confirmação. Copie e entregue a quem
  desenvolve o sistema na hora: depois, nem a central consegue mostrar de novo.
- **Rotacionar secret** gera um secret novo (só existe em client confidencial). **O sistema
  para de funcionar** até ser atualizado com o novo secret.
- **Tokens** lista os acessos ativos emitidos para o client, com a expiração de cada um ("em 40
  minutos"), e **Revogar tokens** derruba todos eles.
- **Desativar** bloqueia o client sem apagar; **Excluir** apaga de vez, revoga os tokens e não
  pode ser desfeito.
- **Acesso à API**: libera o client para usar a API da central, com os papéis que ele terá lá (os leitores bastam para só consultar) e
  os IPs de onde pode chamar (sem nenhum IP, qualquer um é aceito).
- **Webhook**: no campo "URL de webhook" (seção "API", só para client com acesso à API), o client
  recebe um aviso a cada mudança que os papéis dele deixam ver; em branco, sem webhooks. Depois
  de salvar, a edição mostra o "Estado": "Entregando", "Falhando" (com a próxima tentativa e o
  último erro, só o status HTTP ou o erro de rede) ou "Pausado", quando falha por cerca de 24h.
  "Retomar agora" volta a entregar do ponto em que parou, sem perder aviso (fica na auditoria);
  trocar a URL também tira da pausa. "Enviar evento de verificação" testa o receptor na hora. A
  lista de clients marca os pausados com o ícone "Webhook pausado". O formato do aviso está em
  [Para quem desenvolve](/docs/developers.md#receber-webhooks).

## Auditoria

*Exige: Administrador global.*

"Auditoria" › "Log de auditoria" mostra quem mudou o quê na central: quando, quem fez, por onde
(web, linha de comando ou API), a ação e o alvo. Ações feitas por alguém impersonando aparecem
com o nome de quem estava impersonando. Datas e horas aparecem no horário de Brasília: as recentes
de forma curta ("ontem, 14:05"), e parar o mouse sobre qualquer uma mostra a data completa.

Os filtros (aplicados ao clicar em "Filtrar") aceitam ação, tipo de alvo, ator e alvo. **Ator e alvo precisam do email, id ou nome
exatos**, sem busca por pedaço. Outro caminho: o item "Histórico" no menu de cada pessoa,
organização, grupo, permissão, app ou client abre a auditoria já filtrada nele.

### Relatório de acesso

"Auditoria" › "Relatório de acesso" lista todas as pessoas numa página só, com papéis, grupos
diretos e permissões. Serve para investigar um caso ("por que ela
não consegue entrar em tal sistema?"), não para o dia a dia: não tem filtro nem paginação. Nas
permissões, as herdadas de um subgrupo aparecem em cinza, e parar o mouse sobre qualquer uma mostra
os grupos de onde ela vem. Para saber quem tem uma permissão, o filtro "Permissão" em "Usuários" é
mais direto.

## Impersonar

*Exige: Super administrador.*

Impersonar é ver a central como outra pessoa vê, para entender um problema dela. Use "Impersonar"
no menu da pessoa: você vai para a página inicial dela, com uma faixa amarela no topo. Para
voltar, use "Parar de impersonar" na faixa (ou "Desimpersonar", no fim do menu lateral).

Enquanto impersona:

- **Você não entra nos outros sistemas como a pessoa**: em produção, a central recusa o login
  neles. Só nos ambientes de teste (a faixa de segurança no topo das telas indica) isso é liberado.
- Você não consegue vincular contas Google à pessoa.
- **Tudo o que você mudar fica registrado na auditoria com o seu nome.**

Não dá para impersonar a si mesmo nem uma pessoa desativada.