Troubleshooting Tip: General captive portal explanation, flow and troubleshooting

[ggolubovic]

Description

This article describes the general captive portal flow inside captive portals as well as its troubleshooting.

Set up of a captive portal can be done in various ways as described in other articles and documents, for example:
Technical Tip: Setting up a captive portal for network authentication using SAML and Azure for LAN u... 

Technical Tip: How to create FortiGate captive portal using policy 

FortiGate Administration guide: Captive portals 

Scope

FortiGate (and attached products).

Solution

To troubleshoot a captive portal issue, it is best to understand how the end user device that should get its traffic 'captured',  sees its internet access. Generally, browsers and operating systems come with means to detect whether it is behind a captive portal. Typically an unencrypted HTTP GET is sent to a certain website. If the response is unexpected, the device assumes it is behind a captive portal and it may then give a message to log in prior to using the network, similar to this:

captive portal example

The general FortiGate captive portal flow is similar to:

1. DNS for some external FQDN, ideally HTTP unencrypted captive portal detection site (to get the IP for the external resource)
   Each OS/Browser has some built-in unencrypted web pages it uses for testing. captive.apple.com, detectportal.firefox.com, msftconnecttest.com, connectivitycheck.gstatic.com to name some well-known examples.
   
   
2. TCP handshake and HTTP connect (HTTP GET) to that IP.
   
   
3. FortiGate blocks the HTTP request and redirects with HTTP response 302 or 303, or in later versions with HTTP 200. The response contains the redirect URL to FortiGate itself (FQDN:1000 for HTTP, FQDN:1003 for HTTPS).
   
   Note: For HTTPS, 'config firewall auth-portal' is required to be set with a resolvable FQDN for the FortiGate.
   Note that this requirement doesn't change when an external captive portal is used. This still must reflect the FortiGate FQDN. It must not reflect the external captive portal, like FortiAuthenticator.
   At this step, the browser or operating system detects it is behind a captive portal and a message similar to the example above may be displayed.
   
   
4. Optional for HTTPS: DNS for the redirect URL (=FortiGate).
   
   
5. TCP handshake and HTTP/HTTPS connect to that IP (=FortiGate). Display of the portal.
   
   

Adding an external captive portal (like FortiAuthenticator):

6. Redirect with HTTP 200/HTTP 302 or 303 to a FortiGate external resource (FortiAuthenticator, Azure, other portals).
   
   
7. Optional: DNS query for the captive portal FQDN, that is the redirect URL configured on the FortiGate interface as an external link. With FortiAuthenticator, for example, it would be the FortiAuthenticator-FQDN that is contained in the (https://) FortiAuthenticator-FQDN/portal/ URL.
   
   
8. TCP handshake and HTTP/HTTPS (inside TLS) connect to that IP (with redirect link included HTTP parameters, like (https://) portal.forti.lab/captive?login&post=(https://) fgt.fortilab.net:1003/fgtauth&magic=[...]&usermac=de:ad:be:ef:ca:fe&apmac=00:11:22:33:44:55&apip=102.189.68.135&apmac ...).
   
   
9. Typically a portal policy evaluation against the redirect parameters (like a comparison to one of them, like usermac=de:ad:be:ef:ca:fe).
   
   
10. Display of the portal to the user via HTTP/HTTPS.
    
    
11. Disclaimer or User Authentication. If both Disclaimer and authentication are used, another HTTP redirect will be done to get from the disclaimer page to the authentication page.
    
    
12. Redirect by FortiAuthenticator with HTTP 302 back to FortiGate given the HTTP parameters, FortiGate can recognize the client that it sent to FortiAuthenticator in step 6).
    
    
13. FortiGate sends a RADIUS Access-Request with User-Name attribute (value taken from HTTP redirect in 12) and a random password that FortiAuthenticator accepts with an Access-Accept, including other AVP/VSA that may have to be returned.
    
    
14. FortiGate lists the user in the firewall user list (diag firewall auth list or via GUI dashboard).

The following steps are for social login with FortiAuthenticator and are replacing step 11):

• Selection of the social network provider (Facebook, X, etc...).
• DNS for the social network FQDN (can be multiple, like CDNs or other sites).
• TCP handshake and HTTP/HTTPS (inside TLS) connect to that social network provider.
• User authentication to that provider. The provider must have an 'application' that contains configuration pointing to FortiAuthenticator and allowed URLs that the FortiAuthenticator has been spoken to (step 9).
• The FortiAuthenticator must contain the application 'key'. The redirect link to the social provider contains the exchanges of that info.
• Redirect from the social provider to FortiAuthenticator with HTTP 302, parameters in the URL, and a cookie.
• FortiAuthenticator now knows a 'social user', listed in the Social Login Users.

Troubleshooting of captive portals is best done with a packet capture that shows the end user's DNS queries and HTTP traffic. Steps 1-4 as well as any DNS follow up typically is visible in clear text.

If the firewall policy on FortiGate towards the external captive portal doesn't require NAT, the packet capture against the client IP address is good enough as a capturing filter.

The browser development tools (press F12) in conjunction with the packet capture via WireShark may also add details as they show the HTTPS traffic as well as the HTTP responses. These are methods to read the DNS queries (for the captive portal detection pages, FortiGate, and attached external portal FQDNs) and the TCP/HTTP/TLS traffic to the respective nodes one by one.

See also the typical captive portal workflow for an end-user with a FortiGate/FortiWiFi.