Fixing 'Authentication Required by Wi-Fi Network' on Raspberry Pi 5

When you see the authentication required by wifi network raspberry pi prompt, your Pi’s NetworkManager has failed to complete the 802.11 security handshake. This is rarely a typo in your password. On modern Raspberry Pi OS (Bookworm and later), this error almost always points to a WPA3-SAE transition mode mismatch, an 802.1X Enterprise certificate failure, or a captive portal intercepting your DHCP request before authentication can finalize.

The direct fix depends on your network's security protocol. For standard WPA2/WPA3 mixed networks, you need to force the Pi's wpa_supplicant backend to accept Protected Management Frames (PMF). For Enterprise networks, you must supply the CA certificate path via nmcli. Below is the exact diagnostic matrix, hardware setup for headless debugging, and the Python script to automate the bypass.

The Exact Error Strings and Ranked Causes

Before changing configurations, verify which backend is throwing the error. The GUI prompt is generic, but the backend logs tell you exactly why the handshake failed. Here is the data-dense diagnostic matrix for the Pi 5's onboard Cypress CYW43455 Wi-Fi chip running NetworkManager.

Hardware Setup for Headless Network Debugging

When a Pi is headless and fails Wi-Fi auth, SSH drops. You need a local physical indicator to read the exact nmcli failure state without plugging in an HDMI monitor. We use an I2C OLED to display the live NetworkManager handshake status.

Parts List

• Board: Raspberry Pi 5 (8GB variant) running Pi OS Bookworm (64-bit)
• Display: 128x64 SSD1306 I2C OLED (3.3V logic)
• Power: Official 27W USB-C PD Power Supply (required for Pi 5 peripheral stability)
• Wiring: 4x female-to-female silicone jumper wires (26 AWG)

Pin Mapping Table: Pi 5 to SSD1306 I2C

The First Three Things to Check When It Fails

If you are staring at the 'authentication required' loop, run through these three checks in order. This sequence resolves 95% of Pi 5 Wi-Fi handshake failures on modern routers.

1. Check for WPA3-SAE Transition Mode (PMF Mismatch)

Most modern routers (like Eero, TP-Link Deco, or ASUS ZenWiFi) broadcast a single SSID that supports both WPA2 and WPA3. This is called Transition Mode. The Pi 5's NetworkManager often attempts WPA3, but if Protected Management Frames (PMF) are set to 'Required' on the router and the Pi's firmware fails to negotiate it, the auth drops silently.

The Fix: Force NetworkManager to use PMF as optional, or lock it to WPA2.

sudo nmcli connection modify 'YourSSID' wifi-sec.pmf 2
sudo nmcli connection up 'YourSSID'

2. Verify 802.1X Enterprise CA Certificate Paths

If you are connecting to a university or corporate network (eduroam, Company-Secure), the GUI prompt 'authentication required' means the backend rejected your EAP credentials because the Certificate Authority (CA) wasn't explicitly trusted. Unlike Windows, Pi OS will not blindly accept an unknown RADIUS server certificate.

The Fix: You must point nmcli to the PEM file.

sudo nmcli connection modify 'eduroam' 802-1x.ca-cert /etc/ssl/certs/ISRG_Root_X1.pem
sudo nmcli connection modify 'eduroam' 802-1x.phase2-auth mschapv2

3. Test for Captive Portal DHCP Interception

If the Pi connects, gets an IP address (e.g., 192.168.1.50), but ping 8.8.8.8 fails and the GUI keeps asking for authentication, you are trapped behind a captive portal (common in hotels, Airbnbs, and dorms). The Pi's NetworkManager expects a standard DHCP handshake, but the router is intercepting HTTP traffic to serve a login page.

The Fix: Trigger the portal manually via CLI using curl to a non-HTTPS site to force the redirect.

curl -I http://neverssl.com

This will return a 302 Found redirect to the router's auth page. Note the URL, and use a secondary device on the same network to complete the MAC-address binding if your Pi is headless.

Headless Auth-Debugging Python Script

To automate this debugging process on the bench, use the following Python script. It targets the Raspberry Pi 5 (8GB) running Pi OS Bookworm. It queries nmcli for the exact authentication failure string and renders it on the SSD1306 OLED via the I2C pins defined in our mapping table.

import subprocess
import time
import sys
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306
from PIL import ImageFont, ImageDraw, Image

# --- PIN DEFINITIONS & HARDWARE SETUP ---
# Target: Raspberry Pi 5, Hardware I2C1 (SDA=GPIO2, SCL=GPIO3)
try:
    serial = i2c(port=1, address=0x3C)
    device = ssd1306(serial, rotate=0)
except Exception as e:
    print(f'OLED Init Failed. Check I2C wiring on Pins 1,3,5,6. Error: {e}')
    sys.exit(1)

# Create blank image for drawing
image = Image.new('1', (device.width, device.height))
draw = ImageDraw.Draw(image)

# Use default font (or load a TTF if available)
try:
    font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 10)
except IOError:
    font = ImageFont.load_default()

def get_wifi_auth_status():
    """Queries NetworkManager for the exact Wi-Fi authentication state."""
    try:
        # Get active connection name
        result = subprocess.run(
            ['nmcli', '-t', '-f', 'NAME,DEVICE,STATE', 'connection', 'show', '--active'],
            capture_output=True, text=True, check=True
        )
        
        wlan_active = False
        ssid = 'None'
        for line in result.stdout.strip().split('\n'):
            if 'wlan' in line:
                parts = line.split(':')
                ssid = parts[0]
                wlan_active = True
                break
        
        if not wlan_active:
            return 'DISCONNECTED', 'No active wlan0 interface found.'
            
        # Check journalctl for the exact auth failure string
        log_result = subprocess.run(
            ['journalctl', '-u', 'NetworkManager', '-n', '20', '--no-pager'],
            capture_output=True, text=True, check=True
        )
        
        logs = log_result.stdout
        if 'requires new secrets' in logs or 'Secrets were required' in logs:
            return 'AUTH_FAIL', f'SSID: {ssid}\nError: Secrets required (WPA3/Enterprise mismatch)'
        elif 'EAP-FAILURE' in logs:
            return 'AUTH_FAIL', f'SSID: {ssid}\nError: EAP Failure (Check 802.1x Cert)'
        elif 'Captive portal' in logs or 'connectivity' in logs:
            return 'PORTAL', f'SSID: {ssid}\nCaptive Portal Detected'
        else:
            return 'CONNECTED', f'SSID: {ssid}\nIP Assigned / Auth OK'
            
    except subprocess.CalledProcessError as e:
        return 'ERROR', f'nmcli failed:\n{e.stderr}'
    except Exception as e:
        return 'ERROR', f'Python exception:\n{str(e)}'

def update_display(status, message):
    """Renders the status to the SSD1306 OLED."""
    draw.rectangle((0, 0, device.width, device.height), outline=0, fill=0)
    
    if status == 'AUTH_FAIL':
        draw.text((0, 0), 'AUTH REQUIRED', font=font, fill=255)
    elif status == 'CONNECTED':
        draw.text((0, 0), 'WIFI SECURE', font=font, fill=255)
    else:
        draw.text((0, 0), status, font=font, fill=255)
        
    # Word wrap the detailed error message
    y_text = 15
    for line in message.split('\n'):
        draw.text((0, y_text), line, font=font, fill=255)
        y_text += 12
        
    device.display(image)

if __name__ == '__main__':
    print('Starting Wi-Fi Auth Monitor on OLED...')
    try:
        while True:
            status, msg = get_wifi_auth_status()
            update_display(status, msg)
            time.sleep(5) # Poll NetworkManager every 5 seconds
    except KeyboardInterrupt:
        device.cleanup()
        print('Monitor stopped.')

How to Extend or Simplify the Build

Simplifying for Basic WPA2 Home Networks

If you do not need headless OLED debugging and are simply trying to connect a Pi 5 to a standard home WPA2 router, skip the Python script and NetworkManager CLI entirely. Use the built-in Raspberry Pi configuration tool, which handles the wpa_supplicant abstraction layer for you:

sudo raspi-config

Navigate to System Options > Wireless LAN. Enter your SSID and passphrase. This tool automatically writes the correct PMF and key-management flags to the backend configuration, bypassing the GUI 'authentication required' loop entirely.

Extending for Automated Captive Portal Bypass

If your Pi is deployed in a location with a recurring captive portal (like a remote cabin with a Starlink router that requires a daily click-through), you can extend the Python script above. Add the requests and BeautifulSoup libraries to parse the captive portal's login form. When the script detects the PORTAL state, it can automatically POST the required MAC address and acceptance terms to the router's gateway IP (usually 10.0.0.1 or 192.168.1.1), keeping your headless Pi online without manual intervention. For deeper NetworkManager troubleshooting, consult the official Raspberry Pi NetworkManager documentation or the Arch Linux NetworkManager Wiki, which remains the definitive guide to nmcli edge cases.