Ukraine flag

We stand with our friends and colleagues in Ukraine. To support Ukraine in their time of need visit this page

> Ubiquiti UniFi Controller SMS Authentication

Ubiquiti UniFi Controller SMS Authentication

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 RProxy 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:
  1. Then clone the git repository:
  1. 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.
  1. Go to the unifi-guest-portal directory and run:
docker-compose up -d
  1. You can monitor the process of Protectimus Unifi Guest Portal Server deployment using the command:
docker-compose logs -f
  1. There is also an additional file fragments.html, it is needed to customise the UI of the login screen.
  1. After the deployment process 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.all.yml file, which must be located in the same directory as the executable.

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

3.1. Guest Portal Server Settings

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

The port where the Protectimus Unifi Guest Portal Authentication Server will run.
If you would like to import your own trusted SSL certificate, this property allows you to configure the SSL certificate settings, which include the keystore type, keystore path, keystore password, and key alias.

3.2. Unifi Settings

  cookie-expiration-time: 30000
  base-url: https://localhost:8443
  username: admin
  password: admin
  sites-verification-enabled: true
    - default
    duration-minutes: 90
    download-speed: 2048
    upload-speed: 640
    quota: 4096

Allows setting cookie expiration time.
The UniFi Controller URL.
The username of the Unifi Controller administrator.
The password of the Unifi Controller administrator.
Allows restricting access to the portal from the specified websites.
UniFi Controller sites (fundamental organizational unit that allows you to manage and monitor your UniFi network devices and clients.)
This property allows you to set session settings, including the maximum duration of the session, upload and download limits, and data quota amount.
This is the URL that the client is attempting to open after successful authentication on the guest portal. In this instance, it is These types of URLs are commonly used to test internet connectivity or to redirect to a specific webpage after the authentication process.

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


Your login in the PROTECTIMUS system.
Your API key in the PROTECTIMUS system.
If you are using the PROTECTIMUS cloud service, specify the following API URL:

If you are using the Protectimus on-premise platform, the API URL will be something like: protectimus.api.url=
ID of the resource that you created in the PROTECTIMUS system.

3.4. Report Settings

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

Indicates that the report will be stored in CSV format.
You can specify the parameters you wish to save about your guest logins.
The available options include:
  • Action;
  • ID;
  • IP;
  • Access Point (AP);
  • SSID;
  • Time;
  • Phone Number.
The date format as it should be displayed in the report (e.g., Unix).
Time zone ID.

3.5. An Example of guest-portal.all.yml file

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

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

  login: [email protected]
  api-key: secret
  resource-id: 1

    com.protectimus: INFO

4. Configure Ubiquiti UniFi Controller

4.1. Create a Guest User Group

Create a new User Group before setting up the Guest Network. Creating the user group enables you to define upload and download limits specifically for the guests, giving you greater control over the network usage.
  1. Navigate to Settings –> User Groups.
  2. Select Create New User Group.
  3. Assign the group a name, such as Guests.
  4. Set the upload and download bandwidth limits. For basic internet browsing, 5mbps download and 1mbps upload should suffice. However, if you want to enable streaming, ensure a minimum of 10mbps download.
  5. Click Save to apply the changes.

How to setup the Unifi Captive Portal for your Guests - Step 1 -Create a Guest User group

4.2. Create a Wireless Unifi Guest Network

Now you need to set up a special wireless network for your guests, called the Guest Network. This network will have some important rules to follow:
  • Pre and Post-Authorization Access: This means guests can use the network’s login page to sign in. But once they are logged in, they won’t be able to access the main network.
  • Client Isolation: This feature stops guests from sending messages to other guests on the same network. It keeps their communication private and secure.

To create a Guest Network:
  1. Open the Unifi Controller.
  2. Navigate to Settings –> Wireless Networks.
  3. Click on Create New Wireless Network.
  4. Give the network a name that guests will easily identify as the guest network.
  5. Set the security to open for now, as we will later secure it with a captive portal.
  6. Select Apply guest policies (captive portal, guest authentication, access).
  7. Expand the Advanced Options.
  8. Choose the User Group you just made.

How to setup the Unifi Captive Portal for your Guests - Step 2 - Create a Unifi Guest Network

You’ve successfully set up the Guest Network. Now you need to Configure the Captive Portal.

4.3. Set Up the Guest Policies

In the Unifi Controller, head to the Guest Control section where you can easily create the Guest Portal and configure the authentication method and access duration.

Set up the Guest Policies as shown in the image below.
  1. Enable the Guest Portal.
  2. Select External portal server.
  3. Enter the IP address of the Protectimus Unifi Guest Portal Authentication Server in the IPv4 Address field.
  4. Choose Redirect using hostname and provide the URL of the page that the client will attempt to open after successful authentication on the guest portal (e.g.,
  5. The Pre-Authorization Access field is typically left blank as the default setting.
  6. 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.

 Howto setup the Unifi Captive Portal for your Guests - Step 3 - Set Up the Guest Policies

If you have other questions, contact our customer support service.
Last updated on 2023-08-15