Module Federation with Proxy Authentication

This project demonstrates a secure Module Federation setup with Authentik authentication and Nginx proxy. It creates a system where the Host application can access Remote components, but direct access to the Remote application is restricted.

Architecture

• Host Application: Main application consuming remote components
• Remote Application: Exposes components via Module Federation
• Nginx: Reverse proxy controlling access and handling authentication
• Authentik: Identity provider for authentication

Features

• Secure Module Federation with proxy authentication
• Restricted direct access to Remote components
• Custom styled error pages for unauthorized access attempts
• User authentication with Authentik
• User info sharing between applications
• Logout functionality

Prerequisites

• Docker and Docker Compose
• Basic understanding of React, Module Federation, and authentication
• Sudo access (for setting up local hostnames)

Quick Start Guide

1. Clone the Repository

git clone https://github.com/yourusername/mf-proxy-auth.git
cd mf-proxy-auth

2. Configure Local Hostnames

Run the setup script to add necessary hostnames to your /etc/hosts file:

sudo ./setup-hosts.sh

This adds:

127.0.0.1 authentik.local
127.0.0.1 api.local
127.0.0.1 host.local
127.0.0.1 remote.local

3. Start the Environment

docker compose up -d

Wait for all services to start (approximately 1-2 minutes).

4. Configure Authentik

a. Create the Admin Account

1. Visit http://authentik.local/
2. Create your admin account with a secure password
3. Complete the account setup process

b. Configure the Proxy Provider

1. Navigate to Admin Interface > Providers > Create
2. Select Proxy Provider
3. Fill in the form:
   • Name: Nginx Proxy
   • Authentication flow: default-authentication-flow
   • Authorization flow: default-provider-authorization-explicit-consent
   • External host: http://authentik.local
   • Internal host: http://authentik-server:9000
   • Under Advanced Protocol Settings:
     • Skip path regex: ^/$|^/api/|^/static/|^/.well-known/|^/outpost.goauthentik.io/
4. Click Save

c. Create an Outpost

1. Go to Admin Interface > Outposts > Create
2. Fill in:
   • Name: Nginx Outpost
   • Type: Proxy
   • Providers: Select the Nginx Proxy provider
3. Click Save

d. Configure Applications

1. Go to Admin Interface > Applications > Create
2. Create the Host app:
   • Name: Host Application
   • Slug: host-app
   • Provider: Select Nginx Proxy
3. Click Save
4. Repeat to create a Remote app with:
   • Name: Remote Application
   • Slug: remote-app
   • Provider: Select Nginx Proxy

e. Configure Custom Headers

1. Go to Admin Interface > Providers > Edit your Proxy Provider
2. Add these headers:
   • X-authentik-username: user.username
   • X-authentik-email: user.email
   • X-authentik-name: user.name
   • X-authentik-groups: user.groups
3. Click Save

f. Deploy the Outpost

1. Go to Admin Interface > Outposts
2. Select your Nginx Outpost
3. Click Deploy > Embedded Outpost

5. Access the Applications

• Host application: http://host.local/
• Remote application: http://remote.local/ (will return 403 - only accessible through Host)
• Authentik portal: http://authentik.local/
• API endpoint: http://api.local/user-info

How It Works

Authentication Flow

1. When you visit http://host.local/, Nginx forwards the request to Authentik
2. Authentik authenticates you (redirecting to login if needed)
3. After authentication, Authentik passes user information back to Nginx
4. Nginx adds user info as headers and proxies to the Host application
5. The Host application reads user information and displays it
6. The Host application loads components from the Remote application
7. The Remote application checks the referer header to ensure requests come from the Host

Module Federation

• The Host application (host.local) loads a RemoteComponent from the Remote application
• The Remote application exposes components through Module Federation
• Authentication credentials and user info are passed between applications
• Direct access to Remote components is forbidden with custom error pages

Security Features

• Authentik provides authentication and user management
• Nginx enforces access controls based on request origin
• Custom error pages guide users who try to access Remote directly
• Logout button for ending user sessions

Troubleshooting

Authentication Issues

• Check Authentik logs: docker compose logs -f authentik-server
• Verify Provider configuration in Authentik
• Make sure the Outpost is properly deployed and connected

Access Issues

• Verify hosts file entries: cat /etc/hosts
• Check Nginx logs: docker compose logs -f nginx
• Ensure all containers are running: docker compose ps

Module Federation Issues

• Check the browser console for errors with loading remote components
• Verify the Remote application is properly exposing components
• Check CORS headers and Nginx configuration
• Make sure the referer header is being properly passed

Common Solutions

• Restart services: docker compose restart nginx
• Restart all containers: docker compose down && docker compose up -d
• Clear browser cache and cookies

Advanced Customization

Custom Error Pages

Custom error pages are located in /nginx/error_pages/. You can modify these files to change the appearance and messaging of error pages.

Adding More Remote Components

To expose additional components from the Remote application:

1. Add new components to /remote/src/components/
2. Update /remote/rspack.config.js to expose the components
3. Import them in the Host application

Authentication Configuration

To modify authentication behavior:

1. Update the Nginx configuration in /nginx/default.conf
2. Adjust the Authentik Provider settings in the admin interface

Security Considerations

• This setup prevents direct access to Remote components
• All requests to Remote are authenticated and verified
• User information is securely passed between applications
• Logout functionality is provided to end user sessions
• Custom error pages don't leak sensitive information

Technical Details

Key Files

• /nginx/default.conf - Nginx configuration with authentication and routing
• /host/src/App.js - Host application with Remote component imports
• /remote/src/components/RemoteComponent.js - Component exposed by Remote
• /docker-compose.yml - Service definitions and networking

Module Federation Configuration

• Host (Consumer): /host/rspack.config.js
• Remote (Provider): /remote/rspack.config.js