Authentication

Geoportal supports both individual and enterprise authentication with a security-first, production-ready design.

Security Model at a Glance

All authentication traffic is encrypted in transit (HTTPS/TLS).
Authentication trust is established by our backend API, not the frontend.
Geoportal uses secure, server-managed sessions for browser access.
Protected API routes validate authentication and authorization on every request.
Authentication failures use standardized responses (401 / 403) and avoid leaking sensitive details.

Account Types

We support two account models:

Type	Description
Personal	Individual account created with email + password.
Enterprise	Organization-managed account using Microsoft Entra ID SSO.

Authentication Methods

Authentication Method	Personal Accounts	Enterprise Accounts
Email + Password	✅	❌
Microsoft Entra ID (SSO)	✅ (optional)	✅

Authentication Workflows

1) Personal Account (Email + Password)

User submits email + password on the login page over HTTPS.
API validates credentials and account status.
On success, API creates a session and sets a secure cookie (HttpOnly, Secure, SameSite).
Browser sends the session cookie on subsequent API requests.
Protected routes validate the session for each request.
If authentication is missing, expired, or invalid, API responds with 401 Unauthorized.
If authentication is valid but access is not permitted, API responds with 403 Forbidden.

sequenceDiagram
    actor User
    participant Browser as Geoportal Web (Browser)
    participant API as Geoportal API
    User->>Browser: Enter email + password
    Browser->>API: POST /auth/login (HTTPS)
    API->>API: Validate credentials + account status
    API-->>Browser: 200 OK + Set-Cookie (HttpOnly, Secure, SameSite)
    Browser->>API: Request protected resource (with session cookie)
    API->>API: Validate session + authorization
    API-->>Browser: 200 OK

2) Enterprise Account (Microsoft Entra ID SSO)

User starts sign-in from Geoportal.
User is redirected to Microsoft Entra ID using OpenID Connect Authorization Code Flow with PKCE.
Microsoft Entra ID authenticates the user using the organization’s identity policies.
User returns to Geoportal backend callback endpoint.
Backend validates identity response and establishes Geoportal session.
Browser receives secure session cookie and uses it for authenticated API access.
Protected routes validate session and organization-level permissions for each request.

sequenceDiagram
    actor User
    participant Browser as Geoportal Web (Browser)
    participant API as Geoportal API
    participant Entra as Microsoft Entra ID
    User->>Browser: Click "Sign in with Microsoft"
    Browser->>API: Start SSO flow
    API-->>Browser: Redirect to Entra (OIDC Auth Code + PKCE)
    Browser->>Entra: Authenticate with enterprise identity
    Entra-->>Browser: Redirect back with authorization code
    Browser->>API: Send callback code
    API->>API: Validate identity response + establish session
    API-->>Browser: Set-Cookie (HttpOnly, Secure, SameSite)
    Browser->>API: Request protected resource (with session cookie)
    API->>API: Validate session + org authorization
    API-->>Browser: 200 OK

3) Authentication error handling flow

sequenceDiagram
    participant Browser as Geoportal Web (Browser)
    participant API as Geoportal API
    Browser->>API: Request protected resource (missing/expired/invalid auth)
    API-->>Browser: 401 Unauthorized
    Browser->>Browser: Clear local auth state and redirect to login
    Browser->>API: Request protected resource (valid auth, insufficient permission)
    API-->>Browser: 403 Forbidden
    Browser->>Browser: Show "Access denied" UI

Credential Expiration and Invalid Credentials

Expired Credentials

API returns 401 Unauthorized.
Client should prompt the user to sign in again.
Session renewal and timeout behavior are handled by the authentication system.

Invalid or Tampered Credentials

API returns 401 Unauthorized.
Responses are intentionally generic to reduce account and token probing risk.
Invalid attempts are logged and monitored for abuse detection.

Authenticated but Not Allowed

API returns 403 Forbidden.
This means identity is valid, but the user does not have permission for the requested action.

Design Principles

Least privilege: users only receive access required for their role.
Defense in depth: authentication, session controls, and route-level authorization are all enforced.
Separation of concerns: frontend handles UX; backend is the trust boundary.
Safe public documentation: this page explains behavior and guarantees without exposing sensitive internals.