Troubleshooting

This guide helps you diagnose and resolve common issues with IronWifi. Each section includes symptoms, causes, and step-by-step solutions.

Authentication Issues

Access Rejected

Symptoms: User cannot connect and receives a rejection message or error.

Common causes and solutions:

Cause	How to fix
Invalid credentials	Go to Users in the IronWifi Console and verify the username and password are correct
User disabled	Open the user's profile and confirm Status is set to "Enabled"
Time restrictions	Check the Login Time attribute in the user's profile to ensure the current time falls within allowed hours
Expired account	Review the Valid From and Valid To dates in the user's profile
Wrong authentication source	Verify the user's Authentication Source matches where their credentials are stored (local, Azure AD, Google Workspace, etc.)

Certificate Authentication Failure

Symptoms: EAP-TLS authentication fails with certificate-related errors.

Common causes and solutions:

Cause	How to fix
Certificate expired	Check the certificate's validity dates and issue a new certificate if expired
Certificate revoked	In the IronWifi Console, go to Certificates and verify the certificate is not in the revoked list
CA certificate not trusted	Install the IronWifi CA certificate on the client device (download from Certificates > CA Certificate)
Wrong certificate selected	On the client device, open WiFi settings and select the correct user certificate for this network

MAC Authentication Not Working

Symptoms: Device should authenticate automatically based on its MAC address but fails to connect.

Common causes and solutions:

Cause	How to fix
MAC not in authorized list	Go to Users, open the user's profile, and add the device MAC address under Authorized Devices
MAC format mismatch	Use lowercase letters with colons as separators (e.g., aa:bb:cc:dd:ee:ff). Check that your controller sends MACs in this format
Feature not enabled	In your Captive Portal settings, enable MAC-based authentication
Authorization expired	Check if the MAC authorization has a time limit and re-authorize the device if needed

Captive Portal Issues

Splash Page Not Loading

Symptoms: Users see a white page, timeout error, or "page cannot be displayed" when connecting to WiFi.

Common causes and solutions:

Cause	How to fix
Walled garden misconfigured	Add IronWifi's IP address 107.178.250.42/32 and domain *.ironwifi.com to your controller's walled garden or pre-auth access list
Wrong redirect URL	Copy the Splash Page URL from your IronWifi captive portal settings and paste it exactly into your controller's external portal URL field
DNS issues	Ensure your controller allows DNS traffic (port 53) before authentication. Add DNS servers to the pre-auth access list
HTTPS certificate problems	If using a custom domain, verify your SSL certificate is valid and properly installed

Social Login Not Working

Symptoms: Users click a social login button (Google, Facebook, LinkedIn) but authentication fails or the login window doesn't appear.

Common causes and solutions:

Cause	How to fix
Missing walled garden entries	Add the required domains to your controller's walled garden. For Google: *.google.com, *.gstatic.com, *.googleapis.com. For Facebook: *.facebook.com, *.fbcdn.net
OAuth app misconfigured	In IronWifi Console under Captive Portals > Authentication Providers, verify your OAuth Client ID and Secret are correct
Popup blocked	The user's browser may be blocking the login popup. They should allow popups for the splash page domain
Third-party cookies blocked	Social login requires third-party cookies. Users should enable cookies or try a different browser

Users Stuck on Splash Page

Symptoms: Users complete authentication (see a success message) but cannot access the internet and may be redirected back to the splash page.

Common causes and solutions:

Cause	How to fix
Controller not receiving auth response	For UniFi and similar controllers, verify the controller credentials in IronWifi are correct and the controller is reachable from the internet (check firewall rules for port 8443)
Session not created	Go to Reports > Sessions in IronWifi Console to check if a session was created. If not, review the authentication logs for errors
Client isolation enabled	If client isolation is enabled on your access points, it may block communication. Disable it or add exceptions for the captive portal
VLAN misconfiguration	Verify the post-auth VLAN assignment is correct and that the VLAN has internet access

Controller-Specific Issues

UniFi: Authorization Failed

Error: unifi_authentication_failed

This error means IronWifi cannot authenticate with your UniFi controller.

How to fix:

1. In UniFi, create a dedicated local admin user (not SSO) with full admin privileges
2. In IronWifi Console, go to Captive Portals and update the UniFi controller credentials with this new user
3. Test the connection by clicking Test Connection in the captive portal settings

Error: unifi_gw_connection_failed

This error means IronWifi cannot reach your UniFi controller over the network.

How to fix:

1. Confirm your controller's public IP address or hostname is correct in IronWifi
2. Ensure your firewall allows inbound connections on port 8443 from IronWifi's IP (107.178.250.42)
3. If your controller is behind NAT, set up port forwarding for port 8443 to your controller's internal IP
4. If direct connection isn't possible, enable the Proxy feature in your IronWifi captive portal settings

Meraki: RADIUS Timeout

Symptoms: Users experience long delays during authentication, or authentication times out completely.

How to fix:

1. In Meraki Dashboard, go to Wireless > Access control and verify the RADIUS server IP matches IronWifi's regional server (find this in your IronWifi network settings)
2. Confirm the RADIUS port is 1812 for authentication and 1813 for accounting
3. Double-check that the shared secret in Meraki exactly matches the one in IronWifi (secrets are case-sensitive)
4. Ensure your firewall allows outbound UDP traffic on ports 1812 and 1813 to the IronWifi RADIUS server
5. If using RADIUS accounting, verify it's enabled in both Meraki and IronWifi

MikroTik: Users Can't Authenticate

Symptoms: Users cannot authenticate through the MikroTik hotspot.

How to fix:

1. Verify your RADIUS configuration in the MikroTik terminal:

   /radius print

   Confirm the server address, secret, and ports match your IronWifi settings.

2. Check hotspot server settings:

   /ip hotspot print

   Ensure the hotspot is enabled and assigned to the correct interface.

3. Verify walled garden entries include IronWifi domains:

   /ip hotspot walled-garden print

   Add *.ironwifi.com and 107.178.250.42 if missing.

4. Test with a local MikroTik user first to confirm the hotspot itself works, then switch to RADIUS authentication.

Network Issues

Intermittent Connectivity

Symptoms: Users experience random disconnections or need to re-authenticate frequently.

Common causes and solutions:

Cause	How to fix
Session timeout too short	In IronWifi Console, go to Networks > Attributes and increase the Session-Timeout value (e.g., 28800 for 8 hours)
Idle timeout too aggressive	Increase the Idle-Timeout attribute to allow longer periods of inactivity before disconnection
Network instability	Check your local network for issues such as interference, overloaded access points, or bandwidth problems
Roaming between APs	Enable seamless roaming (802.11r/k/v) on your access points and ensure all APs use the same SSID and security settings

Slow Authentication

Symptoms: Authentication takes several seconds or longer than expected.

Common causes and solutions:

Cause	How to fix
RADIUS server latency	Use the IronWifi regional server closest to your location. Check your network settings for available regions
Controller to IronWifi latency	If your controller has high latency to IronWifi, enable the Proxy feature in your captive portal settings for a direct connection
DNS resolution delays	Configure reliable DNS servers (e.g., 8.8.8.8, 1.1.1.1) on your network and ensure DNS is allowed before authentication
Certificate chain issues	If using EAP-TLS, ensure your certificate chain is complete and doesn't require additional lookups during verification

Integration Issues

Connector Sync Failing

Symptoms: Users from Google Workspace or Azure AD are not appearing in IronWifi, or changes are not being synchronized.

How to fix:

1. Go to Connectors in IronWifi Console and click Re-authorize to refresh the connection
2. Verify the connector has the required API permissions in Google Admin Console or Azure Portal
3. Check the Sync Logs in IronWifi to identify specific errors
4. Ensure your network allows outbound HTTPS connections to Google and Microsoft APIs

Webhook Not Received

Symptoms: Your application is not receiving webhook notifications from IronWifi.

How to fix:

1. Go to Settings > Webhooks in IronWifi Console and verify the URL is correct and includes https://
2. Confirm your receiving server is running and accessible from the internet
3. Check your firewall allows inbound HTTPS connections from IronWifi's IP (107.178.250.42)
4. Verify your server's SSL certificate is valid and not expired

Diagnostic Tools

Use these tools to diagnose issues before contacting support.

Authentication Test

Test RADIUS authentication without involving your controller:

1. Go to ironwifi.com/authentication-test
2. Enter your IronWifi RADIUS server address and port
3. Enter the shared secret from your network settings
4. Enter test credentials (username and password)
5. Click Test and review the response

A successful test confirms your IronWifi configuration is correct. If this test passes but authentication fails from your controller, the issue is likely in your controller configuration.

Request Logs

View detailed authentication attempts in the IronWifi Console:

1. Navigate to Reports > Authentication
2. Use filters to find specific requests by date, username, MAC address, or result (Accept/Reject)
3. Click on any request to see the full RADIUS attributes sent and received
4. Look for error messages or missing attributes that explain the failure

Packet Capture

For advanced debugging when other methods don't reveal the issue:

1. On your controller or a network device, capture RADIUS traffic (UDP ports 1812, 1813)
2. Look for Access-Request packets going to IronWifi and Access-Accept or Access-Reject responses
3. Verify that required attributes (User-Name, Called-Station-Id, etc.) are present in requests
4. Compare the shared secret usage and attribute formats with IronWifi documentation

Getting Help

If you cannot resolve an issue using this guide:

1. Gather information before contacting support:

• Screenshots of error messages
• Request IDs from the authentication logs
• Your controller type and firmware version
• Steps to reproduce the issue
• Any recent changes made to your configuration

2. Contact support:

• Live chat: Available 24/7 via the chat widget on ironwifi.com
• Email: support@ironwifi.com

Include the gathered information in your request to help us resolve your issue quickly.

3. Check service status: Visit status.ironwifi.com to check for any ongoing service issues or maintenance.