Configuring SMS Authentication on Ubiquiti UniFi Controller

Implement Wi-Fi SMS Authentication (Ubiquiti UniFi Controller SMS Authentication) by setting up a UniFi Captive Guest Portal secured with Protectimus UniFi Guest Portal Server. This solution seamlessly integrates with the Ubiquiti UniFi Controller, enabling you to protect your Wi-Fi network through SMS authentication. You have the flexibility to choose any SMS provider that suits your preferences.

Here’s how the Wi-Fi SMS authentication process works after configuring the guest portal with the Ubiquiti UniFi Controller and connecting it to Protectimus:

1. Users attempting to connect to the Wi-Fi network will be prompted to enter their phone number.
2. A unique one-time password is sent to the user via SMS.
3. The user enters the received one-time password in the designated field.
4. Protectimus verifies the one-time password and either grants or denies access to the Wi-Fi network based on the authentication result.

For security and administrative purposes, the Protectimus server meticulously logs all user inputs in CSV format. The recorded data includes the user’s MAC address, the access point’s MAC address, the assigned IP, and the phone number provided during authentication. Depending on your requirements, you can configure the data storage period to meet your specific needs. Note that in most countries, data retention for a minimum of 6 months is typically required.

You have the option to install the On-Prem Protectimus Authentication Platform on your hardware on-premises or utilize the convenience of the Protectimus Cloud Service. Either way, you can ensure a robust and reliable Wi-Fi SMS authentication solution for your network.

1. Get Registered and Configure Basic Protectimus Settings

1. Register with the Protectimus Cloud Service and activate API or install the Protectimus On-Premise Platform (if you install Protectimus Platform on Windows, check the Radius box during the installation).
2. Add Resource.

2. Install the Protectimus UniFi Guest Portal Server Using a Docker Image

1. To start installing the Protectimus UniFi Guest Portal Server, first of all, download and install docker and docker-compose:

• Docker: https://docs.docker.com/engine/install/
• Docker-compose: https://docs.docker.com/compose/install/

2. Then clone the git repository: https://github.com/protectimus/platform-linux.git

3. Once you have successfully cloned the git repository, edit the file located at unifi-guest-portal/config/guest-portal.yml, and incorporate the properties detailed in the third paragraph.

4. Go to the unifi-guest-portal directory and run:
   
   

   docker-compose up -d

5. You can monitor the process of Protectimus UniFi Guest Portal Server deployment using the command:
   
   

   docker-compose logs -f

6. There is also an additional file fragments.html, it is needed to customise the UI of the login screen.

7. When deployment is complete, the Protectimus UniFi Guest Portal Server will be available at:
   
   

   https://localhost:8080

   You can modify the port in the configuration file (unifi-guest-portal/config/guest-portal.yml).

If you are unable to use the Docker Image for any reason, please get in touch with our support team, and we will assist you with the installation.

3. Configure Protectimus UniFi Guest Portal Authentication Server Settings

The Protectimus UniFi Guest Portal Authentication Server settings can be configured by specifying them in the guest-portal.yml file, which must be located in the same directory as the executable.

Available properties that you should add to the guest-portal.yml file include:

3.1. Guest Portal Server Settings

server:
  port: 8888
  ssl:
	enabled: true
	key-store-type: PKCS12
	key-store: classpath:keystore/guest-portal.p12
	key-store-password: password
	key-alias: guest-portal

port:

ssl:

3.2. UniFi Settings

unifi:
  cookie-expiration-time: 30000
  base-url: https://localhost:8443
  username: admin
  password: admin
  sites-verification-enabled: true
  sites:
	- default
  session:
	duration-minutes: 90
	download-speed: 2048
	upload-speed: 640
	quota: 4096
  redirect-page: https://www.google.com

cookie-expiration-time:

base-url:

username:

password:

sites-verification-enabled:

sites:

session:

redirect-page:

3.3. Protectimus API Settings (setting up connection to the PROTECTIMUS service)

protectimus-api:
  login:
  api-key:
  url: https://api.protectimus.com/
  resource-id: 

login:

api-key:

url:

resource-id:

3.4. Report Settings

report:
  csv:
	params:
  	- action
  	- id
  	- ip
  	- ap
  	- ssid
  	- time
  	- phoneNumber
	date-format: 'yyyy-MM-dd HH:mm:ss z'
	zone-id: UTC

csv:

params:

date-format:

zone-id:

3.5. An Example of guest-portal.yml file

server:
  port: 8888
  ssl:
	enabled: true
	key-store-type: PKCS12
	key-store: file:guest-portal.p12
	key-store-password: password
	key-alias: guest-portal

unifi:
  base-url: https://localhost:8443
  username: admin
  password: admin
  sites:
	- default

protectimus-api:
  login: test@protectimus.com
  api-key: secret
  url: https://api.protectimus.com/
  resource-id: 1

logging:
  level:
	com.protectimus: INFO

4. Configure Ubiquiti UniFi Controller

4.1. Launch UniFi Controller

For testing purposes, the UniFi controller can be run with the following command:

docker run --rm --init -p 8843:8843 -p 8880:8880 -p 8443:8443 -p 3478:3478/udp -v ~/unifi:/unifi --name unifi jacobalberty/unifi

The UniFi-in-Docker container uses the following ports:

• 8080/tcp – Device command/control
• 8443/tcp – Web interface + API
• 3478/udp – STUN service
• 8843/tcp – HTTPS portal (optional)
• 8880/tcp – HTTP portal (optional)

4.2. Configure WiFi for the Hotspot Portal

1. Go to UniFi Controller > Settings > WiFi.
2. Click Create New.
3. Under WiFi Optimization, select Hotspot and leave the default Captive Portal setting.
4. Under Security Protocol, select Open.

4.3. Set Up the Hotspot Portal

1. Under One Way Methods, enable External Portal Server and click Edit.
2. Enter the IP address of the server where the Protectimus Guest Portal is running (default: 127.0.0.1).

3. For the Post-Authorization Restrictions, enter the subnet of your local network. By default, all possible local network addresses are blocked, so you can leave this as it is. However, if you want to grant guests access to specific devices like a printer while restricting access to the rest of your network, you can set those restrictions here. It is recommended to use different subnets for your guest network and your own network to simplify these restrictions.
4. In the Success Landing Page section, provide the Success Text or specify a Custom URL to which the user will be redirected after successful authentication.

5. Authentication Process

When a user connects to the guest WiFi network and attempts to access the Internet, the UniFi Controller redirects the user to the guest portal.

For example:

The redirect URL contains the following parameters:

• /guest/s/default/: This part of the URL path indicates the guest portal, and default suggests the use of default settings for the guest portal.
• ap=74:83:c2:29:f4:1c: This is the MAC address of the access point to which the client is trying to connect to the guest portal.
• id=50:e0:85:68:7f:ef: This is the identifier of the device or client attempting to access the internet through the guest portal.
• t=1639577246: This is the timestamp in Unix format, indicating the current time in seconds. It may be used for checking the validity period of the request or other time-related restrictions.
• url=http://edge.microsoft.com: This is the original URL the client attempted to access before the guest portal redirect.
• ssid=WiFi-test-3: This is the Wi-Fi network’s name (SSID) to which the client is trying to connect.

After successful login, we make a request to the UniFi Controller at /cmd/stamgr to create a new session.

The endpoint /cmd/stamgr in the UniFi Controller is responsible for managing station (client) sessions. It handles tasks related to client devices connected to the Wi-Fi network, such as adding, removing, and controlling their sessions.

If you have other questions, contact our customer support service.