Skip to main content

​
Overview

Macondo Link Manager uses Google OAuth 2.0 for secure authentication, ensuring that only authorized users from specific domains can access the platform. Authentication is cookie-based using JWT tokens, providing a seamless and secure experience.

Google OAuth

Single sign-on with Google accounts

Domain Restriction

Only approved email domains allowed

JWT Tokens

Secure cookie-based sessions

7-Day Sessions

Long-lived authentication cookies

​
How Authentication Works

The authentication flow follows OAuth 2.0 standards with additional domain verification:
1

User initiates login

Navigate to the login page and click “Sign in with Google”
2

Google OAuth flow

You’re redirected to Google’s authentication page to authorize the application
3

Domain verification

After successful Google authentication, the system verifies your email domain against the allowed list
4

Account creation or login

If your domain is approved, the system either creates a new account or logs you into your existing account
5

JWT token issued

A secure JWT token is generated and stored in an HTTP-only cookie
6

Redirect to dashboard

You’re redirected to the application dashboard, ready to manage links

​
Domain Restriction

Macondo Link Manager restricts access to specific email domains to ensure only authorized organization members can use the platform.

​
Allowed Domains

By default, the following domains are permitted:
  • macondopropaganda.com
  • macondo.com.uy
If you attempt to log in with an email from a non-approved domain, you’ll see an error message and be redirected back to the login page with a DOMAIN_NOT_ALLOWED error.

​
Domain Validation Process

The system extracts the domain from your Google email address and checks it against the allowed domains list. This happens after Google authentication but before account creation. 
// Example domain extraction
email: "[email protected]"
  ↓
domain: "macondopropaganda.com"
  ↓
validation: ✓ ALLOWED
Authentication tokens are stored as secure HTTP-only cookies, providing protection against XSS attacks while maintaining user sessions.
PropertyValueDescription
Namemacondo.tokenCookie identifier
Max Age7 daysToken expiration time
HTTP OnlytruePrevents JavaScript access
SecuretrueRequires HTTPS connection
SameSitenoneAllows cross-site requests
Path/Valid for entire application

​
Token Contents

The JWT payload includes essential user information: 
{
  "sub": "user-uuid",
  "name": "User Full Name",
  "email": "[email protected]",
  "avatarUrl": "https://...",
  "exp": 1234567890
}
The sub (subject) field contains the user’s unique identifier and is used throughout the application to associate resources with users.

​
Login Flow

​
Starting Authentication

To begin the authentication process, users navigate to: 
GET /auth/google
This endpoint initiates the OAuth 2.0 authorization code flow with Google.

​
OAuth Scopes

The application requests the following Google OAuth scopes:
  • email - Access to user’s email address
  • profile - Access to basic profile information (name, picture)

​
Callback Handling

After Google authentication, users are redirected to: 
GET /auth/google/callback
This endpoint:
  1. Exchanges the authorization code for an access token
  2. Fetches user information from Google’s API
  3. Validates the email domain
  4. Creates or retrieves the user account
  5. Generates a JWT token
  6. Sets the authentication cookie
  7. Redirects to the frontend application

​
Logout

Users can log out by sending a POST request to the logout endpoint: 
POST /auth/logout

​
Logout Process

1

Clear authentication cookie

The server removes the macondo.token cookie from the user’s browser
2

Session termination

The user’s session is immediately terminated
3

Confirmation response

The server returns a success message confirming logout

​
Response Example

{
  "code": "LOGOUT_SUCCESS",
  "message": "Logout realizado com sucesso."
}

​
Security Features

HTTP-Only Cookies

Prevents XSS attacks by making tokens inaccessible to JavaScript

Secure Flag

Requires HTTPS, preventing token transmission over insecure connections

Domain Whitelist

Restricts access to approved organizational domains only

Token Expiration

7-day token lifetime ensures regular re-authentication

​
Error Handling

​
Domain Not Allowed

When a user from a non-approved domain attempts to log in: 
Redirect to: {FRONTEND_URL}/?error=DOMAIN_NOT_ALLOWED
The frontend displays an appropriate error message.

​
Authentication Failures

For unexpected errors during authentication:
  • The error is logged on the server with full details
  • The user receives a generic error message
  • No sensitive information is exposed to the client
All authentication events are logged, including successful logins, failed domain validations, and logout actions. This provides an audit trail for security monitoring.

​
Protected Routes

Once authenticated, the JWT token is automatically included in requests via the cookie. Protected API endpoints verify the token using the authHook middleware.

​
Automatic Token Verification

All routes marked with onRequest: [authHook] require valid authentication:
  • /links/* - Link management
  • /clients/* - Client management
  • /campaigns/* - Campaign management
  • /dashboard/* - Analytics and dashboards
If a token is expired or invalid, the server returns a 401 Unauthorized response, prompting the user to log in again.

Build docs developers (and LLMs) love

Get started for freeTalk to us