Installation Guides

Step-by-step firewall & gateway integration guides for Useroam Cloud Hotspot and 5651 logging.

Ruijie Integration Guide

This guide walks you through the complete integration between a Ruijie / Reyee gateway and Useroam Cloud — captive portal authentication (WiFiDog external portal) and legal 5651 syslog forwarding.

Before you start: you need administrator access to the Ruijie web interface, the gateway's active WAN IP address, and the hardware serial number printed on the device label.

1 - Adding the device to the Useroam panel

First, sign in to your panel at panel.useroam.com and add a New Device.

Adding a Ruijie device in the Useroam panel

2 - Allowlist settings for trusted IPs (Allowlist → Dest. IP)

In the Ruijie management interface, go to Object > User Authentication > Authentication Settings from the top menu. Under the Allowlist tab, select the Dest. IP option and allow the Useroam Cloud server IP address (104.247.174.120) together with your hotspot service networks.

Ruijie Allowlist Dest. IP settings

3 - Allowlist settings for trusted domains (Allowlist → URL)

Switch to the URL tab in the same menu. Add *.useroam.com to the allowlist — guests must be able to reach it before they authenticate. Also define URL rules for the messaging and operating-system captive-portal detection domains that mobile devices use to verify the hotspot network in the background (for example the WhatsApp networks).

Ruijie Allowlist URL settings

4 - External Portal & WiFiDog authentication template

From the left-hand menu, open Authentication Template and select the External Portal tab. Enable WiFiDog Authentication, then create the template:

Ruijie WiFiDog authentication template

5 - Authentication policy (Edit Authentication Policy)

As the final configuration step, go to Authentication Policy in the left menu and either add a new rule or edit your existing guest policy:

Ruijie authentication policy

6 - Forwarding logs to Useroam (Syslog config)

So that guest internet traffic and hotspot session activity can be legally signed under Turkish Law No. 5651, the logs must be forwarded to the Useroam Cloud server. In the Ruijie management interface go to Advanced > Syslog and use the Add button to define a new syslog server:

Ruijie syslog configuration

Important — integration complete

That's it. Useroam Cloud Hotspot and the legal 5651 syslog integration are now fully configured on your Ruijie / Reyee gateway. Remember to update the Useroam panel whenever the device serial number or WAN IP address changes, otherwise the integration will stop working. For assistance during the process, contact our technical team at destek@useroamteknoloji.com.

Login with WhatsApp — firewall allowlist (walled garden)

For the Login with WhatsApp flow to work while the guest is still behind the captive portal (before internet access is granted), the following addresses must be allowed in your firewall or walled-garden configuration. Without these rules the WhatsApp login screen will not open and the automatic login based on delivery confirmation will not work.

Domains to allow (FQDN)

IP addresses to allow

Note: 157.240.0.0 and 31.13.0.0 are typically /16 network blocks (Meta infrastructure); we recommend defining them as blocks in the firewall (157.240.0.0/16, 31.13.0.0/16). 104.247.174.120 is the Useroam panel IP (/32). Use the domain list if your firewall supports FQDN-based filtering; otherwise use the IP blocks.

Sophos API Connection

Useroam uses the Sophos Firewall API to create and remove hotspot user sessions automatically. This page shows how to create the API user and grant the API permission on the Sophos side.

When do I need this? Complete these steps after the Sophos Integration Guide, whenever Useroam has to manage users over the API.

Creating a new profile

In Sophos, go to Profile > Device Access in the left menu and create a new profile. Grant all permissions.

Creating a device access profile in Sophos

Creating the API user

In Sophos, go to Authentication > Users > New user in the left menu and create a new user. For User Profile, select the profile you created in the previous step.

Creating the API user in Sophos

Granting the API permission

In Sophos, open Backup & Firmware from the left menu, switch to the API tab, add the entry below to the API Configuration field and click +.

Sophos API configuration

Tip: the API user's credentials must match the ones entered on the device record in the Useroam panel. If you change the password later, update it in the panel as well.

Fortigate Integration Guide

This guide covers the full integration between a FortiGate firewall and Useroam Cloud: RADIUS authentication, the captive portal replacement messages, the firewall policies, and 5651 syslog forwarding.

Before you start: you need administrator access to the FortiGate web interface (and CLI access if a second syslog server is required), plus the WAN IP address of the firewall.

1 - Adding the device to the Useroam panel

Sign in to your panel at panel.useroam.com and add a New Device. The system selects your license automatically.

Note: if you want the traffic to leave over a different WAN interface, create an SNAT rule to route it through the interface you want.

Adding a Fortinet device in the Useroam panel

2 - Adding the RADIUS server

On your firewall, go to User & Authentication > RADIUS Servers and click Create New to define the Useroam Cloud server.

Test Connectivity: you can run a RADIUS test from your firewall against Useroam Cloud.

FortiGate RADIUS server settings
FortiGate RADIUS connectivity test

3 - Captive portal messages (Replacement Messages)

Three fields under System > Replacement Messages need their code replaced. Switch to Extended View from the top-right corner first.

3A - Login Failed Page

Search for Login Failed Page. On the screen that opens, clear the code area on the right, paste in {"Error":"passwordwrong", "ErrorType":"passwordwrong"} and save.

FortiGate Login Failed Page replacement message
FortiGate replacement message code area

3B - Authentication Success Page & Login Page

Search for Authentication Success Page. Clear the code area on the right, paste in {"Error":"success", "ErrorType":"success"} and save.

Finally, for Login Page, paste the entire code you copied from the Useroam Cloud panel (Settings > Device Settings).

FortiGate Login Page replacement message

4 - Creating the user group (User Groups)

Go to User & Authentication > User Groups and create a group for Useroam Cloud.

FortiGate user group

5 - Interface configuration

On the firewall, edit the relevant port from the Interface menu.

FortiGate interface configuration

Creating the firewall policies

To create the rules, go to Policy & Objects > Firewall Policy on the FortiGate firewall.

RULE 1: Guest to DNS

Create your DNS rule first. Selecting only the DNS service is enough.

FortiGate Guest to DNS policy

RULE 2: Guest to Useroam

This rule lets users in the zone where you enable Useroam reach the panel.useroam.com panel. Under Service, select the HTTP/HTTPS services.

FortiGate Guest to Useroam policy

RULE 3: Guest to Internet

This rule is your general internet access rule. Add the User Group (Open Group) object you created as the Source, and the ALL service under Service.

FortiGate Guest to Internet policy
Once all three rules are in place, the Policy & Objects > Firewall Policy list should be ordered as shown below.
FortiGate firewall policy order

Forwarding logs to the Useroam device

Under Log & Report > Log Settings, set Syslog logging to Enable. Then enter the server details in the IP Address/FQDN field as panel.useroam.com.

FortiGate syslog settings
Caution: if a different IP is already defined here, you must configure your second syslog server from the command line (CLI).
After checking whether syslogd2 already contains another configuration, you can use the example command block below:

config log syslogd2 setting
set status enable
set server "panel.useroam.com"
set port 514
set format default
end

Important — integration complete

That's it — your FortiGate integration is complete. If you run into any problems during the process, contact our support team at destek@useroamteknoloji.com.

Login with WhatsApp — firewall allowlist (walled garden)

For the Login with WhatsApp flow to work while the guest is still behind the captive portal (before internet access is granted), the following addresses must be allowed in your firewall or walled-garden configuration. Without these rules the WhatsApp login screen will not open and the automatic login based on delivery confirmation will not work.

Domains to allow (FQDN)

IP addresses to allow

Note: 157.240.0.0 and 31.13.0.0 are typically /16 network blocks (Meta infrastructure); we recommend defining them as blocks in the firewall (157.240.0.0/16, 31.13.0.0/16). 104.247.174.120 is the Useroam panel IP (/32). Use the domain list if your firewall supports FQDN-based filtering; otherwise use the IP blocks.

Sophos Integration Guide

This guide covers the full integration between a Sophos Firewall and Useroam Cloud: RADIUS authentication, web authentication, the captive portal template, the firewall rules, and 5651 syslog forwarding.

Before you start: you need administrator access to the Sophos web interface and the WAN IP address of the firewall. If Useroam will also manage users over the API, complete the Sophos API Connection page afterwards.

1 - Adding the device to the Useroam panel

Sign in to your panel at panel.useroam.com and add a New Device. The system selects your license automatically.

Note: if you want the traffic to leave over a different WAN interface, create an SNAT rule to route it through the interface you want.

Adding a Sophos device in the Useroam panel

2 - Device Access settings

Go to Administration > Device Access. For the zone where you will use Useroam, enable only the Captive Portal and DNS options.

Caution: if you enable other authentication mechanisms such as RADIUS SSO at the same time, you may run into redirection problems or a slow-loading captive portal page.
Sophos Device Access settings

3 - Adding the RADIUS server

Add a new RADIUS server from Authentication > Servers. In the Server IP field, enter the IP address you get when you ping panel.useroam.com.

Then copy the code shown next to Device Password under Useroam > Settings > Device Settings and paste it into the Shared Secret field.

Sophos RADIUS server settings
Device password in the Useroam panel

4 - Connection test (optional)

If you want to test at this point: create a new user in the Useroam Cloud panel via Guests > New User, then check the connection with Test Connection inside the RADIUS server settings on the firewall.

Sophos RADIUS connection test

5 - Authentication priority (Authentication Methods)

Go to Authentication > Services, move Useroam to the top of the Firewall Authentication Methods list, and click Apply to save.

Sophos firewall authentication methods

6 - Web authentication settings

Move on to Authentication > Web Authentication. Under Sign Out User, tick When User is Inactive.

In the Traffic flow section next to it, set 1440 minutes (24 hours) for 100 bytes. With this setting, every connected device stays signed in on the firewall as long as it transfers at least 100 bytes within 24 hours. You can shorten this period if you prefer.

Finally, tick "Use insecure HTTP instead of HTTPS" and save.

Sophos web authentication settings

7 - Integrating the captive portal design (Custom HTML)

In Useroam, go to Settings > Device Settings and copy the whole block that starts with the <html> line. Paste it into Authentication > Web Authentication > Captive portal appearance > Custom HTML on the Sophos firewall and save.

Useroam captive portal template
Sophos custom HTML field
Limiting concurrent sessions: if you want to limit how many devices can use a single account, configure this under Configure > Authentication > Services > Global Settings on the Sophos firewall. By default the system allows an unlimited number of devices.
Sophos global authentication settings

Creating the firewall rules

To create the rules, go to Protect > Rules and Policies on the Sophos firewall and open the Add Firewall Rule page.

RULE 1: Guest to DNS

Every device sends a DNS query to a vendor-specific domain to work out whether the network it joined has internet access (for example captive.apple.com).

When the answer comes back, the device concludes it has internet and starts passing traffic. Without it, the hotspot redirect will not happen.

This rule must sit above the guest internet access rule.

Sophos Guest to DNS rule

RULE 2: Guest to Useroam

This rule lets devices on your guest network reach *.useroam.com. Selecting HTTP/HTTPS under Services is enough.

Sophos Guest to Useroam rule

RULE 3: Guest to Internet

This rule provides internet access for your devices.

Tick the Log Firewall checkbox. So that unknown users are shown the hotspot screen, also tick Match Known Users and Use Web Authentication For Unknown Users. For Web Policy and Identify And Control Applications (App Control), select Allow All or any policy you prefer.

Sophos Guest to Internet rule
Sophos Guest to Internet rule details
When you are done, the Protect > Rules and Policies list should be ordered as shown below.
Sophos rule order

Forwarding logs to the Useroam device

1 - Defining the syslog server

First go to System Services > Log Settings and define a new syslog server.

Sophos log settings

2 - Entering the syslog details and starting

Fill in the following details for the newly added syslog server:

Sophos syslog server details

Then, on the row for the newly added syslog server, select only the Content Filtering fields to start sending logs to Useroam.

Sophos syslog content filtering selection

3 - Checking the log packets

Afterwards, go back to the Useroam panel to confirm that packets are arriving from the firewall. Check the General Statistics area in the top-right corner and look at the section under Pending Signature.

Pending signature statistics in the Useroam panel

Important — integration complete

Your Sophos integration is complete. If you run into any problems during the process, contact our support team at destek@useroamteknoloji.com.

Login with WhatsApp — firewall allowlist (walled garden)

For the Login with WhatsApp flow to work while the guest is still behind the captive portal (before internet access is granted), the following addresses must be allowed in your firewall or walled-garden configuration. Without these rules the WhatsApp login screen will not open and the automatic login based on delivery confirmation will not work.

Domains to allow (FQDN)

IP addresses to allow

Note: 157.240.0.0 and 31.13.0.0 are typically /16 network blocks (Meta infrastructure); we recommend defining them as blocks in the firewall (157.240.0.0/16, 31.13.0.0/16). 104.247.174.120 is the Useroam panel IP (/32). Use the domain list if your firewall supports FQDN-based filtering; otherwise use the IP blocks.

Palo Alto Integration Guide

This guide covers the full integration between a Palo Alto firewall and Useroam Cloud: zone and interface configuration, RADIUS authentication, certificates, the Authentication Portal, DNS, log forwarding, and the firewall rules.

Before you start: you need administrator access to the Palo Alto web interface, the external interface IP address the firewall will use to talk to Useroam, and your SSL certificate together with its key file and password.

1 - Adding the firewall to the panel

First sign in to your panel at panel.useroam.com and add a New Device. In the Device Address field, enter the external interface IP address the firewall will use to communicate.

Adding a Palo Alto device in the Useroam panel

2 - Zone settings

For the interface where Useroam will be enabled, create a new zone under Network > Zone and tick Enable User Identification.

Palo Alto zone settings

3 - Interface and profile settings

On the interface where Useroam will be enabled, create a new profile from the Advanced section. While doing so, tick the Response Pages checkbox.

Palo Alto interface management profile

4 - RADIUS settings

Apply the settings below under Device > Server Profiles > RADIUS:

Palo Alto RADIUS server profile

5 - Authentication Profile

Define the new profile under Device > Authentication Profile.

Palo Alto authentication profile

6 - Certificate configuration

Before the certificates are installed on the device, the relevant root certificates (Root CA or Intermediate) must already be added to the system. This completes the certificate trust chain and prevents SSL/TLS errors on the client devices that connect.

6A - Importing the Root CA

As the first step, import the Root CA or CA certificate.

Palo Alto Root CA import

6B - Uploading the certificate and key file

Next, upload the certificate file to the firewall together with the key file and its password.

Palo Alto certificate and key upload

6C - Verifying the layered certificate chain

Once the upload is complete, the view should show a layered structure — a certificate chain in which the entries are linked to one another.

Palo Alto certificate chain

7 - Authentication Portal settings

Next, open the Settings section under Device > User Identification > Authentication Portal.

Palo Alto Authentication Portal settings

If you need to create a new profile, follow these steps:

8 - Uploading the captive portal design (Comfort Page)

In panel.useroam.com, go to Settings > Device Settings and copy the entire code block that starts with <html>. Paste it into a text editor and save it in HTML format under a name such as captive.html. Then upload that document on the firewall via Device > Response Pages > Captive Portal Comfort Page.

Palo Alto Captive Portal Comfort Page

9 - DHCP settings

So that DNS queries from the internal network are handled without problems, the DHCP and DNS Proxy configuration must be updated if you do not have a separate DNS server. Go to Network > DHCP > Options.

Note: if you already have an internal DNS server, add the record required for the domain redirect to your internal DNS as well (in the Static Entries section) and continue from step 11.

Palo Alto DHCP options

10 - DNS Proxy settings

Next, define a new proxy under Network > DNS Proxy so DNS queries resolve correctly.

Palo Alto DNS Proxy settings

11 - Forwarding logs to Useroam (Log Forwarding)

Go to Objects > Log Forwarding and add a new profile with Add. A separate profile must be created for each of the five log types (auth, data, decryption, traffic, url). For every entry, remember to select the Useroam profile in the Syslog section.

Palo Alto log forwarding profile
Palo Alto log forwarding syslog selection

Creating the firewall rules

Two sets of rules are needed for the Palo Alto integration. When you first create the rules, Palo Alto needs to learn the traffic — so set Service to Any at first and change it to application-default afterwards.

12A - RULE SET 1: Authentication rules

Go to Policies > Authentication and define the three rules below. Useroam must be selected in the Log Forwarding field on every rule.

Palo Alto authentication policy list
Palo Alto authentication rules

12B - RULE SET 2: Security rules

Go to Policies > Security. On every rule, Log at Session End must be selected under Log Settings and Useroam must be assigned in Log Forwarding.

Palo Alto security policy list

Additional technical note (disconnecting a signed-in user): to end an active guest session or clear its cache, sign in to the Palo Alto CLI and run the following commands in order.

To list all signed-in active users and their IP addresses:
show user ip-user-mapping all

To drop the relevant IP address from the network, run:
clear user-cache ip <ip-address>
debug user-id reset captive-portal ip-address <ip-address>

Important — integration complete

That's it — your Palo Alto integration and server change are complete. If you run into any technical problems during the process, contact our support team at destek@useroamteknoloji.com.

Login with WhatsApp — firewall allowlist (walled garden)

For the Login with WhatsApp flow to work while the guest is still behind the captive portal (before internet access is granted), the following addresses must be allowed in your firewall or walled-garden configuration. Without these rules the WhatsApp login screen will not open and the automatic login based on delivery confirmation will not work.

Domains to allow (FQDN)

IP addresses to allow

Note: 157.240.0.0 and 31.13.0.0 are typically /16 network blocks (Meta infrastructure); we recommend defining them as blocks in the firewall (157.240.0.0/16, 31.13.0.0/16). 104.247.174.120 is the Useroam panel IP (/32). Use the domain list if your firewall supports FQDN-based filtering; otherwise use the IP blocks.