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.

Setup 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 before using the network, similar to this:

captive portal example

The following is a general captive portal redirection and that may apply to other solutions as well. Note that a 'redirect' in this context, if not explicitly stated means:

• Start with an HTTP response that contains a URL.
• The FQDN on the URL will have to be resolved (if the URL is not an IP).
• The client will attempt a regular TCP handshake.
• May have to do a TLS handshake to encrypt (that requires a proper certificate setup for each of the involved nodes).
• HTTP GET to the URL indicated in the previous HTTP response.

The captive portal flow on FortiGate follows this schema:

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. For example, captive.apple.com, detectportal.firefox.com, msftconnecttest.com, connectivitycheck.gstatic.com, to name some well-known detection resources.
   
   
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 redirected URL to FortiGate itself (FQDN:1000 for HTTP, FQDN:1003 for HTTPS). The URL/FQDN must point to the interface IP of this FortiGate, facing this client's captive portal network. Typically, that IP is the gateway IP for the client.
   
   Note: For HTTPS to FortiGate, 'config firewall auth-portal' is required to be set with a resolvable FQDN for the FortiGate. It must resolve to the FortiGate interface IP, the default gateway for the client's subnet.
   Note that this requirement does not 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 HTTPS: DNS for the redirect URLs FQDN (resolves to the FortiGate's client-facing interface).
   
   
5. TCP handshake and HTTP/HTTPS connect to that IP (i.e. FortiGate's IP of the client-facing interface). 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), configured on the FortiGate interface as the 'External' address on the setting 'Authentication Portal'.
   
   
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 against the parameters, like usermac=de:ad:be:ef:ca:fe, apip, etc.).
   
   
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. The disclaimer agreement directs the URL of that redirect.
    
    
12. Redirect by FortiAuthenticator with HTTP 302 back to FortiGate.
    This redirect requires the URL to include the session ID ('magic'), the username, and the password given in the HTTP parameters. The FQDN must be the FortiGate again, the URL/FQDN was handed over as an HTTP parameter in step 8.
    FortiGate can recognize the client that it sent to FortiAuthenticator in step 6). The client has to use these to create an HTTP POST to the FortiGate URL.
    
    
13. With the HTTP POST to FortiGate from the client, FortiGate will attempt a regular authentication:
    FortiGate sends a RADIUS Access-Request with User-Name attribute (value taken from HTTP redirect in 12) and the password that FortiAuthenticator accepts with an Access-Accept, including other AVP/VSA (like Fortinet-Group-Name) that may have to be returned.
    Note that if the external portal is not a FortiAuthenticator but relies on a different method and the user database is on the FortiGate in 'config user local'.
    
    
14. FortiGate lists the user in the firewall user list (diag firewall auth list or via GUI dashboard). If a value of the VSA Fortinet-Group-Name was handed over in the Access-Accept, matching a FortiGate local user group (config user group) referencing that RADIUS server (config match), the output will reflect that group name.

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

• Selection of the social network provider (Facebook, X, etc...), which results in another HTTP redirect.
• 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. The FortiGate must allow these with a policy with the 'captive-portal-exempt' option enabled. ISDB as a destination object may be the best choice. If the providers change IPs or even FQDNs, this breaks the connection to the provider. Bad website display or no connection at all would be a result. See article 262159 for an ISDB example on the captive portal.
• 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:
The steps above must be followed and in case of issues with the captive portal, on the steps, there is a diversion from the description. 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 typically are visible in clear text.

If the firewall policy on FortiGate towards the external captive portal does not require NAT: the packet capture against the client IP address is sufficient as a capturing filter.

The browser development tools (usually these can be opened with the keyboard press of 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.

During the troubleshooting of HTTP, strict transport security (HSTS) captive portal errors might also be experienced. Check the article on
How to troubleshoot HSTS error for captive portal for more information.

Related articles:
Technical Tip: The typical captive portal workflow for an end-user with a FortiGate/FortiWiFi

Technical Tip: Fortinet's RADIUS Dictionary and VSAs (latest)