Skip to main content

How to Integrate

GuardianKey Auth Bastion Enterprise is designed to offer fast, secure, and flexible integration with any Web system, without the need to change the original application's source code. Below, we present an overview of the integration possibilities for the solution.

⚠️ Important: each integration case is individually analyzed and supported by the GuardianKey Customer Success team, ensuring compatibility, security, and performance. For specific integrations, please contact our technical support.

📌 TOC (Table of Contents)​

🎯 Integration Objectives​

Integration with the bastion can occur with two distinct objectives:

1. 🛡️ Protect systems with two-factor authentication (2FA)​

The bastion intercepts the system's authentication route, requiring an additional verification (TOTP, email, SMS) before allowing access to the login form.

2. 🆔 Offer login via OAuth2/OIDC​

The bastion replaces or complements the system's original login, enabling federated authentication with GovBR directly through the bastion interface.

OAuth2/OIDC Integrator Module Specification

1️⃣ Integration for 2FA Protection​

Requirements​

  • The system to be protected must be a Web application.
  • The bastion must be able to receive connections directly from the end user (or via a proxy that preserves the original IP).
  • The protected system must be accessible by the bastion (internally or externally).
  • It is necessary to define:
    • Domain (FQDN) of the application.
    • Protected path (e.g.: /login, /auth).
    • Backend servers (for redirection after authentication).
    • 2FA authentication type: TOTP, email, or others.
    • User registration method: email, credentials, API, bastion.

General Flow​

User accesses system → Intercepted by bastion → 2FA validated → Redirected to login form → Login performed → Access granted

Possibilities​

  • 2FA validation occurs before the original login.
  • The bastion can use system endpoints to fetch the user's email or validate credentials (if necessary).
  • The authenticated session generates a token linked to the IP and with an expiration time (TTL).

📌 Tip: use User Pool to share 2FA users among multiple authgroups.

2️⃣ Integration with Login via GovBR (OAuth2/OIDC)​

Requirements​

  • The system must be Web and accessible by the bastion.
  • The protected system needs to have the same username that will be authenticated in the OAuth2/OIDC authenticator, to allow correct user matching; if the authenticator is Gov.br, the protected system must have the user's CPF in its database.

Integration Features​

  • All OAuth2 logic is managed within the bastion.
  • The "Login with GovBR" button is automatically injected into the login interface, with a customizable template.

After logging in to GovBR:​

  • The bastion associates the user by CPF (or username, according to the authenticator configuration).
  • The user is redirected to the originally requested URL, already authenticated.

Usage Modes:​

  • Exclusive: replaces the standard login.
  • Optional: the user chooses between GovBR login or traditional login.

⚠️ For additional protection, it is possible to enable integration with GuardianKey Auth Security (risk score), but it is not compatible with 2FA in this mode.

General Flow​

User accesses system → Chooses "Login with GovBR" → OAuth2 authentication → CPF returned → User authenticated → Redirected to application

🧩 Recommended Modeling​

The basic structure of an integration in the Bastion panel involves:

Organization
 └── Domain Name (e.g.: app.company.com)
            └── Authgroup (e.g.: HR System)
                     ├── Protected paths (e.g.: /login)
                     ├── Authentication method (Oauth2/GovBR)
                     ├── Oauth2 Integrations (authenticator keys and endpoints)
                     └── Backends (IP or host of the protected system)

It is also necessary to configure an integrator agent, which creates the authenticated session in the system to be protected.

🧠 Tips for Efficient Integration​

  • Clearly define which path will be protected (e.g.: /login).
  • Choose the authentication type most appropriate for your audience (e.g.: email for public portals, TOTP for internal systems).
  • Ensure that the bastion can communicate with the protected system (internal DNS, firewall, etc.).
  • Consider reusing user pools if more than one system shares the user base.
  • When using GovBR, ensure the system correctly identifies the user's CPF.

🤝 Integration Support​

GuardianKey offers full integration support, with technical assistance and specialized guidance through the Customer Success team. To ensure security and proper operation, we recommend that any new integration be validated with our team.

📩 Contact us at [email protected] or through your dedicated channel.