Easy Cognito Nginx Gateway Auth

What it is

This project provides a shell-based installation framework to configure an nginx reverse proxy and oauth2-proxy instance. It acts as a centralized authentication layer for web applications, handling OAuth2/OIDC flows with AWS Cognito. Applications behind the gateway receive authenticated user details via HTTP headers (e.g., X-User-Email), enabling zero-code integration of Single Sign-On (SSO).

Features

• Zero-code authentication integration for existing web apps
• Centralized Single Sign-On (SSO) via AWS Cognito
• Secure OAuth2 Authorization Code Flow with PKCE
• Passes user identity to apps via standard HTTP headers
• Modular nginx configuration for multi-app support
• Automated installation and systemd service management

Quickstart

git clone https://github.com/davidbmar/easy-cognito-nginx-gateway-auth.git
cd easy-cognito-nginx-gateway-auth
sudo ./scripts/install.sh --domain=your-domain.com --cognito-region=us-east-1 --cognito-pool-id=us-east-1_XXXXXXXXX --cognito-client-id=YOUR_CLIENT_ID --cognito-client-secret=YOUR_CLIENT_SECRET --app-port=3000

Architecture

flowchart TD
    User[User Browser] -->|HTTPS Request| Nginx[Nginx Reverse Proxy]
    Nginx -->|Auth Check| OAuth2[oauth2-proxy]
    OAuth2 -->|OIDC Flow| Cognito[AWS Cognito]
    Cognito -->|Token Validation| OAuth2
    OAuth2 -->|Set Cookie/Headers| Nginx
    Nginx -->|Proxy Request + Headers| App[Web Application]
    App -->|Response| Nginx
    Nginx -->|Response| User

How it's built

The solution is built using Bash scripts for automation and configuration management. It installs and configures three core components: nginx (as the entry point and reverse proxy), oauth2-proxy (as the OIDC client handler), and AWS Cognito (as the identity provider). Configuration is managed via template files populated by command-line arguments or environment variables, and services are managed via systemd.

How it runs

sequenceDiagram
    participant User as User Browser
    participant Nginx as Nginx Gateway
    participant Proxy as oauth2-proxy
    participant Cognito as AWS Cognito
    participant App as Web App

    User->>Nginx: GET /protected-resource
    Nginx->>Proxy: auth_request /oauth2/auth
    alt Not Authenticated
        Proxy->>User: 302 Redirect to Cognito Login
        User->>Cognito: Authenticate
        Cognito->>User: Redirect with Code
        User->>Proxy: Callback with Code
        Proxy->>Cognito: Exchange Code for Token
        Cognito->>Proxy: ID/Access Tokens
        Proxy->>User: Set Secure Cookie & Redirect
    else Authenticated
        Proxy->>Nginx: 200 OK + User Headers
    end
    Nginx->>App: Proxy Request + X-User-Email Header
    App->>Nginx: Application Response
    Nginx->>User: Final Content

How to apply & reuse

Deploy this on an Ubuntu/Debian server where your web applications are hosted. Use the provided install.sh script to configure the gateway with your AWS Cognito credentials and application ports. For infrastructure-as-code workflows, use the bootstrap.sh script within EC2 user_data templates to automate setup during instance initialization.

At a glance