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:

1

Access GBS Auth

Access the GBS Auth URL in the browser.

2

Log in

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

Enter your credentials (username and password).

3

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.

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

1

Start creation

Click the button Create Role.

2

Fill in the role data

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

Fill in the Descriptiondescription, for example: "System administrator with full access".

3

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.

4

Create the role

Click Create.

5.3. Editing a Role

1

Open the edit

In the list, click the edit (pencil icon) on the desired role.

2

Update the role

The role name cannot be changed after creation.

Change the description as needed.

Add or remove permissions in the permissions section.

3

Save the changes

Click Save.

When editing a role, the changes affect all users who have that role assigned.

5.4. Copying a Role

1

Start copying

In the list, click the copy (copy icon) on the desired role.

2

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.

3

Create the copy

Click Create.

5.5. Deleting a Role

1

Start deletion

In the list, click the delete (trash icon, red) on the desired role.

2

Confirm deletion

A confirmation window will be displayed with the role name.

Click Delete to confirm, or Cancel to cancel.

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

1

Start creation

Click the button Create User.

2

Fill in the user data

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

Fill in the Email, for example: "[e-mail]".

3

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.

4

Create the user

Click Create.

6.3. Editing a User

1

Open the edit

In the list, click the edit (pencil icon) on the desired user.

2

Update the data

Change name and/or email as needed.

3

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.

4

Save the changes

Click Save.

6.4. Assigning Roles to a User

1

Open role assignment

In the user list, click the button Roles (shield icon) on the desired user.

2

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.

3

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.

6.5. Deleting a User

1

Start deletion

In the list, click the delete (trash icon, red) on the desired user.

2

Confirm deletion

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

Click Delete to confirm, or Cancel to cancel.

7. Audit

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

7.1. How to Use

1

Access the audit screen

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

2

Load the logs

Click the button Search to load the logs.

3

Apply filters, if necessary

Optionally, apply filters before searching.

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

View details of an audit entry

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.

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.

1

Open the user menu

Click your name/avatar in the top right corner.

2

Select the language

In the dropdown, in the Languagesection, select the desired language.

3

Confirm the update

The current language is marked with a check icon.

The interface updates immediately — there is no need to reload the page.

9. Common Messages

9.1. Success Messages

Message	Context
Role created successfully	Role created successfully
Role updated successfully	Role updated successfully
Role deleted successfully	Role deleted successfully
User created successfully	User created successfully
User updated successfully	User updated successfully
User deleted successfully	User deleted successfully
User roles updated successfully	User roles updated successfully

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