GBS Auth

1. Visão Geral

O GBS Auth é uma aplicação web de gerenciamento de autenticação e autorização baseada em OIDC (OpenID Connect). A ferramenta atua como broker de autenticação para provedores de identidade externos (ex.: Google Workspace, Gov.br), emite seus próprios tokens de acesso, e fornece um painel administrativo para gerenciamento de usuários, funções (roles), permissões e auditoria.

Este guia abrange a utilização da aplicação GBS Auth — as telas de gerenciamento de funções, usuários e auditoria. Ele pode ajudá-lo com:

• Entendendo o que cada tela exibe e quais ações estão disponíveis

• Criando e gerenciando funções (roles) e permissões

• Criando e gerenciando usuários e identificadores externos

• Atribuindo funções a usuários

• Consultando o histórico de auditoria

2. Login

O GBS Auth utiliza autenticação via OpenID Connect integrada ao Provedor de Identidade (IdP). O fluxo de login é:

1

Acesse o GBS Auth

Acesse a URL do GBS Auth no navegador.

2

Faça login

Você será redirecionado para a tela de login do provedor de identidade configurado.

Insira suas credenciais (usuário e senha).

3

Retorne ao GBS Auth

Após a autenticação, você será redirecionado de volta ao GBS Auth.

Suas iniciais e nome aparecem no canto superior direito da tela.

Para fazer logout, clique no seu nome no canto superior direito e selecione Sair.

2.1. Se o login falhar

O Que Você Vê	O Que Significa	O Que Fazer
Tela de login do IdP não carrega	O IdP está inacessível	Verifique sua conexão de rede e tente novamente. Se persistir, contate o suporte.
Credenciais inválidas	Usuário ou senha incorretos	Verifique suas credenciais. Use "Esqueci a senha" se disponível no IdP.
"Completing sign in..." fica carregando	Callback OAuth falhou	Clique em "Tente novamente". Se persistir, limpe os cookies e cache do navegador.
Mensagem de erro com ícone de triângulo amarelo	Falha na troca de tokens ou state mismatch	Clique em "Tente novamente". Se persistir, limpe sessionStorage e tente novamente.
Telas vazias ou itens de menu ausentes após login	Você não possui permissões atribuídas	Contate o administrador para verificar suas funções e permissões.

3. Navegação

A barra lateral esquerda contém o menu principal de navegação. Os itens disponíveis dependem das suas permissões:

Item do Menu	Ícone	Permissão Necessária	Descrição
Dashboard	Layout (grid)	Nenhuma	Visão geral do sistema
Funções	Escudo	auth:roles:write	Gerenciamento de funções
Usuários	Pessoas	Nenhuma	Gerenciamento de usuários
Auditoria	Documento	auth:audit-logs:read	Histórico de auditoria

O menu pode ser recolhido clicando no botão de colapso na parte inferior da barra lateral, exibindo apenas os ícones para ganhar mais espaço de trabalho. Quando recolhido, o nome de cada item aparece como tooltip ao passar o mouse.

4. Dashboard

A tela inicial exibe três cartões com contadores:

Cartão	Informação	Ação
Total de Funções	Quantidade de funções definidas	Link "Ver todas as funções"
Total de Permissões	Quantidade de permissões disponíveis	Link "Ver Funções"
Usuários	Quantidade de usuários registrados	Link "Gerenciar Usuários"

Os contadores são carregados automaticamente ao acessar a tela.

5. Funções

5.1. Listagem de Funções

A tela exibe um grid de cartões, cada um representando uma função:

• Nome da função

• Descrição breve

• Quantidade de permissões (badge cinza)

• Botões de ação: Permissões, Editar, Copiar, Excluir

Use o campo de busca no topo para filtrar funções por nome ou descrição.

Estado vazio: Se não houver funções, a tela exibe "Nenhuma função encontrada" com um botão "Crie sua primeira função".

5.2. Criando uma Função

1

Inicie a criação

Clique no botão Criar Função.

2

Preencha os dados da função

Preencha o Nome da função, por exemplo: admin, operator, viewer.

Preencha a Descrição, por exemplo: "Administrador do sistema com acesso total".

3

Selecione as permissões

Na seção Permissões, marque as permissões desejadas.

• Use o campo de busca para filtrar permissões por nome ou descrição.

• O contador "X de Y selecionadas" mostra quantas permissões foram marcadas.

4

Crie a função

Clique em Criar.

5.3. Editando uma Função

1

Abra a edição

Na listagem, clique no botão de editar (ícone de lápis) na função desejada.

2

Atualize a função

O nome da função não pode ser alterado após a criação.

Altere a descrição conforme necessário.

Adicione ou remova permissões na seção de permissões.

3

Salve as alterações

Clique em Salvar.

Ao editar uma função, as alterações afetam todos os usuários que possuem essa função atribuída.

5.4. Copiando uma Função

1

Inicie a cópia

Na listagem, clique no botão de copiar (ícone de cópia) na função desejada.

2

Ajuste os dados

Um formulário de criação é aberto com a descrição e permissões da função original.

Defina um novo nome para a função.

Ajuste descrição e permissões conforme necessário.

3

Crie a cópia

Clique em Criar.

5.5. Excluindo uma Função

1

Inicie a exclusão

Na listagem, clique no botão de excluir (ícone de lixeira, vermelho) na função desejada.

2

Confirme a exclusão

Uma janela de confirmação será exibida com o nome da função.

Clique em Excluir para confirmar, ou Cancelar para cancelar.

6. Usuários

6.1. Listagem de Usuários

A tela exibe um grid de cartões, cada um representando um usuário:

• Nome do usuário

• E-mail

• Quantidade de funções atribuídas (badge cinza)

• Botões de ação: Funções, Editar, Excluir

Use o campo de busca no topo para filtrar usuários por nome ou e-mail.

A listagem é paginada (20 itens por página). Use os botões de navegação no rodapé para trocar de página.

Estado vazio: Se não houver usuários, a tela exibe "Nenhum usuário encontrado" com um botão "Crie seu primeiro usuário".

6.2. Criando um Usuário

1

Inicie a criação

Clique no botão Criar Usuário.

2

Preencha os dados do usuário

Preencha o Nome, por exemplo: "João Silva".

Preencha o E-mail, por exemplo: "[e-mail]".

3

Adicione identificadores externos, se necessário

Opcionalmente, adicione Identificadores Externos:

• Clique em Adicionar Identificador.

• Selecione a Claim Key no dropdown, por exemplo: cpf, titulo.

• Preencha o Claim Value, por exemplo: "12345678900".

• Repita para adicionar mais identificadores.

4

Crie o usuário

Clique em Criar.

6.3. Editando um Usuário

1

Abra a edição

Na listagem, clique no botão de editar (ícone de lápis) no usuário desejado.

2

Atualize os dados

Altere nome e/ou e-mail conforme necessário.

3

Gerencie os identificadores externos

Na seção Identificadores Externos:

• Para adicionar: clique em "Adicionar Identificador", preencha claim key e value.

• Para remover: clique no ícone de lixeira ao lado do identificador. Ele ficará com texto tachado e opacidade reduzida.

• Para desfazer remoção: clique em "Desfazer" no identificador marcado para remoção.

4

Salve as alterações

Clique em Salvar.

6.4. Atribuindo Funções a um Usuário

1

Abra a atribuição de funções

Na listagem de usuários, clique no botão Funções (ícone de escudo) no usuário desejado.

2

Selecione as funções

A tela exibe o cartão do usuário — nome, e-mail e avatar com iniciais — e a lista de funções disponíveis.

Marque ou desmarque as funções desejadas usando as caixas de seleção.

• Use o campo de busca para filtrar funções por nome ou descrição.

• O contador "X / total" mostra quantas funções estão selecionadas.

3

Salve as alterações

Clique em Salvar Alterações — o botão mostra a quantidade de alterações.

O botão só fica habilitado se houver alterações em relação ao estado original.

6.5. Excluindo um Usuário

1

Inicie a exclusão

Na listagem, clique no botão de excluir (ícone de lixeira, vermelho) no usuário desejado.

2

Confirme a exclusão

Uma janela de confirmação será exibida com o nome do usuário.

Clique em Excluir para confirmar, ou Cancelar para cancelar.

7. Auditoria

A tela de auditoria exibe o histórico completo de todas as alterações realizadas no sistema.

7.1. Como Usar

1

Acesse a tela de auditoria

Ao acessar a tela, você verá a mensagem "Clique em Buscar para carregar os logs".

2

Carregue os logs

Clique no botão Buscar para carregar os logs.

3

Aplique filtros, se necessário

Opcionalmente, aplique filtros antes de buscar.

7.2. Filtros Disponíveis

Clique em Filtros para expandir o painel de filtros. Um badge mostra a quantidade de filtros ativos.

Filtro	Descrição	Exemplo
Event Type	Tipo de evento	CREATED, UPDATED, DELETED, ASSIGNED, REMOVED, REVOKED
Entity Type	Tipo de entidade	USER, ROLE, USER_ROLE, ROLE_PERMISSION, EXTERNAL_IDENTIFIER
Entity ID	ID da entidade afetada	UUID ou nome
Actor UUID	UUID de quem realizou a ação	UUID do usuário
Date From	Início do período	Seletor de data
Date To	Fim do período	Seletor de data

Clique em Aplicar para buscar com os filtros. Clique em Limpar para limpar todos os filtros.

7.3. Informações Exibidas

Cada entrada de auditoria mostra:

Coluna	Descrição
Data	Data e hora da ação
Evento	Badge colorido com o tipo de evento
Entidade	Tipo de entidade afetada
ID da Entidade	Identificador da entidade (fonte monospace)
UUID do Ator	Quem realizou a ação (ou "System" para ações automáticas)

7.4. Cores dos Eventos

Evento	Cor
CREATED	Verde
UPDATED	Azul
DELETED	Vermelho
ASSIGNED	Azul primário
REMOVED	Âmbar
REVOKED	Vermelho

7.5. Detalhes Expandíveis

Ver detalhes de uma entrada de auditoria

Clique na seta à esquerda de uma entrada para expandir e ver detalhes adicionais em formato chave-valor, como nomes antigos/novos e permissões afetadas.

7.6. Paginação

Use os botões de navegação no rodapé para trocar de página. O total de resultados e a faixa atual são exibidos.

8. Idioma

O GBS Auth está disponível em Português (Brasil) e Inglês.

1

Abra o menu do usuário

Clique no seu nome/avatar no canto superior direito.

2

Selecione o idioma

No dropdown, na seção Idioma, selecione o idioma desejado.

3

Confirme a atualização

O idioma atual é marcado com um ícone de check.

A interface é atualizada imediatamente — não é necessário recarregar a página.

9. Mensagens Comuns

9.1. Mensagens de Sucesso

Mensagem	Contexto
Role created successfully	Função criada com sucesso
Role updated successfully	Função atualizada com sucesso
Role deleted successfully	Função excluída com sucesso
User created successfully	Usuário criado com sucesso
User updated successfully	Usuário atualizado com sucesso
User deleted successfully	Usuário excluído com sucesso
User roles updated successfully	Funções do usuário atualizadas

9.2. Mensagens de Erro

Mensagem	Significado	O Que Fazer
Failed to load roles	Não foi possível carregar a lista de funções	Verifique a conexão e tente atualizar a página
Failed to load users	Não foi possível carregar a lista de usuários	Verifique a conexão e tente atualizar a página
Failed to delete role	A exclusão da função falhou	Tente novamente. Se persistir, contate o suporte
Failed to delete user	A exclusão do usuário falhou	Tente novamente. Se persistir, contate o suporte
Role not found	A função não existe mais	Atualize a lista de funções
User not found	O usuário não existe mais	Atualize a lista de usuários
Already exists (409)	Tentativa de criar item duplicado	Use um nome/identificador diferente
Already assigned (409)	Função ou permissão já atribuída	O item já está atribuído — nenhuma ação necessária
Session expired	Sua sessão expirou	Faça login novamente
Role name is required	Campo nome da função vazio	Preencha o nome da função
Description is required	Campo descrição vazio	Preencha a descrição
Name is required	Campo nome do usuário vazio	Preencha o nome do usuário
Email is required	Campo e-mail vazio	Preencha o e-mail
All identifier fields are required	Campos de identificador externo incompletos	Preencha todos os campos do identificador

9.3. Estados Vazios

Mensagem	Contexto
No roles found	Nenhuma função cadastrada ou nenhum resultado para o filtro
No users found	Nenhum usuário cadastrado ou nenhum resultado para o filtro
No audit logs found	Nenhum log de auditoria para os filtros aplicados
Click Search to load audit logs	Tela de auditoria antes da primeira busca
No permissions found	Nenhuma permissão corresponde ao filtro
No roles found matching your query	Nenhuma função corresponde ao filtro na tela de atribuição