> For the complete documentation index, see [llms.txt](https://docs.griaule.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.griaule.com/aplicacoes/gbs-auth.md).

# 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 é:

{% stepper %}
{% step %}

#### Acesse o GBS Auth

Acesse a URL do GBS Auth no navegador.
{% endstep %}

{% step %}

#### Faça login

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

Insira suas credenciais (usuário e senha).
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### Inicie a criação

Clique no botão **Criar Função**.
{% endstep %}

{% step %}

#### 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".
{% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

#### Crie a função

Clique em **Criar**.
{% endstep %}
{% endstepper %}

### 5.3. Editando uma Função

{% stepper %}
{% step %}

#### Abra a edição

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

{% step %}

#### 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.
{% endstep %}

{% step %}

#### Salve as alterações

Clique em **Salvar**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Ao editar uma função, as alterações afetam todos os usuários que possuem essa função atribuída.
{% endhint %}

### 5.4. Copiando uma Função

{% stepper %}
{% step %}

#### Inicie a cópia

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

{% step %}

#### 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.
{% endstep %}

{% step %}

#### Crie a cópia

Clique em **Criar**.
{% endstep %}
{% endstepper %}

### 5.5. Excluindo uma Função

{% stepper %}
{% step %}

#### Inicie a exclusão

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

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

## 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

{% stepper %}
{% step %}

#### Inicie a criação

Clique no botão **Criar Usuário**.
{% endstep %}

{% step %}

#### Preencha os dados do usuário

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

Preencha o **E-mail**, por exemplo: "<joao@exemplo.com>".
{% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

#### Crie o usuário

Clique em **Criar**.
{% endstep %}
{% endstepper %}

### 6.3. Editando um Usuário

{% stepper %}
{% step %}

#### Abra a edição

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

{% step %}

#### Atualize os dados

Altere nome e/ou e-mail conforme necessário.
{% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

## Salve as alterações

Clique em **Salvar**.
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

### 6.5. Excluindo um Usuário

{% stepper %}
{% step %}

#### Inicie a exclusão

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

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

## 7. Auditoria

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

### 7.1. Como Usar

{% stepper %}
{% step %}

#### Acesse a tela de auditoria

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

{% step %}

#### Carregue os logs

Clique no botão **Buscar** para carregar os logs.
{% endstep %}

{% step %}

#### Aplique filtros, se necessário

Opcionalmente, aplique filtros antes de buscar.
{% endstep %}
{% endstepper %}

### 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

<details>

<summary>Ver detalhes de uma entrada de auditoria</summary>

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.

</details>

### 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**.

{% stepper %}
{% step %}

#### Abra o menu do usuário

Clique no seu nome/avatar no canto superior direito.
{% endstep %}

{% step %}

#### Selecione o idioma

No dropdown, na seção **Idioma**, selecione o idioma desejado.
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

## 9. Mensagens Comuns

### 9.1. Mensagens de Sucesso

<table data-search="false"><thead><tr><th>Mensagem</th><th>Contexto</th></tr></thead><tbody><tr><td>Role created successfully</td><td>Função criada com sucesso</td></tr><tr><td>Role updated successfully</td><td>Função atualizada com sucesso</td></tr><tr><td>Role deleted successfully</td><td>Função excluída com sucesso</td></tr><tr><td>User created successfully</td><td>Usuário criado com sucesso</td></tr><tr><td>User updated successfully</td><td>Usuário atualizado com sucesso</td></tr><tr><td>User deleted successfully</td><td>Usuário excluído com sucesso</td></tr><tr><td>User roles updated successfully</td><td>Funções do usuário atualizadas</td></tr></tbody></table>

### 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  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.griaule.com/aplicacoes/gbs-auth.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.