> 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/gbs/en/applications/gbs-auth.md).

# GBS Auth

## 1. Overview

The **GBS Auth** is an OIDC (OpenID Connect)-based authentication and authorization management web application. The tool acts as an authentication broker for external identity providers (e.g.: Google Workspace, Gov.br), issues its own access tokens, and provides an administrative panel for managing users, roles, permissions, and auditing.

This guide covers the **use of the GBS Auth application** — the role, user, and audit management screens. It can help you with:

* Understanding what each screen displays and what actions are available
* Creating and managing roles and permissions
* Creating and managing users and external identifiers
* Assigning roles to users
* Consulting the audit history

## 2. Login

GBS Auth uses authentication via OpenID Connect integrated with the Identity Provider (IdP). The login flow is:

{% stepper %}
{% step %}

#### Access GBS Auth

Access the GBS Auth URL in the browser.
{% endstep %}

{% step %}

#### Log in

You will be redirected to the login screen of the configured identity provider.

Enter your credentials (username and password).
{% endstep %}

{% step %}

#### Return to GBS Auth

After authentication, you will be redirected back to GBS Auth.

Your initials and name appear in the top right corner of the screen.
{% endstep %}
{% endstepper %}

To log out, click your name in the top right corner and select **Sign out**.

### 2.1. If login fails

| What You See                                    | What It Means                            | What to Do                                                                    |
| ----------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------- |
| IdP login screen does not load                  | The IdP is unreachable                   | Check your network connection and try again. If it persists, contact support. |
| Invalid credentials                             | Incorrect username or password           | Check your credentials. Use "Forgot password" if available in the IdP.        |
| "Completing sign in..." keeps loading           | OAuth callback failed                    | Click "Try again". If it persists, clear the browser cookies and cache.       |
| Error message with yellow triangle icon         | Token exchange failure or state mismatch | Click "Try again". If it persists, clear sessionStorage and try again.        |
| Empty screens or missing menu items after login | You do not have any assigned permissions | Contact the administrator to check your roles and permissions.                |

## 3. Navigation

The left sidebar contains the main navigation menu. The available items depend on your permissions:

| Menu Item     | Icon          | Required Permission    | Description     |
| ------------- | ------------- | ---------------------- | --------------- |
| **Dashboard** | Layout (grid) | None                   | System overview |
| **Roles**     | Shield        | `auth:roles:write`     | Role management |
| **Users**     | People        | None                   | User management |
| **Audit**     | Document      | `auth:audit-logs:read` | Audit history   |

The menu can be collapsed by clicking the collapse button at the bottom of the sidebar, showing only the icons to gain more workspace. When collapsed, the name of each item appears as a *tooltip* on hover.

## 4. Dashboard

The home screen displays three cards with counters:

| Card                  | Information                     | Action                |
| --------------------- | ------------------------------- | --------------------- |
| **Total Roles**       | Number of defined roles         | Link "View all roles" |
| **Total Permissions** | Number of available permissions | Link "View Roles"     |
| **Users**             | Number of registered users      | Link "Manage Users"   |

The counters are loaded automatically when accessing the screen.

## 5. Roles

### 5.1. Role Listing

The screen displays a grid of cards, each representing a role:

* **Name** of the role
* **Description** brief
* **Number of permissions** (gray badge)
* **Action buttons**: Permissions, Edit, Copy, Delete

Use the search field at the top to filter roles by name or description.

**Empty state:** If there are no roles, the screen shows "No role found" with a "Create your first role" button.

### 5.2. Creating a Role

{% stepper %}
{% step %}

#### Start creation

Click the button **Create Role**.
{% endstep %}

{% step %}

#### Fill in the role data

Fill in the **Name** role name, for example: `admin`, `operator`, `viewer`.

Fill in the **Description**description, for example: "System administrator with full access".
{% endstep %}

{% step %}

#### Select the permissions

In the **Permissions**, check the desired permissions.

* Use the search field to filter permissions by name or description.
* The counter "X of Y selected" shows how many permissions have been checked.
  {% endstep %}

{% step %}

#### Create the role

Click **Create**.
{% endstep %}
{% endstepper %}

### 5.3. Editing a Role

{% stepper %}
{% step %}

#### Open the edit

In the list, click the **edit** (pencil icon) on the desired role.
{% endstep %}

{% step %}

#### Update the role

The role name **cannot be changed** after creation.

Change the description as needed.

Add or remove permissions in the permissions section.
{% endstep %}

{% step %}

#### Save the changes

Click **Save**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
When editing a role, the changes affect all users who have that role assigned.
{% endhint %}

### 5.4. Copying a Role

{% stepper %}
{% step %}

#### Start copying

In the list, click the **copy** (copy icon) on the desired role.
{% endstep %}

{% step %}

#### Adjust the data

A creation form opens with the description and permissions of the original role.

Define a **new name** for the role.

Adjust description and permissions as needed.
{% endstep %}

{% step %}

#### Create the copy

Click **Create**.
{% endstep %}
{% endstepper %}

### 5.5. Deleting a Role

{% stepper %}
{% step %}

#### Start deletion

In the list, click the **delete** (trash icon, red) on the desired role.
{% endstep %}

{% step %}

#### Confirm deletion

A confirmation window will be displayed with the role name.

Click **Delete** to confirm, or **Cancel** to cancel.
{% endstep %}
{% endstepper %}

## 6. Users

### 6.1. User Listing

The screen displays a grid of cards, each representing a user:

* **Name** of the user
* **Email**
* **Number of roles** assigned (gray badge)
* **Action buttons**: Roles, Edit, Delete

Use the search field at the top to filter users by name or email.

The list is paginated (20 items per page). Use the navigation buttons in the footer to change pages.

**Empty state:** If there are no users, the screen shows "No user found" with a "Create your first user" button.

### 6.2. Creating a User

{% stepper %}
{% step %}

#### Start creation

Click the button **Create User**.
{% endstep %}

{% step %}

#### Fill in the user data

Fill in the **Name**, for example: "John Silva".

Fill in the **Email**, for example: "[john@example.com](mailto:joao@exemplo.com)".
{% endstep %}

{% step %}

#### Add external identifiers, if necessary

Optionally, add **External Identifiers**:

* Click **Add Identifier**.
* Select the **Claim Key** in the dropdown, for example: `cpf`, `title`.
* Fill in the **Claim Value**, for example: "12345678900".
* Repeat to add more identifiers.
  {% endstep %}

{% step %}

#### Create the user

Click **Create**.
{% endstep %}
{% endstepper %}

### 6.3. Editing a User

{% stepper %}
{% step %}

#### Open the edit

In the list, click the **edit** (pencil icon) on the desired user.
{% endstep %}

{% step %}

#### Update the data

Change name and/or email as needed.
{% endstep %}

{% step %}

#### Manage the external identifiers

In the **External Identifiers**:

* To **add**: click "Add Identifier", fill in claim key and value.
* To **remove**: click the trash icon next to the identifier. It will appear with strikethrough text and reduced opacity.
* To **undo removal**: click "Undo" on the identifier marked for removal.
  {% endstep %}

{% step %}

## Save the changes

Click **Save**.
{% endstep %}
{% endstepper %}

### 6.4. Assigning Roles to a User

{% stepper %}
{% step %}

#### Open role assignment

In the user list, click the button **Roles** (shield icon) on the desired user.
{% endstep %}

{% step %}

#### Select the roles

The screen displays the user card — name, email and avatar with initials — and the list of available roles.

Check or uncheck the desired roles using the checkboxes.

* Use the search field to filter roles by name or description.
* The counter "X / total" shows how many roles are selected.
  {% endstep %}

{% step %}

#### Save the changes

Click **Save Changes** — the button shows the number of changes.

The button is only enabled if there are changes compared to the original state.
{% endstep %}
{% endstepper %}

### 6.5. Deleting a User

{% stepper %}
{% step %}

#### Start deletion

In the list, click the **delete** (trash icon, red) on the desired user.
{% endstep %}

{% step %}

#### Confirm deletion

A confirmation window will be displayed with the user's name.

Click **Delete** to confirm, or **Cancel** to cancel.
{% endstep %}
{% endstepper %}

## 7. Audit

The audit screen displays the complete history of all changes made in the system.

### 7.1. How to Use

{% stepper %}
{% step %}

#### Access the audit screen

When you access the screen, you will see the message "Click Search to load the logs".
{% endstep %}

{% step %}

#### Load the logs

Click the button **Search** to load the logs.
{% endstep %}

{% step %}

#### Apply filters, if necessary

Optionally, apply filters before searching.
{% endstep %}
{% endstepper %}

### 7.2. Available Filters

Click **Filters** to expand the filter panel. A *badge* shows the number of active filters.

| Filter          | Description                                 | Example                                                        |
| --------------- | ------------------------------------------- | -------------------------------------------------------------- |
| **Event Type**  | Event Type                                  | CREATED, UPDATED, DELETED, ASSIGNED, REMOVED, REVOKED          |
| **Entity Type** | Entity Type                                 | USER, ROLE, USER\_ROLE, ROLE\_PERMISSION, EXTERNAL\_IDENTIFIER |
| **Entity ID**   | ID of the affected entity                   | UUID or name                                                   |
| **Actor UUID**  | UUID of the person who performed the action | User UUID                                                      |
| **Date From**   | Start of period                             | Date picker                                                    |
| **Date To**     | End of period                               | Date picker                                                    |

Click **Apply** to search with the filters. Click **Clear** to clear all filters.

### 7.3. Displayed Information

Each audit entry shows:

| Column         | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| **Date**       | Date and time of the action                                  |
| **Event**      | Color badge with the event type                              |
| **Entity**     | Type of affected entity                                      |
| **Entity ID**  | Identifier of the entity (monospace font)                    |
| **Actor UUID** | Who performed the action (or "System" for automatic actions) |

### 7.4. Event Colors

| Event    | Color        |
| -------- | ------------ |
| CREATED  | Green        |
| UPDATED  | Blue         |
| DELETED  | Red          |
| ASSIGNED | Primary blue |
| REMOVED  | Amber        |
| REVOKED  | Red          |

### 7.5. Expandable Details

<details>

<summary>View details of an audit entry</summary>

Click the arrow to the left of an entry to expand and view additional key-value details, such as old/new names and affected permissions.

</details>

### 7.6. Pagination

Use the navigation buttons in the footer to change pages. The total number of results and the current range are displayed.

## 8. Language

GBS Auth is available in **Portuguese (Brazil)** and **English**.

{% stepper %}
{% step %}

#### Open the user menu

Click your name/avatar in the top right corner.
{% endstep %}

{% step %}

#### Select the language

In the dropdown, in the **Language**section, select the desired language.
{% endstep %}

{% step %}

#### Confirm the update

The current language is marked with a check icon.

The interface updates immediately — there is no need to reload the page.
{% endstep %}
{% endstepper %}

## 9. Common Messages

### 9.1. Success Messages

<table data-search="false"><thead><tr><th>Message</th><th>Context</th></tr></thead><tbody><tr><td>Role created successfully</td><td>Role created successfully</td></tr><tr><td>Role updated successfully</td><td>Role updated successfully</td></tr><tr><td>Role deleted successfully</td><td>Role deleted successfully</td></tr><tr><td>User created successfully</td><td>User created successfully</td></tr><tr><td>User updated successfully</td><td>User updated successfully</td></tr><tr><td>User deleted successfully</td><td>User deleted successfully</td></tr><tr><td>User roles updated successfully</td><td>User roles updated successfully</td></tr></tbody></table>

### 9.2. Error Messages

| Message                            | Meaning                                   | What to Do                                       |
| ---------------------------------- | ----------------------------------------- | ------------------------------------------------ |
| Failed to load roles               | Could not load the role list              | Check the connection and try refreshing the page |
| Failed to load users               | Could not load the user list              | Check the connection and try refreshing the page |
| Failed to delete role              | Role deletion failed                      | Try again. If it persists, contact support       |
| Failed to delete user              | User deletion failed                      | Try again. If it persists, contact support       |
| Role not found                     | The role no longer exists                 | Refresh the role list                            |
| User not found                     | The user no longer exists                 | Refresh the user list                            |
| Already exists (409)               | Attempt to create a duplicate item        | Use a different name/identifier                  |
| Already assigned (409)             | Role or permission already assigned       | The item is already assigned — no action needed  |
| Session expired                    | Your session has expired                  | Log in again                                     |
| Role name is required              | Role name field is empty                  | Fill in the role name                            |
| Description is required            | Description field is empty                | Fill in the description                          |
| Name is required                   | User name field is empty                  | Fill in the user name                            |
| Email is required                  | Email field is empty                      | Fill in the email                                |
| All identifier fields are required | External identifier fields are incomplete | Fill in all identifier fields                    |

### 9.3. Empty States

| Message                            | Context                                             |
| ---------------------------------- | --------------------------------------------------- |
| No roles found                     | No roles registered or no results for the filter    |
| No users found                     | No users registered or no results for the filter    |
| No audit logs found                | No audit logs for the applied filters               |
| Click Search to load audit logs    | Audit screen before the first search                |
| No permissions found               | No permission matches the filter                    |
| No roles found matching your query | No role matches the filter on the assignment screen |


---

# 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/gbs/en/applications/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.