This project is a proof of concept and not a polished product. Its intended use case was to build a low cost captive portal for WiFi setups using Aerohive access points. It currently has the following features:
- Landing page with login and self-registration functionality
- User self-registration using name, personal email address and mobile phone number (optional)
- Users must also specify a sponsor email address from a list of approved sponsors
- Sponsor notification via email to accept or reject registrations
- Sending of confirmation email and optionally a short message (SMS) containing the user credentials
- Network login with personal email address and password
- 12 hours MAC address caching of the users devices to allow for seamless reconnects
- Ability to limit the amount of devices per account
You will need a Linux server running Docker and Docker Compose. Clone this repo and rename the .env.sample
file to .env
. Change the values for the variables to match your environment most of them should be self explanatory.
DATABASE_NAME
name of the database used by FreeradiusDATABASE_USER
username for the radius databaseDATABASE_PASS
password for the radius databaseRADIUS_CLIENTS
Radius shared secret in the form of shared_secret@subnet/mask_bitsRADIUS_AUTH_PORT
Radius auth portRADIUS_ACCT_PORT
Radius acct portVIRTUAL_HOST
External hostname as used by LetsEncrypt companion container for nginx-proxyLETSENCRYPT_EMAIL
Mail address External hostname as used by LetsEncrypt companion container for nginx-proxyENDPOINT_LIMIT
Limits how many devices the user can us to simultaniously connect to the WifiSPONSORCC
Specify whether the sponsor should be in CC when sending confirmation email to use can be either TRUE or FALSEUAM_SHARED_SECRET
A 1-128 characters long random string used to secure user passwords during loginCI_ENCRYPTION_KEY
CodeIgniter Encryption KeySMTP_HOST
SMTP server nameSMTP_PORT
SMTP server portSMTP_USER
SMTP usernameSMTP_PASS
SMTP passwordSMTP_CRYPTO
SMTP Encryptiontls
orssl
SIPGATE_SMS_ID
see chapter SMS integration belowSIPGATE_ACCESS_TOKEN
see chapter SMS integration below
A few settings are not available via the .env
variables but need to be changed in order to make Bouncer work properly:
- approved sponsor list in the register function of the Portal library
- sender email address and name in the register function of the Portal library
- sender email address and name in the _send_approval_mail function of the Sponsor controller
Now you can start Bouncer using the docker-compose up
command. Please note Bouncers web interface is not meant to be reachable directly over the internet instead it relies on a reverse proxy as provided by the LetsEncrypt companion container for nginx-proxy. This will also take care of the retrieval and renewal of the SSL certicate by using Let's Encrypt a free, automated, and open Certificate Authority. It is even possible to extend the functionality of the nginx-proxy to also load balance the UDP connections to the Radius containers.
If you're reading this you probably already have some experience with Aerohive access points and HiveManager. So I will not provide a detailed guide how to set it all up but I will point out the most critical settings.
You can find it in HiveManager under CONFIGURATION >> AUTHENTICATION >> Captive Web Portals. Create a new entry and apply the following settings:
- Name (Exact value is not important some random name will do)
- Registration Type: External Authentication
- Captive Web Portal Login Page Settings
- Authentication Method: CHAP
- Login URL: https://your-server-name/aerohive
- Password Encryption: UAM with Shared Secret
- Shared Secret: enter the same random key as in the Bouncer configuration
- Captive Web Portal Success Page Settings
- Show the success page after a successful login: checkbox enabled
- Use the automatically generated web pages
- After successful login: Redirect to initially requested page
- Captive Web Portal Failure Page Settings
- Show the failure page after an unsuccessful login attempt: checkbox enabled
- Use the automatically generated web pages
- After a failed login: Redirect to the login page
- Captive Web Portal Language Support
- Choose the supported and default languages for the Aerohive internal web pages please note: Bouncer is currently only available in english!
You can find it in HiveManager under CONFIGURATION >> AUTHENTICATION >> AAA Client Settings. Create a new entry and apply the following settings:
- Name (Exact value is not important some random name will do)
- IP Address/Domain Name of your server running Bouncer
- Server Type: Auth
- Shared Secret: enter the same shared secret as in the Bouncer configuration please note: This is and should be different from the UAM shared secret above!
- Authentication Port: 1812
You can find it in HiveManager under CONFIGURATION >> SSIDS. Create a new entry and apply the following settings:
- Profile Name
- SSID
- SSID Access Security
- Open
- Enable Captive Web Portal: checkbox enabled
- Enable MAC authentication: checkbox enabled
- Authentication Protocol: PAP
- Optional Settings
- Advanced
- User Profile Application Sequence: MAC Authentication - Captive Web Portal - SSID
- Advanced
This is where you define your guest VLAN ID. It is also a good idea to implement a suitable IP Firewall Policy and bandwidth limiting. How to do this is not in the scope of this document.
Bouncers MAC caching feature relies on the MAC authentication which we enabled earlier in the SSID settings but if the users MAC address is unknown we want to redirect the users to the Captive Web Portal. In order to do this we have to apply a CLI command to the configuration of the access points. For that to work we have to enable supplemental CLI in the settings of the HiveManager. This can be found under HOME >> HIVEMANAGER SETTINGS >> Enable Supplemental CLI. If this is set to Yes you should get a new option under CONFIGURATION >> COMMON OBJECTS. This option is called CLI Supplement in there create a new entry and apply the following command:
security-object <SSID-profile-name> security additional-auth-method mac-based-auth fallback-to-ecwp
Replace <SSID-profile-name> with the Profile Name of your actual SSID as defined in Step 3.
Select the newly created SSID and apply the Captive Portal, AAA client (aka RADIUS) and the User profile. Don't forget to apply the CLI supplement under Additional settings >> Service Settings >> Supplemental CLI! Now save your network policy and apply it to your access points using a full configuration upload.
By default it is possible to use the SMS gateway provided by Sipgate. With slight modifications to the sponsor controller it is also possible to use the Free and Open Source SMS Gateway playSMS.
To use the Sipgate REST API it is recommended to use OAuth2 to create an access token. But if you already have a sipgate account it is also possible to use the API directly. This is particularly useful to determine the correct value for the smsId.
First you have to find out what your userId is.
curl --request GET --user username:password --url https://api.sipgate.com/v2/users
{"items":[{"id":"<userId>","firstname":"John","lastname":"Doe","email":"[email protected]","defaultDevice":"e0","busyOnBusy":false,"admin":true}]}
Now that you know your userId you can query the sms endpoint to get your smsId.
curl --request GET --user username:password --url https://api.sipgate.com/v2/<userId>/sms
{"items":[{"id":"<smsId>","alias":"SMS","callerId":"sipgate"}]}
It is also possible to send out a test SMS via curl.
curl --request POST --user username:password --header "Content-Type: application/json" --data '{"smsId":"<smsId>", "recipient":"+4915123456790", "message":"This is only a test"}' --url https://api.sipgate.com/v2/sessions/sms
Edit the .env file and uncomment the line containing the SIPGATE_SMS_ID and enter your smsId. Have a look at the Sipgate documentation to see how to generate the access token and put it also in the .env file as value for the SIPGATE_ACCESS_TOKEN variable.