A3 v3.1.2 Installation Guide

You must now configure A3. The A3 web-based configuration interface (called the configurator) is started automatically.To set up A3 for production, do the following:

Step 1. Login to the Web User Interface

Step 2. Choose your deployment type

When you log in to A3 for the first time, you are prompted to choose your deployment mode:

The remainder of this topic assumes that you are deploying A3 as a new deployment.

Step 3. Set administrator credentials

In this step, you configure your administrator credentials. Ensure that you use a very strong password. To configure your credentials, enter the administrator email address and password, and then click Next.

Step 4. Configure host name and network settings

In this step, configure you basic network settings including the A3 host name and eth0 network parameters. To configure the basic settings, enter the following information, and then click Next.

Step 5. Configure the registration VLAN interface

A3 uses VLANs to segregate the network traffic. To configure the registration VLAN interface, click Add VLAN, enter the following information, and then click Save.

Step 6. Configure the isolation VLAN interface.

To configure the registration VLAN interface, click Add VLAN, enter the following information, and then click Save.

Step 7. Review the networking configuration

Ensure that your network and VLAN configurations are correct according to your deployment plan. When you are satisfied, click Next.

Step 8. Choose the license option

You can choose between two licensing options:

Step 9. Integrate with HiveManager

You can integrate ExtremeCloud IQ monitor functions with A3. You configure A3 to send monitoring information to ExtremeCloud IQ, enter the following information, and then click Link with Aerohive aloud account:

Step 10. Starting services

After entering the  ExtremeCloud IQ account services, A3 begins to start the service that it uses. When it completes, A3 prompts you to go to the A3 administrator console. Click Go To Administrator Interface. Click Go to Administration Interface to begin working with your A3 server. Log in using the credentials created in Step 3.

Next we join the A3 server to your existing Microsoft Active Directory domain controller. From A3’s web admin interface, go in Configuration→Policies and Access Control→Domains→Active Directory Domain and click on the Add domain button. Provide the required fields. You will need an Active Directory administrative username and password (member of the domain admins) to join the A3 server to your domain. Once all the information has been provided, click on the Save and join" button.

Once the domain join succeeds, click on the Realms tab. Click on the Default realm and set the domain to the Active Directory domain you have just created. That will instruct A3 to use that newly created Active Directory for the default authentication realm. Next, do the same thing for the NULL realm.

Next we add the Microsoft Active Directory domain controller as an authentication source in A3. To do so, from Configuration→Policies and Access Control→Authentication Sources, click on Add source→Internal→AD. Specify all the required fields. If you need help identifying fields relevant to your Active Directory environment, please use the Active Directory Explorer (AD Explorer) tool from your Active Directory server.

Next, add an Authentication Rules with name catchall with no condition and with the following actions:

• Role - default
• Access duration - 5 days

Make sure the information you provided are valid. Click on the Test button to validate the provided information. If you see the message Success! LDAP connect, bind and search successful - you have properly configured your Microsoft Active Directory authentication source. Save your new authentication source by clicking on the Save button.

Next we configure a switch so that it integrates with A3 using 802.1X. In our example, we will use a Cisco Catalyst 2960 access switch and its IP address will be 172.21.2.3. Our A3’s server IP address will be 172.20.100.2 - you will need to adjust this according to your environment.

Connect to that switch over SSH as an admin.

Enable 802.1X

As a first configuration step, you need to enable 802.1X globally on the switch. To do so, use the following:

Configure AAA

The next step is to configure AAA so it will use your newly created A3 server. Make sure you replace the PF_MANAGEMENT_IP variable with your actual A3 management IP (172.20.100.2 in our example) in the following commands:

Configure Switchport for 802.1X

Once AAA is ready, we can configure some or all switchports to perform 802.1X. In our example, we will only configure port no. 10 to use 802.1X:

Write the switch configuration to memory.

A3 must be aware of the equipment it manages. From Configuration→Policies and Access Control→Network Devices→Switches, click on Add switch → default. Enter your switch IP address (172.21.2.3 in our example). As a switch type, select Cisco Catalyst 2960 and select Production as the Mode. From the Roles tab, make sure Role by VLAN ID is checked and that the VLAN ID associated to the default role is set to your normal VLAN currently in use on your network. In our example, it will be VLAN 20. That means that once a 802.1X authentication is allowed by A3, access will be properly granted in the default role in VLAN 20.

From the RADIUS tab, specify the Secret Passphrase to use - in our example, it is useStrongerSecret. It is very important to correctly set the RADIUS secret passphrase otherwise A3 will prevent the switch from communicating to itself.

Finally, from the SNMP tab, provide the correct Community Read and Community Write values.

Next we need to configure the connection profile in A3. That is required so that A3 knows how to handle a connection coming from the wired network or WiFi network. In our case, we will create a new connection profile to use our Microsoft Active Directory authentication source and also to let A3 know to automatically register any devices that successfully authenticate using 802.1X on the default connection profile.

From Configuration→Policies and Access Control→Connection Profiles, click on on Add profile. Specify the following information:

• Profile Name: 8021x
• Automatically register devices: checked
• Filters: If any of the following conditions are met:
• Connection Type: Ethernet-EAP
• Sources: your newly created Active Directory authentication source

Click on Save to save all configuration changes.

To enable 802.1X on the wired adapter of the Microsoft Windows 7 endpoint, you first need to enable the Wired AutoConfig service. To do so, from the Microsoft Windows Services control panel, double-click on Wired AutoConfig. Make sure Startup type: is set to Automatic and click on Start to enable the service.

Then, from Windows' Network Connection panel, open the Properties window of the LAN interface you will use for testing. From the authentication tab, make sure Enable IEEE 802.1X authentication is checked. As the authentication method, make sure Microsoft: Protected EAP (PEAP) is selected. Then, click on Settings and make sure Validate server certificate is unchecked. As authentication method, make sure Secured password (EAP-MSCHAPv2) is selected. Then, click on Configure …​ and make sure Automatically use my Windows logon name and password (and domain if any) is unchecked.

Save all changes.

Now we are ready to do some testing. First make sure you restart the radiusd service. That is required since we added a new Active Directory domain controller. From Status→Services, click on the Restart button for the radiusd service. A3 will take care of restarting that service and the radiusd-acct and radiusd-auth sub-services.

Connect the Microsoft Windows 7 endpoint on port no. 10 from the Cisco Catalyst 2960 switch. From Microsoft Windows, a popup should appear prompting you for a username and password. Enter a valid username and password from your Microsoft Active Directory domain - this should trigger 802.1X (EAP-PEAP) authentication.

To see what’s going on from A3, click on the Auditing tab from A3’s admin interface. You should see an entry for the MAC address of your Microsoft Windows 7 endpoint. Click on the (+) button to see the RADIUS exchanges. If the 802.1X authentication is successful, you should have Accept as an Auth Status.

In the previous section, we have succesfully configured 802.1X using A3, Microsoft Active Directory and a Cisco Catalyst 2960 switch. While this demonstrates the fundamental role and capabilities of a NAC solution, most organizations are also looking at providing access to guests for example. One way of handling guests on a network is showing them a captive portal and let them register their own devices. This section will guide you in achieving this with A3.

There are two ways A3 can show its captive portal for unknown (or unregistered) devices:

• it can use Web Authentication (or also known as hotspot-style authentication) - this works with numerous equipment vendors
• it can use a registration VLAN, where A3 provides DHCP services and DNS black-holing services - this works with any equipment vendors that support RADIUS dynamic VLAN assignment

For our example, we will use Web Authentication, as it is supported by the Cisco Catalyst 2960. For more information on various enforcement modes, please refer to the Supported Enforcement Modes sections of this document.

Creating Authentication Source for Guests

To keep our example simple, we will simply create a captive portal for guests where they will only have to accept the terms and conditions prior to gaining network access. To do so, we must first create a Null authentication source. From Configuration→Policies and Access Control→Authentication Sources, click on Add Source→External→Null. As Name and Description, specify null-source. Then add an Authentication Rules with name catchall with no condition and with the following tow Actions:

• Role - guest
• Access duration - 12 hours

Click on Save to save the new authentication source.

Configure switchport for Web Authentication

Connect to that switch over SSH as an admin.

First, we need to enable Change-of-Authorization (CoA) in our Cisco Catalyst 2960 switch configuration. We essentially need to allow our A3 server (172.20.100.2) to send CoA requests to the switch:

Then, we must enable Web Authentication on switch port no. 10. Add the following configuration to the global section:

Then add the required access lists:

Adjust Switch Configuration in A3

Next we have to let A3 know that Web Auth is to be used on the Cisco Catalyst 2960 switch. From Configuration→Policies and Access Control→Switches and click on your switch’s IP to open its configuration options. From the Definition tab, make sure Use CoA and External Portal Enforcement are checked and set the CoA Port to 3799. From the Roles tab, make the following changes:

• in Role by VLAN ID, set the registration and guest VLAN ID to 20 - this will ensure unregistered clients are initially put in VLAN 20 and avoid a VLAN change once they properly authenticate from the captive portal
• make sure Role by Switch Role is checked and set the registration role to registration - this will ensure the registration access list created in the previous section is returned for unregistered users. This will limit their access to the A3 captive portal
• make sure Role by Web Auth URL is checked and set the registration URL to http://172.20.100.2/Cisco::Catalyst_2960

Click Save to save all configuration changes.

Enabling Portal on Management Interface

By default the A3 captive portal does not listen on the management interface. To change this, go in Configuration→Network Configuration→Interfaces and click on the logical name of your management interface to bring the configuration panel. In Additional listening daemon(s) - make sure you add portal.

You must then restart the following services from Status→Services:

• haproxy
• httpd.portal
• iptables

Configuring the Connection Profile

For Web Authentication, we will create a new connection profile in A3. That means the default connection profile will be used for 802.1X while the new connection profile will be used for Web Authentication and will be used to display a captive portal with our Null authentication source. From Configuration→Policies and Access Control→Connection Profiles click on Add Profile. Specify the following information:

• Profile Name: guest
• Filters: If any of the following conditions are met:
• Connection Type: WIRED_MAC_AUTH
• Sources: null-source

Click on Save to save all configuration changes.

Testing

First make sure that the Microsoft Windows 7 endpoint is unplugged from the Cisco Catalyst 2960 switch. Then, make sure the endpoint is unregistered from A3. To do this, from the Nodes configuration module, locate its MAC address and click on it. From the node property window, change the Status to unregistered.

Next, we need to disable 802.1X from the network configuration card from the Microsoft Windows 7 endpoint. We want to simulate here an authentication by MAC address, so we have to disable 802.1X to do this. From Windows' Network Connection connection panel, ask for the properties of the LAN interface you will use for testing. From the authentication tab, make sure Enable IEEE 802.1X authentication is unchecked. Save all changes.

Next, connect the endpoint in the Cisco Catalyst 2960 switch. After a few second, open a web browser and try to open any website - say http://www.aerohive.com. You should now see the captive portal. You should only need to accept the terms and conditions for gaining network access.

This section will show you how to enable SMS authentication on the captive portal so that guests use their cellular phone number to register their endpoints. A3 will send an SMS PIN code to the guest phone number. That code will be required to complete the registration process. The SMS code will be sent by A3 over email - using popular SMTP-to-SMS gateways.

Some of the key concepts presented in this section are:

• Authentication sources
• Alerting

Authentication Sources

A3 can authenticate users that register devices via the captive portal using various methods. Among the supported methods, there are:

• Active Directory
• Apache htpasswd file
• Email
• External HTTP API
• Facebook (OAuth 2)
• Github (OAuth 2)
• Google (OAuth 2)
• Instagram (OAuth 2)
• Kerberos
• Kickbox
• LDAP
• LinkedIn (OAuth 2)
• Null
• OpenID Connect (OAuth 2)
• Pinterest (OAuth 2)
• RADIUS
• SMS
• Sponsored Email
• Twitter (OAuth 2)
• Windows Live (OAuth 2)

and many others. Moreover, A3 can also authenticate users defined in its own internal SQL database. Authentication sources can be created from A3 administrative GUI - from the Configuration → Policies and Access Control → Authentication Sources section. Authentication sources, rules, conditions and actions are stored in the conf/authentication.conf configuration file.

Each authentication sources you define will have a set of rules, conditions and actions.

Multiple authentication sources can be defined, and will be tested in the order specified (note that they can be reordered from the GUI by dragging them around). Each source can have multiple rules, which will also be tested in the order specified. Rules can also be reordered, just like sources. Finally, conditions can be defined for a rule to match certain criteria. If the criteria match (one or more), actions are then applied and rules testing stop, across all sources as this is a "first match wins" operation.

When no condition is defined, the rule will be considered as a catch-all. When a catch-all is defined, all actions will be applied for any users that match in the authentication source. Once a source is defined, it can be used from Configuration → Policies and Access Control → Connection Profiles. Each connection profile has a list of authentication sources to use.

In the previous section, you configured two authentication sources: Microsoft Active Directory and the Null sources. They were both catch-all sources.

Alerting

A3 can send emails to administrators, users and guests. So it is important to properly configure the mail sending functionality of A3. From Configuration→System Configuration→Alerting, set at least the following fields:

• Sender - the "From" address of emails being sent by A3
• SMTP server - IP or DNS name of the SMTP server used by A3 to send all emails

If your SMTP server requires authentication or encryption to relay emails, you will have to properly configure the SMTP encryption, username and password parameters.

Adding SMS Authentication Source

Now that you understand what authentication sources and alerting are, we will add an SMS authentication source on our guest portal. We previously used the Null source but we will add an other source. Portal profiles can provide multiple authentication sources.

From Configuration→Policies and Access Control→Authentication Sources, click Add source→External→SMS. As Name and Description, specify sms-source. Then add an Authentication Rules with name catchall with no condition and with the following two Actions:

• Role - guest
• Access duration - 12 hours

You will also need to select the proper carriers to do your test. Make sure you include the one your are using for your cellular phone.

Click on Save to save the new authentication source.

Configuring the Connection Profile

Now let’s add our new SMS-based authentication source to our guests captive portal. From Configuration→Policies and Access Control→Connection Profiles, click on the guest profile that we previously created. In the Sources, cick on the (+) button and add the newly created SMS source, sms-source. Save the changes by clicking on the Save button.

• You can preview at any time the portal associated with connection profile by clicking on the Preview button.

Testing

First unplug and unregister again the Microsoft Windows 7 endpoint. Then, connect the endpoint in switch port no. 10 - you should see the captive portal with the new SMS-based registration option. Note that the Null option will also be offered.

One important key concept from NAC solutions is for seggretating network accesses. For example, an employee from the finance department might not have the same network access level as an other employee from the marketing department. Guests should also not have the same access level as normal employees within an organization. A3 uses roles internally to identify and differentiate users. For seggretating network access, A3 can use one or all of the following techniques:

• ACL
• VLAN or VLAN pool
• equipment role

The techniques to use depends on the wired/WiFi equipment itself. A role in A3 will be eventually mapped to a VLAN, an ACL or an external role. You must define the roles to use in your organization for network access.

In our previous configuration examples, we made use of two roles that come by default in A3: default and guest. We will now add two new roles - one for consultants and one used to authenticate machines on the network.

Adding Roles

Roles in A3 can be created from Configuration → Policies and Access Control → Roles. From this interface, you can also limit the number of devices users belonging to certain roles can register.

Roles are dynamically computed by A3, based on the rules (ie., a set of conditions and actions) from authentication sources, using a first-match wins algorithm. Roles are then matched to VLAN or VLAN pool or internal roles or ACL on equipment from the Configuration → Policies and Access Control → Switches module. For a VLAN pool instead of defining a VLAN identifier, you can set a value like that: 20..23,27..30 - which means that the VLAN returned by A3 can be 20 to 23 and 27 to 30 (inclusively). There are two algorithms: one based on a hash of the username (default one) and the other one based on a round-robin (last registered device +1).

Configuration → Policies and Access Control → Roles, click on Add role. Provide the following information:

• Name: consultant
• Description: Role used for consultants visiting our network
• Max nodes per user: 2

Redo the operation of the other role:

• Name: corporate_machine
• Description: Corporate owned machines
• Max nodes per user: 1

Using the Consultant Role

Let’s say we have two roles: guest and employee. First, we define them Configuration → Policies and Access Control → Roles.

Now, we want to authenticate employees using Active Directory (over LDAP), and guests using A3’s internal database - both using A3’s captive portal. From the Configuration → Policies and Access Control → Authentication Sources, we select Add source → AD. We provide the following information:

• Name: ad1
• Description: Active Directory for Employees
• Host: 192.168.1.2:389 without SSL/TLS
• Base DN: CN=Users,DC=acme,DC=local
• Scope: subtree
• Username Attribute: sAMAccountName
• Bind DN: CN=Administrator,CN=Users,DC=acme,DC=local
• Password: acme123

Then, we add a rule by clicking on the Add rule button and provide the following information:

• Name: employees
• Description: Rule for all consultants
• Don’t set any condition (as it’s a catch-all rule)
• Set the following actions:
  • Set role consultant
  • Set unregistration date January 1st, 2020

Test the connection and save everything. Using the newly defined source, any username that actually matches in the source (using the sAMAccountName) will have the employee role and an unregistration date set to January 1st, 2020.

Now, since we want to authenticate guests from A3’s internal SQL database, accounts must be provisioned manually. You can do so from the Users → Create section. When creating guests, specify "guest" for the Set role action, and set an access duration for 1 day.

Using the Machine Role

If you would like to differentiate user authentication and machine authentication using Active Directory, one way to do it is by creating a second authentication sources, for machines:

• Name: ad1
• Description: Active Directory for Machines
• Host: 192.168.1.2:389 without SSL/TLS
• Base DN: CN=Computers,DC=acme,DC=local
• Scope: One-level
• Username Attribute: servicePrincipalName
• Bind DN: CN=Administrator,CN=Users,DC=acme,DC=local
• Password: acme123

Then, we add a rule:

• Name: machines
• Description: Rule for all machines
• Don’t set any condition (as it’s a catch-all rule)
• Set the following actions:
  • Set role machineauth
  • Set unregistration date January 1st, 2020

• When a rule is defined as a catch-all, it will always match if the username attribute matches the queried one. This applies for Active Directory, LDAP and Apache htpasswd file sources. Kerberos and RADIUS will act as true catch-all, and accept everything.

  If you want to use other LDAP attributes in your authentication source, add them in Configuration→System Configuration→Main Configuration→Advanced→Custom LDAP attributes. They will then be available in the rules you define.

Prior configuring A3, you must chose an appropriate enforcement mode to be used by A3 with your networking equipment. The enforcement mode is the technique used to enforce registration and any subsequent access of devices on your network. A3 supports the following enforcement modes:

• Out-of-band using SNMP or RADIUS
• Hostpot-style (or Web Auth)
• RADIUS only
• DNS

It is also possible to combine enforcement modes. For example, you could use the out-of-band mode on your wired switches, while using the inline mode on your old WiFi access points.

The following sections will explain these enforcement modes. It will also explain you how to properly configure A3 to use each enforcement mode.

Technical Introduction to Out-of-band Enforcement

Introduction

VLAN assignment is currently performed using several different techniques. These techniques are compatible one to another but not on the same switch port. This means that you can use the more secure and modern techniques for your latest switches and another technique on the old switches that doesn’t support latest techniques. As it’s name implies, VLAN assignment means that A3 is the server that assigns the VLAN to a device. This VLAN can be one of your VLANs or it can be a special VLAN where A3 presents the captive portal for authentication or remediation.

VLAN assignment effectively isolate your hosts at the OSI Layer2 meaning that it is the trickiest method to bypass and is the one which adapts best to your environment since it glues into your current VLAN assignment methodology.

VLAN assignment techniques

Wired: 802.1X + MAC Authentication

802.1X provides port-based authentication, which involves communications between a supplicant, authenticator (known as NAS), and authentication server (known as AAA). The supplicant is often software on a client device, such as a laptop, the authenticator is a wired Ethernet switch or wireless access point, and the authentication server is generally a RADIUS server.

The supplicant (i.e., client device) is not allowed access through the authenticator to the network until the supplicant’s identity is authorized. With 802.1X port-based authentication, the supplicant provides credentials, such as user name / password or digital certificate, to the authenticator, and the authenticator forwards the credentials to the authentication server for verification. If the credentials are valid (in the authentication server database), the supplicant (client device) is allowed to access the network. The protocol for authentication is called Extensible Authentication Protocol (EAP) which have many variants. Both supplicant and authentication servers need to speak the same EAP protocol. Most popular EAP variant is PEAP-MsCHAPv2 (supported by Windows / Mac OSX / Linux for authentication against AD).

In this context, A3 runs the authentication server (a FreeRADIUS instance) and will return the appropriate VLAN to the switch. A module that integrates in FreeRADIUS does a remote call to the A3 server to obtain that information. More and more devices have 802.1X supplicant which makes this approach more and more popular.

MAC Authentication is a new mechanism introduced by some switch vendor to handle the cases where a 802.1X supplicant does not exist. Different vendors have different names for it. Cisco calls it MAC Authentication Bypass (MAB), Juniper calls it MAC RADIUS, Extreme Networks calls it Netlogin, etc. After a timeout period, the switch will stop trying to perform 802.1X and will fallback to MAC Authentication. It has the advantage of using the same approach as 802.1X except that the MAC address is sent instead of the user name and there is no end-to-end EAP conversation (no strong authentication). Using MAC Authentication, devices like network printer or non-802.1X capable IP Phones can still gain access to the network and the right VLAN.

Wireless: 802.1X + MAC authentication

Wireless 802.1X works like wired 802.1X and MAC authentication is the same as wired MAC Authentication. Where things change is that the 802.1X is used to setup the security keys for encrypted communication (WPA2-Enterprise) while MAC authentication is only used to authorize (allow or disallow) a MAC on the wireless network.

On wireless networks, the usual A3 setup dictate that you configure two SSIDs: an open one and a secure one. The open one is used to help users configure the secure one properly and requires authentication over the captive portal (which runs in HTTPS).

The following diagram demonstrates the flow between a mobile endpoint, a WiFi access point, a WiFi controller and A3:

1. User initiates association to WLAN AP and transmits MAC address. If user accesses network via a registered device in A3, go to step 8.
2. The WLAN controller transmits MAC address via RADIUS to the A3 server to authenticate/authorize that MAC address on the AP.
3. A3 server conducts address audit in its database. If it does not recognize the MAC address, go to step 4. If it does, go to step 8.
4. A3 server directs WLAN controller via RADIUS (RFC2868 attributes) to put the device in an "unauthenticated role“ (set of ACLs that would limit/redirect the user to the A3 captive portal for registration, or we can also use a registration VLAN in which A3 does DNS blackholing and is the DHCP server).
5. The user’s device issues a DHCP/DNS request to A3 (which is a DHCP/DNS server on this VLAN or for this role) which sends the IP and DNS information. At this point, ACLs are limiting/redirecting the user to the A3’s captive portal for authentication. A3 fingerprints the device (user-agent attributes, DHCP information & MAC address patterns) to which it can take various actions including: keep device on registration portal, direct to alternate captive portal, auto-register the device, auto-block the device, etc. If the device remains on the registration portal the user registers by providing the information (username/password, cell phone number, etc.). At this time A3 could also require the device to go through a posture assessment (using Nessus, OpenVAS, etc.).
6. If authentication is required (username/password) through a login form, those credentials are validated via the Directory server (or any other authentication sources - like LDAP, SQL, RADIUS, SMS, Facebook, Google+, etc.) which provides user attributes to A3 which creates user+device policy profile in its database.
7. A3 performs a Change of Authorization (RFC3576) on the controller and the user must be re-authenticated/reauthorized, so we go back to step 1.
8. A3 server directs WLAN controller via RADIUS to put the device in an "authenticated role“, or in the "normal" VLAN.

Web Authentication Mode

Web authentication is a method on the switch that forwards HTTP traffic of the device to the captive portal.

With this mode, your device will never change of VLAN ID but only the ACL associated to your device will change.

Refer to the Network Devices Configuration Guide to see a sample web auth configuration on a Cisco WLC.

Port-security and SNMP

Relies on the port-security SNMP Traps. A fake static MAC address is assigned to all the ports this way any MAC address will generate a security violation and a trap will be sent to A3. The system will authorize the MAC and set the port in the right VLAN. VoIP support is possible but tricky. It varies a lot depending on the switch vendor. Cisco is well supported but isolation of a PC behind an IP Phone leads to an interesting dilemma: either you shut the port (and the phone at the same time) or you change the data VLAN but the PC doesn’t do DHCP (didn’t detect link was down) so it cannot reach the captive portal.

Aside from the VoIP isolation dilemma, it is the technique that has proven to be reliable and that has the most switch vendor support.

More on SNMP traps VLAN isolation

When the VLAN isolation is working through SNMP traps all switch ports (on which VLAN isolation should be done) must be configured to send SNMP traps to the A3 host. On A3, we use snmptrapd as the SNMP trap receiver. As it receives traps, it reformats and writes them into a flat file: /usr/local/A3/logs/snmptrapd.log. The multithreaded pfsetvlan daemon reads these traps from the flat file and responds to them by setting the switch port to the correct VLAN. Currently, we support switches from Cisco, Edge-core, HP, Intel, Linksys and Nortel (adding support for switches from another vendor implies extending the pf::Switch class). Depending on your switches capabilities, pfsetvlan will act on different types of SNMP traps.

You need to create a registration VLAN (with a DHCP server, but no routing to other VLANs) in which A3 will put unregistered devices. If you want to isolate computers which have open violations in a separate VLAN, an isolation VLAN needs also to be created.

Port Security Traps

In its most basic form, the Port Security feature remembers the MAC address connected to the switch port and allows only that MAC address to communicate on that port. If any other MAC address tries to communicate through the port, port security will not allow it and send a port-security trap.

If your switches support this feature, we strongly recommend to use it rather than linkUp/linkDown and/or MAC notifications. Why? Because as long as a MAC address is authorized on a port and is the only one connected, the switch will send no trap whether the device reboots, plugs in or unplugs. This drastically reduces the SNMP interactions between the switches and A3.

When you enable port security traps you should not enable linkUp/linkDown nor MAC notification traps.

Technical Introduction to RADIUS Enforcement

Introduction

The concept of having a RADIUS enforcement is to not use registration, isolation, nor the portal capabilities of A3. Everything here is for RADIUS integration only. By default the management interface will be the RADIUS interface. If needed, it is possible to add an other interface from Configuration→Network Configuration→Networks→Interfaces. When doing so, you must select Other as the type of interface. Moreover, you must select radius as an additionnal listening daemon.

Using RADIUS enforcement, everytime a device connects to the network, a matching production VLAN will be assigned, depending on the rules in Configuration→Policies and Access Control→Authentication Sources.

Technical Introduction to DNS Enforcement

Introduction

DNS enforcement allows you to control the network access of the device by using the pfdns service on A3.

The architecture of DNS enforcement is as following :

- DHCP and DNS are provided by the A3 server

- The A3 DHCP server will provide the IP of your network equipment as the gateway and the IP address of the A3 DNS server to resolve names.

- Routing is provided by another equipment on your network (Core switch, Firewall, Router,…​)

- If a user should be shown the portal, the pfdns service will return a pointer to the IP address of the captive portal, otherwise pfdns will resolve the name externally and use it in the reply.

This enforcement mode used by itself can be bypassed by the device by using a different DNS server or by using its own DNS cache.

The first can be prevented using an ACL on your routing equipment, the second can be prevented by combining DNS enforcement with Single-Sign-On on your network equipment. Please see the Firewall Single-Sign-On documentation for details on how to accomplish this.

In order to configure DNS enforcement, you first need to go in Configuration → Network Configuration → Networks → Interfaces then select one of your interfaces and set it in DNS enforcement mode.

After, you need to configure a routed network for this interface by clicking Add routed network. See the Routed Networks section of this document for details on how to configure it.

• If you are not using a routed network, you need to use Inline enforcement as DNS enforcement can only be used for routed networks.

Once this is done, you need to restart the dhcpd and pfdns services.

RADIUS Audit Log

Log files

Here are the most important A3 log files:

• /usr/local/A3/logs/A3.log — A3 Core Log
• /usr/local/A3/logs/httpd.portal.access — Apache – Captive Portal Access Log
• /usr/local/A3/logs/httpd.portal.error — Apache – Captive Portal Error Log
• /usr/local/A3/logs/httpd.admin.access — Apache – Web Admin/Services Access Log
• /usr/local/A3/logs/httpd.admin.error — Apache – Web Admin/Services Error Log
• /usr/local/A3/logs/httpd.webservices.access — Apache – Webservices Access Log
• /usr/local/A3/logs/httpd.webservices.error — Apache – Webservices Error Log
• /usr/local/A3/logs/httpd.aaa.access — Apache – AAA Access Log
• /usr/local/A3/logs/httpd.aaa.error — Apache – AAA Error Log

There are other log files in /usr/local/A3/logs/ that could be relevant depending on what issue you are experiencing. Make sure you take a look at them.

The main logging configuration file is /usr/local/A3/conf/log.conf. It contains the configuration for the A3.log file (Log::Log4Perl) and you normally don’t need to modify it. The logging configuration files for every service are located under /usr/local/A3/conf/log.conf.d/.

RADIUS Debugging

First, check the FreeRADIUS logs. The file is located at /usr/local/A3/logs/radius.log.

If this didn’t help, run FreeRADIUS in debug mode. To do so, start it using the following commands.

For the authentication radius process:

For the accounting radius process:

Additionally there is a raddebug tool that can extract debug logs from a running FreeRADIUS daemon. A3’s FreeRADIUS is pre-configured with such support.

In order to have an output from raddebug, you need to either:

• Make sure user pf has a shell in /etc/passwd, add /usr/sbin to PATH (export PATH=/usr/sbin:$PATH) and execute raddebug as pf, or
• Run raddebug as root (less secure!)

Now you can run raddebug easily:

The above will output FreeRADIUS' authentication debug logs for 5 minutes.

Use the following to debug radius accounting:

See man raddebug for all the options.

This section details most of the authentication mechasnisms supported by A3. It walks you through the required steps to properly use an authentication mechanism on your captive portal, for example. For Public Key Infrastructure (PKI) integration, please refer to the PKI Integration section from this document.

Microsoft Active Directory (AD)

Go in the Administration interface under Configuration → Policies and Access Control → Domains → Active Directory Domains.

• If you can’t access this section and you have previously configured your server to bind to a domain externally to A3, make sure you run /usr/local/A3/addons/AD/migrate.pl

Click Add Domain and fill in the information about your domain.

Where :

• Identifier is a unique identifier for your domain. It’s purpose is only visual.
• Workgroup is the workgroup of your domain in the old syntax (like NT4).
• DNS name of the domain is the FQDN of your domain. The one that suffixes your account names.
• This server’s name is the name that the server’s account will have in your Active Directory.
• DNS server is the IP address of the DNS server of this domain. Make sure that the server you put there has the proper DNS entries for this domain.
• Username is the username that will be used for binding to the server. This account must be a domain administrator.
• Password is the password for the username defined above.
• If you are using an Active/Active cluster, each member of the cluster must be joined separately. Please follow the instructions in the A3 Clustering Guide.

Troubleshooting

• In order to troubleshoot unsuccessful binds, please refer to the following file : /chroots/<mydomain>/var/log/samba<mydomain>/log.winbindd. Replace <mydomain> with the identifier you set in the domain configuration.
• You can validate the domain bind using the following command : chroot /chroots/<mydomain> wbinfo -u
• You can test the authentication process using the following command chroot /chroots/<mydomain> ntlm_auth --username=administrator
• Under certain conditions, the test join may show as unsuccessful in the Administration interface but the authentication process will still work properly. Try the test above before doing any additional troubleshooting. Also try reloading the page in the GUI since in some case the browser side of the ajax call may time out while the join actually succeeds.

Default Domain Configuration

You should now define the domain you want to use as the default one by creating the following realm in Configuration → Policies and Access Control → Domains → REALMS

Next, restart A3 in Status → Services

Multiple Domains Authentication

First configure your domains in Configuration → Policies and Access Control → Domains → Active Directory Domains.

Once they are configured, go in Configuration → Policies and Access Control → Domains → REALMS.

Create a new realm that matches the DNS name of your domain AND one that matches your workgroup. In the case of this example, it will be DOMAIN.NET and DOMAIN.

Where :

• Realm is either the DNS name (FQDN) of your domain or the workgroup
• Realm options are any realm options that you want to add to the FreeRADIUS configuration
• Domain is the domain which is associated to this realm

Now create the two other realms associated to your other domains.

You should now have the following realm configuration

OAuth2 Authentication

• OAuth2 authentication does not work with Webauth enforcement

  OAuth2 authentication will fail by design when previewed through "Connection Profiles"

The captive portal of A3 allows a guest/user to register using his Google, Facebook, LinkedIn, Windows Live, Twitter, Instagram, Pinterest, OpenID Connect or Github account.

For each providers, we maintain an allowed domain list to punch holes into the firewall so the user can hit the provider login page.

This list is available in each OAuth2 authentication source.

You must enable the passthrough option in your A3 configuration (fencing.passthrough in pf.conf).

Google

In order to use Google as a OAuth2 provider, you need to get an API key to access their services. Sign up here : http://code.google.com/apis/console.

In the Google APIs Console, go into *Credentials → Create Credentials → OAuth client ID → Web Application, then enter a name and make sure you use this URI for the "Authorized redirect URIs" field : https://YOUR_PORTAL_HOSTNAME/oauth2/callback. Of course, replace the hostname with the values from general.hostname and general.domain.

Save to get the Client ID and Client secret.

You can keep the default configuration, modify the App ID & App Secret (Given by Google on the developer platform) and Portal URL (https://YOUR_PORTAL_HOSTNAME/oauth2/callback).

Also, add the following Authorized domains : *.google.com, *.google.ca, *.google.fr, *.gstatic.com,googleapis.com,accounts.youtube.com (Make sure that you have the google domain from your country like Canada ⇒ *.google.ca, France ⇒ *.google.fr, etc…​)

Once you have your client id, and API key, you need to configure the OAuth2 provider. This can be done by adding a Google OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add Google as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Facebook

To use Facebook, you also need an API code and a secret key. To get one, go here: https://developers.facebook.com/apps. When you create your App, make sure you specify the following as the Website URL:

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

To find the secret, go in your newly created app, and click on Settings → Basic.

In the Facebook developers pages, Settings → Basic, add YOUR_PORTAL_HOSTNAME in the App Domains field.

You can keep the default configuration, modify the App ID & App Secret (Given by Facebook on the developer platform) and Portal URL (https://YOUR_PORTAL_HOSTNAME/oauth2/callback).

Also, add the following Authorized domains : *.facebook.com, *.fbcdn.net, *.akamaihd.net (May change)

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a Facebook OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add Facebook as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

• By allowing OAuth through Facebook, you will give Facebook access to the users while they are sitting in the registration VLAN.

Github

To use Github, you also need an API code and a secret key. To get one, you need to create an App here: https://github.com/settings/applications. When you create your App, make sure you specify the following as the Callback URL

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a GitHub OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add GitHub as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Instagram

To use Instagram, you also need an API code and a secret key. To get one, go here: https://www.instagram.com/developer/clients/manage/. When you create your App, make sure you specify the following as the Website URL:

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a Instagram OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add Instagram as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

LinkedIn

To use LinkedIn, you also need an API code and a secret key. To get one, you need to create an App here: https://developer.linkedin.com/. When you create your App, make sure you specify the following as the Callback URL

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a LinkedIn OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add LinkedIn as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Also, LinkedIn requires a state parameter for the authorization URL. If you modify it, make sure to add it at the end of your URL.

OpenID Connect

Using OpenID Connect is a bit different than other OAuth2 sources. The reason behind that is because you will setup your own OpenID Connect source or depend on a provider for it. Configuration like token path, authorize path or API URL are specific to your setup. For more information on how to create your own or get a host please visit: http://openid.net/connect/.

When you create your App, make sure you specify the following as the Callback URL, https://YOUR_PORTAL_HOSTNAME/oauth2/callback.

Of course, replace the hostname with the values from general.hostname and general.domain.

OpenID connect have different ways to be configured, make sure to create a client ID and a client secret to work with A3.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding an OpenID OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add OpenID as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Pinterest

To use Pinterest, you also need an API code and a secret key. To get one, go here: https://developers.pinterest.com/apps. When you create your App, make sure you specify the following as the Redirect URL:

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a Pinterest OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add Pinterest as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Twitter

To use Twitter, you also need an API code and a secret key which Twitter calls consumer key and consumer secret. Obtain this information by creating an new application from your Twitter Apps Management page. When you create your App, make sure you specify the following as the Callback URL

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a Twitter OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add Twitter as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Windows Live

To use Windows live, you also need an API code and a secret key. To get one, you need to create an App here: https://account.live.com/developers/applications. When you create your App, make sure you specify the following as the Callback URL

https://YOUR_PORTAL_HOSTNAME/oauth2/callback

Of course, replace the hostname with the values from general.hostname and general.domain.

Once you have your information, you need to configure the OAuth2 provider. This can be done by adding a WindowsLive OAuth2 authentication source from Configuration → Policies and Access Control → Authentication Sources.

Remember to add the Authentication Rules with at least two Actions (example: Role and Access duration).

Moreover, don’t forget to add WindowsLive as a Source from your connection profile definition, available from Configuration → Policies and Access Control → Connection Profiles and Pages.

Eduroam

• eduroam (education roaming) is the secure, world-wide roaming access service developed for the international research and education community.

  eduroam allows students, researchers and staff from participating institutions to obtain Internet connectivity across campus and when visiting other participating institutions by simply opening their laptop.

— eduroam

https://www.eduroam.org/

A3 supports Eduroam and allows participating institutions to authenticate both locally visiting users from other institutions as well as allowing other institutions to authenticate local users.

In order for A3 to allow Eduroam authentication, you need to configure an exclusive Eduroam source in Configuration→Authentication Sources and restart the RADIUS services.

SAML Authentication

A3 supports SAML authentication in the captive portal in combination with another internal source to define the level of authorization of the user.

First, transfer the Identity Provider metadata on the A3 server. In this example, it will be under the path /usr/local/A3/conf/idp-metadata.xml.

Then, transfer the certificate and CA certificate of the Identity provider on the server. In this example, they will be under the paths /usr/local/A3/conf/ssl/idp.crt and /usr/local/A3/conf/ssl/idp-ca.crt. If it is a self-signed certificate, then you will be able to use it as the CA in the A3 configuration.

Then, to configure SAML in A3, go in Configuration → Policies and Access Control → Sources and then create a new Internal source of the type SAML and configure it.

Where :

• Service Provider entity ID is the identifier of the Service Provider (A3). Make sure this matches your Identity Provider configuration.
• Path to Service Provider key is the path to the key that will be used by A3 to sign its messages to the Identity Provider. A default one is provided under the path : /usr/local/A3/conf/ssl/server.key
• Path to Service Provider cert is the path to the certificate associated to the key above. A self-signed one is provided under the path : /usr/local/A3/conf/ssl/server.key
• Path to Identity Provider metadata is the path to the metadata file you transferred above (should be in /usr/local/A3/conf/idp-metadata.xml)
• Path to Identity Provider cert is the path to the certificate of the identity provider you transferred on the server above (should be in /usr/local/A3/conf/ssl/idp.crt).
• Path to Identity Provider CA cert is the path to the CA certificate of the identity provider you transferred on the server above (should be in /usr/local/A3/conf/ssl/ca-idp.crt). If the certificate above is self-signed, put the same path as above in this field.
• Attribute of the username in the SAML response is the attribute that contains the username in the SAML assertion returned by your Identity Provider. The default should fit at least SimpleSAMLphp.
• Authorization source is the source that will be used to match the username against the rules defined in it. This allows to set the role and access duration of the user. The Authentication section of this document contains explanations on how to configure an LDAP source which can then be used here.

Once this is done, save the source and you will be able to download the Service Provider metadata for A3 using the link Download Service Provider metadata on the page.

Configure your identity provider according to the generated metadata to complete the Trust between A3 and your Identity Provider.

In the case of SimpleSAMLPHP, the following configuration was used in metadata/saml20-sp-remote.php :

A3 does not support logoff on the SAML Identity Provider. You can still define the URL in the metadata but it will not be used.

Passthroughs

In order for your users to be able to access the Identity Provider login page, you will need to activate passthroughs and add the Identity Provider domain to the allowed passthroughs.

To do so, go in Configuration → Network Configuration → Networks → Fencing, then check Passthrough and add the Identity Provider domain name to the Passhtroughs list.

Next, restart iptables and pfdns to apply your new passthroughs.

Billing Engine

A3 integrates the ability to use a payment gateway to bill users to gain access to the network. When configured, the user who wants to access the network / Internet is prompted by a page asking for it’s personal information as well as it’s credit card information.

A3 currently supports four payment gateways: Authorize.net, Mirapay, Paypal and Stripe.

In order to activate the billing, you will need to configure the following components :

• Billing source(s)
• Billing tier(s)

Configuring a billing source

First select a billing provider and follow the instructions below.

Paypal

• This provider requires that your A3 server is accessible on the public domain. For this your A3 portal should be available on a public IP using the DNS server name configured in A3.

If you have a business account and do not want to configure a test environment, you can skip the next section.

Sandbox account

To configure a sandbox paypal account for use in A3, head to https://developer.paypal.com/ and either sign up or login into your existing account.

Then in the Sandbox menu, click Accounts

Create an account that has the type Personal and one that has the type Business.

Afterwards, go back into accounts, and expand the business account, then click Profile

Now click the Change password link and change the password and note it.

Do the same thing with the personal account you created

Configuring the merchant account

Login into the Paypal business account that you created at https://www.sandbox.paypal.com/ if you are using a sandbox account or on https://www.paypal.com/ if you are using a real account.

Next go in My Account → Profile in order to go into your profile configuration.

Next in the Selling Preferences you will need to select Website Payment Preferences

Configure the settings so they match the screenshot below.

You should turn on Auto Return, set the return URL to https://YOUR_PORTAL_HOSTNAME/billing/paypal/verify.

You should also take note of the Identity Token as it will be required in the A3 configuration.

Next go back in your profile configuration My account → Profile and select Encrypted Payment Settings

Now on this page you will need to submit the certificate used by A3 to Paypal (/usr/local/A3/conf/ssl/server.crt by default).

Once you have submitted it, note it’s associated Cert ID as you will need to configure it in A3.

Still on that page, click the Download link to download the Paypal public certificate and put it on the A3 server under path : /usr/local/A3/conf/ssl/paypal.pem

• The certificate will NOT be the same if you use a sandbox account or a real account.

Configuring A3

Now, in the A3 administration interface, go in Configuration→Policies and Access Control→Sources and create a new source of type Billing → Paypal.

Where :

• Identity token is the one you noted when on the Website Payment Preferences page.
• Cert ID is the one you noted when on the Encrypted Payment Settings.
• Payment type is whether the access is donation based (not mandatory to pay for it).
• Email address is the email address of the merchant paypal account.
• Cert file is the path to the A3 certificate (/usr/local/A3/conf/ssl/server.crt by default).
• Key file is the path to the A3 certificate (/usr/local/A3/conf/ssl/server.key by default).
• Paypal cert file is the path to the Paypal certificate (/usr/local/A3/conf/ssl/paypal.pem in this example).
• Currency is the currency that will be used in the transactions.
• Test mode should be activated if you are using a sandbox account.
• If they aren’t already enabled, you will need to enable passthroughs so that users can reach the domains of this provider. Refer to the Passthroughs section of this document for details

Stripe

Stripe account

First go on https://dashboard.stripe.com, create an account and login.

Next on the top right click Your account then Account settings.

Navigate to the API keys tab and note your key and secret. The test key should be used when testing the configuration and the live key when putting the source in production.

Configuring A3

Now, in the A3 administration interface, go in Configuration→Policies and Access Control→Sources and create a new source of type Billing → Stripe

Where :

• Secret key is the secret key you got from your Stripe account.
• Publishable key is the publishable key you got from your Stripe account.
• Style is whether you are doing a one-time charge or subscription based billing (recurring). See section Subscription based registration below for details on how to configure it.
• Currency is the currency that will be used in the transactions.
• Test mode should be activated if you are using the test key and secret account.
• If they aren’t already enabled, you will need to enable passthroughs so that users can reach the domains of this provider. Refer to the Passthroughs section of this document for details

Authorize.net

Creating an account

First go on https://account.authorize.net to signup for a merchant account or http://developer.authorize.net/ for a sandbox account.

After you created your account you will be shown your API login ID and Transaction key. Note both of these information for usage in the A3 configuration.

Then login into your new account.

Then under Account click Settings.

On the settings page in the section Security settings, click MD5-Hash

Now enter a secret that will be shared between authorize.net and A3.

A3 configuration

Next in the A3 administration interface, go in Configuration→Policies and Access Control→Sources and create a new source of type Billing→AuthorizeNet.

Where :

• API login ID is the one you got earlier while creating your account.
• Transaction key is the one you got earlier while creating your account.
• MD5 hash the one you configured in your Authorize.net account.
• Currency is the currency that will be used in the transactions.
• Test mode should be activated if you are using a sandbox account.
• If they aren’t already enabled, you will need to enable passthroughs so that users can reach the domains of this provider. Refer to the Passthroughs section of this document for details

Mirapay

To be contributed...

Adding billing tiers

Once you have configured one or more billing source, you need to define billing tiers which will define the price and target authentication rules for the user.

In the A3 administration interface, go in Configuration→Advanced Access Configuration→Billing tiers

Then click Add billing tier and configure it.

Where :

• Billing tier is the unique identifier of the billing tier.
• Name is the friendly name of the billing tier.
• Description is an extended description of the billing tier.
• Price is the amount that will be charged to the user.
• Access duration is the amount of time the user will be granted access to your network.
• Role is the target role the user should be in.
• Use time balance defines if the access duration should be computed on real-time access duration meaning if the user buys 24 hours of access he can use the network for 24 hours in different time blocks. This requires a valid RADIUS accounting configuration.
• If don’t want to use all the billing tiers that are defined, you can specify the ones that should be active in the Connection profile.

Subscription based registration

A3 supports subscription based billing using Stripe as a billing provider.

Billing tier

When using subscription based billing, it is advised to configure the billing tier so it has an almost infinite access duration (e.g. 20 years) as the billing provider will be contacting the A3 server when the subscription is canceled.

You should configure a billing tier for each subscription plan you want to have. This example will use the plan simple and advanced configured using the following parameters.

Stripe configuration

Then in your Stripe dashboard, you should go in Subscriptions → Plans.

Then create a new plan.

Where :

• ID is the billing tier identifier. It is important that this matches the ID of the billing tier in A3.
• Amount is the price of the plan. It is important that this matches the price of the billing tier in A3.
• Currency is the currency that will be used in the transactions. It is important that this matches the currency of the Stripe source in A3.
• Interval is the interval at which the customer should be billed. In the case of this example, it is monthly.

Now, following the same procedure, create the advanced plan.

Receiving updates from Stripe

As the subscription can be cancelled by a user, you need to setup your A3 installation to receive updates from Stripe.

Updates are sent using HTTP requests on a public IP.

You need to make sure that your A3 server is available through a public IP on port 80 and that your A3 server hostname resolves on the public domain.

Then, in Stripe, configure a Webhook so Stripe informs A3 of any event that happens in this Stripe merchant account.

In order to do so go in Your Account → Account Settings → Webhooks and click Add endpoint.

Where :

• URL is the URL to the A3 server. This should be http://YOUR_PORTAL_HOSTNAME/hook/billing/stripe
• Mode is whether this webhook is for testing mode or live mode

Now every time a user unsubscribes from a plan, A3 will be notified and will unregister that device from your network.

Extending access before it ends

A3 allows users to extend their access before it has ended. In order to do so, you need to enable Allow access to registration portal when registered accessible via the Captive Portal tab of the Connection Profiles. Once this is activated, the users can reach https://YOUR_PORTAL_IP/status and select Extend your access in order to be able to access the billing section after they have registered.

External API Authentication

A3 also supports calling an external HTTP API as an authentication source. The external API needs to implement an authentication action and an authorization action.

Authentication

This should provide the information about whether or not the username/password combination is valid

These information are available through the POST fields of the request

The server should reply with two attributes in a JSON response

• result : should be 1 for success, 0 for failure
• message : should be the reason it succeeded or failed

Example JSON response :

Authorization

This should provide the actions to apply on a user based on it’s attributes

The following attributes are available for the reply : access_duration, access_level, sponsor, unregdate, category.

Sample JSON response, note that not all attributes are necessary, only send back what you need.

• See /usr/local/A3/addons/example_external_auth for an example implementation compatible with A3.

A3 Configuration

In A3, you need to configure an HTTP source in order to use an external API.

Here is a brief description of the fields :

• Host : First, the protocol, then the IP address or hostname of the API and lastly the port to connect to the API.
• API username and password : If your API implements HTTP basic authentication (RFC 2617) you can add them in these fields. Leaving any of those two fields empty will make A3 do the requests without any authentication.
• Authentication URL : URL relative to the host to call when doing the authentication of a user. Note that it is automatically prefixed by a slash.
• Authorization URL : URL relative to the host to call when doing the authorization of a user. Note that it is automatically prefixed by a slash.

Portal Modules

The A3 captive portal flow is highly customizable. This section will cover the Portal Modules which are used to define the behavior of the captive portal.

• When upgrading from a version that doesn’t have the portal modules, the A3 Portal Modules configuration already comes with defaults that will fit most cases and offers the same behavior as previous versions of A3. Meaning, all the available Connection Profile sources are used for authentication, then the available provisioners will be used.

First, a brief description of the available Portal Modules:

• Root: This is where it all starts, this module is a simple container that defines all the modules that need to be applied in a chained way to the user. Once the user has completed all modules contained in the Root, he is released on the network.
• Choice: This allows to give a choice between multiple modules to the user. The default_registration_policy is a good example of a choice that is offered to the user.
• Chained: This allows you to define a list of modules that a user needs to go through in the order that they are defined - ex: you want your users to register via Google+ and pay for their access using PayPal.
• Message: This allows you to display a message to the user. An example is available below in Displaying a message to the user after the registration
• URL: This allows you to redirect the user to a local or external URL which can then come back to the portal to continue. An example is available below in Calling an external website.
• Authentication: The authentication modules can be of a lot of types. You would want to define one of these modules, in order to override the required fields, the source to use, the template or any other module attribute.
  • Billing: Allows to define a module based on one or more billing sources
  • Choice: Allows to define a module based on multiple sources and modules with advanced filtering options. See the section Authentication Choice module below for a detailed explanation.
  • Login: Allows you to define a username/password based module with multiple internal sources (Active Directory, LDAP, …​)
  • SelectRole: Allows to define a module to override the role given when registering a device. For instance: an admin user is trying to register a device using the normal registration process, with this module the admin can choose which role to apply to the device while registering it. It will bypass authentication rules.
  • Other modules: The other modules are all based on the source type they are assigned to, they allow to select the source, the AUP acceptance, and mandatory fields if applicable.

Examples

This section will contain the following examples:

• Prompting for fields without authentication.
• Prompting additional fields during the authentication.
• Chained authentication.
• Mixing login and Secure SSID on-boarding on the portal.
• Displaying a message to the user after the registration.

Creating a custom root module

First, create a custom root module for our examples in order to not affect the default policy. In order to do so, go in Configuration → Advanced Access Configuration → Portal Modules, then click Add Portal Module and select the type Root. Give it the identifier my_first_root_module and the description My first root module, then hit save.

Next, head to Configuration → Policies and Access Control → Connection Profiles, select the connection profile you use (most probably default) and then under Root Portal Module, assign My first root module then save your profile. If you were to access the captive portal now, an error would display since the Root module we configured doesn’t contain anything.

You could add some of the pre-configured modules to the new Root module you created and that would make the error disappear.

Prompting for fields without authentication

In order to prompt fields without authentication, you can use the Null source with the Null Portal Module.

A3 already comes with a Null source pre-configured. If you haven’t modified it or deleted it, you can use it for this example. Otherwise, go in Configuration → Policies and Access Control → Sources and create a new Null source with a catchall rule that assigns a role and access duration.

Then go in Configuration → Advanced Access Configuration → Portal Modules and click Add Portal Module and select Authentication → Null. Set the Identifier to prompt_fields and configure the module with the Mandatory fields you want and uncheck Require AUP so that the user doesn’t have to accept the AUP before submitting these fields.

Next, add the prompt_fields module in my_first_root_module (removing any previous modules) and save it. Now when visiting the portal, it should prompt you for the fields you define in the module. Then, submitting these information will assign you the role and access duration that you defined in the null source.

Prompting additional fields during the authentication

If you want to prompt additional fields during the authentication process for a module, you can define a Module based on that source that will specify the additional mandatory fields for this source.

You can also add additional mandatory fields to the default policies that are already configured.

This example will make the default_guest_policy require the user to enter a first name, last name and address so that guests have to enter these three information before registering.

Go in Configuration → Advanced Access Configuration → Portal Modules and click the default_guest_policy. Add firstname, lastname and address to the Mandatory fields and save.

Next, add the default_guest_policy to my_first_root_module (removing any previous modules). Now when visiting the portal, selecting any of the guest sources will require you to enter both the mandatory fields of the source (ex: phone + mobile provider) and the mandatory fields you defined in the default_guest_policy.

• Not all sources support additional mandatory fields (ex: OAuth sources like Google, Facebook, …​).

Chained authentication

The portal modules allow you to chain two or more modules together in order to make the user accomplish all of the actions in the module in the desired sequence.

This example will allow you to configure a Chained module that will require the user to login via any configured OAuth source (Github, Google+, …​) and then validate his phone number using SMS registration.

For the OAuth login we will use the default_oauth_policy, so just make sure you have an OAuth source configured correctly and available in your Connection Profile.

Then, we will create a module that will contain the definition of our SMS registration.

Go in Configuration → Advanced Access Configuration → Portal Modules then click Add Portal Module and select Authentication → SMS.

Configure the portal module so that it uses the sms source and uncheck the Require AUP option since the user will have already accepted the AUP when registering using OAuth.

Then, add another Portal Module of type Chained. Name it chained_oauth_sms, assign a relevant description and then add default_oauth_policy and sms to the Modules fields

Next, add the chained_oauth_sms module in my_first_root_module (removing any previous modules) and save it. Now when visiting the portal, you should have to authentication using an OAuth source and then using SMS based registration.

Mixing login and Secure SSID on-boarding on the portal

This example will guide you through configuring a portal flow that will allow for devices to access an open SSID using an LDAP username/password but also give the choice to configure the Secure SSID directly from the portal.

First, we need to configure the provisioners for the Secure SSID onboarding. Refer to section Apple and Android Wireless Provisioning of this guide to configure your provisioners and add them to the connection profile.

Create a provisioner of the type Deny and add it with your other provisioners (putting any other provisioner before it). This will make sure that if there is no match on the other provisioners, it will not allow the device through.

Also in the connection profile add your LDAP source to the available sources so its the only one available.

Next, create a Provisioning portal module by going in Configuration → Advanced Access Configuration → Portal Modules. Set the Identifier to secure_boarding and the description to Board Secure SSID. Also uncheck Skippable so the user is forced to board the SSID should it choose this option.

Then, still in the Portal Modules, create a Choice module. Set the Identifier to login_or_boarding and description to Login or Boarding. Add secure_boarding and default_login_policy to the Modules field and save.

Next, add the login_or_boarding module in my_first_root_module (removing any previous modules) and save it. Now when visiting the portal, you will have the choice between login to the LDAP source and gain access to the network or directly use provisioning in order to configure your device for a Secure SSID.

Displaying a message to the user after the registration

Using the Message module you can display a custom message to the user. You can also customize the template to display in order to display a fully custom page.

Go in Configuration → Advanced Access Configuration → Portal Modules, then click Add Portal Module and select Message. Set the Identifier to hello_world and the description to Hello World.

Then put the following in the Message field

Next, add default_registration_policy and hello_world in the Modules of my_first_root_module (removing any previous modules) and save it. Now when visiting the portal, you should have to authenticate using the sources defined in your connection profile and you will then see the hello world message.

Calling an external website

Using the URL module, you can redirect the user to a local or external URL (as long as it is in the passthroughs). Then you can make it so the portal accepts a callback in order for the flow to continue.

In this example, the portal will redirect to an externally hosted PHP script that will give a random token to the user and then callback the portal to complete the registration process.

The example script is located in addons/example_external_auth/token.php and a README is available in that directory to set it up.

Once you have the script installed and working on URL: http://YOUR_PORTAL_HOSTNAME:10000/token.php, you can configure what you need on the A3 side.

Go in Configuration → Advanced Access Configuration → Portal Modules, then click Add Portal Module and select URL. Set the Identifier to token_system, the Description to Token system and the URL to http://YOUR_PORTAL_HOSTNAME:10000/token.php.

Next, add default_registration_policy and token_system in the Modules of my_first_root_module (removing any previous modules) and save it. Now when visiting the portal, you should have to authenticate using the sources defined in your connection profile and then you will be redirected to example token system. Clicking the continue link on that system will bring you back to the portal and complete the registration process.

Authentication Choice module (advanced)

The Authentication Choice module allows to define a choice between multiple sources using advanced filtering rules, manual selection of the sources and selection of Portal Modules.

All the sources that are defined in the Sources field will be available for usage by the user. Same goes for the modules defined in Modules.

You can also define which mandatory fields you want to prompt for these authentication choices. Although you can still configure them on any Authentication Choice module, they will only be shown if they are applicable to the source.

In addition to the manual selection above you can dynamically select sources part of the Connection Profile based on their object attribute (Object Class, Authentication type, Authentication Class).

• You can find all the authentication objects in lib/pf/Authentication/Source
• Sources by class: Allows you to specify the perl class name of the sources you want available
  • ex: pf::Authentication::Source::SMSSource will select all the SMS sources. pf::Authentication::Source::BillingSource will select all the billing sources (Paypal, Stripe, …​)
• Sources by type: Allows you to filter out sources using the type attribute of the Authentication object
• Sources by Auth Class: Allows you to filter our sources using the class attribute of the Authentication object.

You can see the default_guest_policy and default_oauth_policy for examples of this module.

SelectRole

The SelectRole module allows to define specific roles manually when registering a device. This is useful if for instance you ask your technical crew to register new devices.

The configuration is simple, you have a role which is the Admin role the one allowed to select the role while registering a new device and the Role List which is the list of roles that can be chosen from while registering a device.

For instance; techs are in the AD group tech support and get the role tech support while registering, let’s put tech support as the Admin role. They are allowed to register new devices with the roles default, voice and guest. Every time someone with the role tech support will try to register a device on a connection profile where this portal module is active, then the crew memeber will be asked to choose which role to assign to this device.

Devices Registration

Users have the possibility to register their devices right from a special portal page. When accessing this page, users will be prompted to login as if they were registering themselves. Once logged in, the portal will ask them to enter the device MAC address that will then be matched against the Fingerbank database to match authorized devices list. The device will be registered with the user’s id and can be assigned into a specific category for easier management.

The section Configuration → → Advanced Access Configuration → Device Registration is where to configure it.

The portal page can be accessed by the following URL: https://YOUR_PORTAL_HOSTNAME/device-registration

This URL is accessible from within the network, in any VLAN that can reach the A3 server.

As from A3 7.3 and onwards you need to create a device registration profile and associate it with the connection profile.

This will allow you to configure who is able to register which type of device. For instance a person connecting from the public WiFi can only register an Android device but a person from the internal network can register Windows and MacOS computers.

• A portal interface type is required to use this feature. A portal interface type can be added to any network interface using the web admin GUI.

Passthroughs

Passthroughs are used to allow access to certain resources that are outside of the registration confinement process for the users that are in it.

A good example would be when you want to allow access to a password reset server even for clients that are currently on the captive portal.

There are two solutions for passthroughs - one using DNS resolution and iptables and the other one using Apache’s mod_proxy module.

Note that non-HTTP (including HTTPS) protocols cannot use the mod_proxy approach.

You can use one of them or both but for if a domain is configured in both, DNS passthroughs have a higher priority.

In order to use the passthroughs feature in A3, you need to enable it from the GUI in Configuration→Network Configuration→Networks→Fencing, enable Passthrough and then save.

DNS passthroughs

• In active-active cluster, pfdns needs to listen on VIP only. Configuration→System Configuration→Cluster→pfdns on VIP only

If you just enabled the passthroughs, you should restart the iptables services after configuring the parameter (/usr/local/A3/bin/pfcmd service iptables restart).

Then add passthroughs in Configuration→Network Configuration→Networks→Fencing→Passthroughs. They can be of the following format:

• example.com: opens ports 80 and 443 in TCP for example.com
• example.com:1812: opens the port 1812 in TCP and UDP for example.com
• example.com:tcp:1812: opens the port 1812 in TCP for example.com
• example.com:udp:1812: opens the port 1812 in UDP for example.com

In addition to the options above, you can prefix the domain with *. (*.example.com) to white list all the subdomains of example.com (ex: www.example.com, my.example.com).

Should you combine multiple times the same domain with different ports (example.com,example.com:udp:1812,example.com:udp:1813) in the passthroughs, it will open all ports specified in all entries. In the previous example that would open ports 80, 443 in TCP as well as 1812 and 1813 in UDP.

Now when pfdns receives a request for one of these domains, it will reply with the real DNS records for the FQDN instead of a response that points to the captive portal.

At the same time, it will add the entry to a special ipset which will allow access to the real IP address attached the FQDN via iptables based routing.

Apache mod_proxy passthroughs

The proxy passthroughs can be configured in Configuration→Network Configuration→Networks→Fencing→Proxy Passthroughs.

Add a new FQDN (can also be a wildcard domain like *.google.com). Port specific passthroughs cannot be used as these only apply to port 80 in TCP.

Then for this FQDN, pfdns will still answer with the IP address of the captive portal and when a device hits the captive portal, A3 will detect that this FQDN has a passthrough configured in A3 and will forward the traffic to mod_proxy.

Proxy Interception

A3 enables you to intercept proxy requests and forward them to the captive portal. It only works one layer-2 networks because A3 must be the default gateway.

In order to use the Proxy Interception feature, you need to enable it from the GUI in

Configuration → Network Configuration → Networks → Fencing and check Proxy Interception.

Add the port you want to intercept (like 8080 or 3128) and add a new entry in the /etc/hosts file to resolve the fully qualified domain name (fqdn) of the captive portal to the IP address of the registration interface. This modification is mandatory in order for Apache to receives the proxy requests.

Parked Devices

In the event that you are managing a large registration network with devices that stay there (ex: Students that can’t register in your environment), these devices consume precious resources and generate useless load on the captive portal and registration DHCP server.

Using the parking feature, you can make these devices have a longer lease and hit an extremely lightweight captive portal so that the amount of resources they consume is minimal. In that captive portal, they will see a message explaining that they haven’t registered their device for a certain amount of time, and will let them leave the parked state by pressing a link.

The parked vs unparked state is controlled through violation 1300003 which gets triggered according to the parking.threshold setting (Configuration→Network Configuration→Networks→Device Parking).

So, in order to activate the parking, go in Configuration→Network Configuration→Networks→Device Parking and set the threshold to a certain amount of seconds. A suggested value would be 21600 which is 6 hours. This means that if a device stays in your registration network for more than 6 hours in a row, it will trigger violation 1300003 and place that device into the parked state.

In that same section, you can define the lease length of the user when he is in the parked state.

• Parking is detected when a device asks for DHCP, if A3 is not your DHCP server for the registration network, this feature will not work. Also, if the device goes into the parked state with a lease time of 1 hour and the user immediately releases himself from the parking state, it will take 1 hour before the next detection takes place even if you set parking.threshold to a lower value.

Violation 1300003

This violation controls what happens when a user is detected doing parking.

Here are the main settings:

• You can add actions to the predefined ones (like Email admin or External action) in Definition → Actions
• The amount of time a user can unpark their device is controlled through the Remediation → Max enable setting.
• The amount of grace time between two parking violations is controlled by the Remediation → Grace setting. This means, once a user release himself from the parked state, he will have at least this amount of time to register before the parking triggers again.
• The destination role (thus VLAN) of the user is controlled by Advanced → Role. You should leave the user in the registration role, but should you want to dedicate a role for parking, you can set it there.
• The Template attribute will only be used when the user is on the normal A3 portal and not the one dedicated for parking. If you want the user to access the non-parking portal, disable Show parking portal in Configuration → Network Configuration → Networks → Device Parking

Connection Profiles

A3 comes with a default connection profile. The follow parameters are important to configure no matter if you use the default connection profile or create a new one:

• Redirect URL under Configuration → Policies and Access Control → Connection Profile → Profile Name

For some browsers, it is preferable to redirect the user to a specific URL instead of the URL the user originally intended to visit. For these browsers, the URL defined in redirecturl will be the one where the user will be redirected. Affected browsers are Firefox 3 and later.

• IP under Configuration → Advanced Access Configuration → Captive portal

This IP is used as the web server who hosts the common/network-access-detection.gif which is used to detect if network access was enabled. It cannot be a domain name since it is used in registration or quarantine where DNS is black-holed. It is recommended that you allow your users to reach your A3 server and put your LAN’s A3 IP. By default we will make this reach A3’s website as an easier and more accessible solution.

In some cases, you may want to present a different captive portal (see below for the available customizations) according to the SSID, the VLAN, the switch IP/MAC or the URI the client connects to. To do so, A3 has the concept of connection profiles which gives you this possibility.

When configured, connection profiles will override default values for which it is configured. When no values are configured in the profile, A3 will take its default ones (according to the "default" connection profile).

Here are the different configuration parameters that can be set for each connection profiles. The only mandatory parameter is "filter", otherwise, A3 won’t be able to correctly apply the connection profile. The parameters must be set in conf/profiles.conf:

Connection profiles should be managed from A3’s Web administrative GUI - from the Configuration → Policies and Access Control → Connection Profiles section. Adding a connection profile from that interface will correctly copy templates over - which can then be modified as you wish.

Filters under Configuration → Policies and Access Control → Connection Profile → Profile Name → Filters

A3 offers the following filters: Connection Type, Network, Node Role, Port, realm, SSID, Switch, Switch Port, URI, VLAN and Time period.

Example with the most common ones:

• SSID: Guest-SSID
• VLAN: 100
• Time period: wd {Mon Tue} hr {1pm-3pm} — See http://search.cpan.org/~pryan/Period-1.20/Period.pm
• Switch Port: <SwitchId>-<Port>
• Network: Network in CIDR format or an IP address
• Node role will take effect only with a 802.1X connection or if you use VLAN filters.
• Advanced filter under Configuration → Policies and Access Control → Connection Profile → Profile Name → Advanced Filter

Examples

• last_switch =~ "^JAMES" && extended.mse_inout.bob == "bobby"

A3 relies extensively on Apache for its captive portal, administrative interface and Web services. The A3 Apache configuration is located in /usr/local/A3/conf/httpd.conf.d/.

In this directory you have three important files: httpd.admin, httpd.portal, httpd.webservices, httpd.aaa.

• httpd.admin is used to manage A3 admin interface
• httpd.portal is used to manage A3 captive portal interface
• httpd.webservices is used to manage A3 webservices interface
• httpd.aaa is use to manage incoming RADIUS request

These files have been written using the Perl language and are completely dynamic - so they activate services only on the network interfaces provided for this purpose.

The other files in this directory are managed by A3 using templates, so it is easy to modify these files based on your configuration. SSL is enabled by default to secure access.

Upon A3 installation, self-signed certificates will be created in /usr/local/A3/conf/ssl (server.key and server.crt). Those certificates can be replaced anytime by your 3rd-party or existing wild card certificate without problems. Please note that the CN (Common Name) needs to be the same as the one defined in the A3 configuration file (pf.conf).

Reuse 802.1X credentials

Under certain circumstances, for example to show an AUP after a successful 802.1X connection, it might be interesting to have the ability to use an "SSO emulation" in the sense that the user does not need to re-enter his credentials on the portal after having entered them during the 802.1X EAP process. The Reuse 802.1X credentials connection profile option will address this purpose. The same username as the one used during the 802.1X connection will be used against the different connection profile authentication sources to recompute the role from the portal.

As a security precaution, this option will only reuse 802.1X credentials if there is an authentication source matching the provided realm. This means, if users use 802.1X credentials with a domain part (username@domain, domain\username), the domain part needs to be configured as a realm under the RADIUS section and an authentication source needs to be configured for that realm. If users do not use 802.1X credentials with a domain part, only the NULL realm will be match IF an authentication source is configured for it.

VLAN Filter Definition

We added the ability to specify filters directly in the portion of code that re-evaluates the VLAN or do a call to the API.

These rules are available in different scopes:

And can be defined using different criteria like:

Below are several common examples of VLAN filters usage.

EXAMPLE: prevent a device from connecting when its role is "default", the SSID is "SECURE", the current time is between 11am and 2pm, from Monday to Friday and as a registered device

EXAMPLE: create a violation if the SSID is OPEN and the owner is igmout

EXAMPLE: autoregister the device and assign the role staff to each device where the username is igmout.

EXAMPLE: autoregister all Windows devices and assign them the role default.

EXAMPLE: filter a MAC address and reject it by assigning the role REJECT.

EXAMPLE: autoregister devices using dot1x/EAP over wired or wireless and that are not pending

EXAMPLE: auto set Avaya and Polycom as phones by matching vendor MAC, and set to default role

EXAMPLE: Refuse user authentication without prior machine authentication

EXAMPLE: autoregister printers and scanners

You can also add notes to the device using filters. Here you can see how to add a note to all HP Printers.

You can have a look in the file vlan_filters.conf, there are some examples on how to use and define filters.

RADIUS Filter Definition

We added the ability to specify filters directly in the portion of code that return the radius answer or do a call to the API.

These rules are only available in one scope:

And can be defined using different criteria like:

For example, lets define a rule that return Access Accept when the connection is Ethernet-EAP and when there is no violation

(merge_return means that the original answer of A3 will be merge with the filter answer automatically):

In this other example we just add a new attribute to the original answer in the same conditions

(here $user_role will be replaced by the real user role of the device and ${switch._portalURL} will be replaced

by the value of _portalURL defined in the switch config):

Here is an example on filtering by switch IP addresses and using MAC authentication, and then changing session and idle timeouts.

Fingerbank can also be used to target specific devices as seen below. We can then apply Cisco ACLs to them.

You can have a look in the file radius_filters.conf, there are some examples on how to use and define filters.

This section presents the FreeRADIUS configuration steps. In some occasions, a RADIUS server is mandatory in order to give access to the network. For example, the usage of WPA2-Enterprise (Wireless 802.1X), MAC authentication and Wired 802.1X all require a RADIUS server to authenticate the users and the devices, and then to push the proper roles or VLAN attributes to the network equipment.

Local Authentication

Add your user’s entries at the end of the /usr/local/A3/raddb/users file with the following format:

Authentication against Active Directory (AD)

To perform EAP-PEAP authentication using Microsoft Active Directory, please refer to the Active Directory documentation from the Authentication Mechanism section.

EAP Authentication against OpenLDAP

To authenticate 802.1X connection against OpenLDAP you need to define the LDAP connection in /usr/local/A3/raddb/modules/ldap and

be sure that the user password is define as a NTHASH or as clear text.

Next in /usr/local/A3/raddb/sites-available/A3-tunnel add in the authorize section:

EAP Guest Authentication on Email, Sponsor and SMS Registration

This section will allow local credentials created during guest registration to be used in 802.1X EAP-PEAP connections.

First create a guest SSID with the guest access you want to use (Email, Sponsor or SMS, …​) and activate Create local account on that source.

At the end of the guest registration, A3 will send an email with the credentials for Email and Sponsor. For SMS the phone number and the PIN code should be used.

• This option doesn’t currently work with the Reuse dot1x credentials option of the captive portal.

In /usr/local/A3/conf/radiusd/A3-tunnel uncomment the line # A3-local-auth and restart radiusd.

This will activate the feature for any local account on the A3 server. You can restrict which accounts can be used by commenting the appropriate line in /usr/local/A3/raddb/policy.d/A3.

For example, if you would want to deactivate this feature for accounts created via SMS, you would have the following :

• For this feature to work, the users' passwords must be stored in clear text in the database. This is configurable via advanced.hash_passwords.

EAP Local User Authentication

The goal here is to use the local user to authenticate 802.1X device.

Edit /usr/local/A3/conf/radiusd/A3-tunnel

Restart the radiusd service in order to apply the change.

/usr/local/A3/bin/pfcmd service radiusd restart

• You will need to disable password hashing in the database for local authentication to work. In the administration interface, go in Configuration → System Configuration → Main Configuration →Advanced and set Database passwords hashing method to plaintext or ntlm. Don’t use bcrypt.

Limit Brute Force EAP Authentication

This section will allow you to limit a brute force attack and prevent the locking of Active Directory accounts.

Edit /usr/local/A3/conf/radiusd/A3-tunnel

# Uncomment the following lines to enable this feature

By default it will reject for 5 minutes a device that has been rejected twice in the last 5 minutes. You can change the default values in raddb/policy.d/packetfence and in raddb/mods-enabled/cache_ntlm

Testing

Test your setup with radtest using the following command and make sure you get an Access-Accept answer:

RADIUS Accounting

RADIUS Accounting is usually used by ISPs to bill clients. In A3, we are able to use this information to determine if the node is still connected, how much time it has been connected, and how much bandwidth the user consumed.

Violations

Using A3, it is possible to add violations to limit bandwidth abuse. The format of the trigger is very simple:

Let’s explain each chunk properly:

• DIRECTION: You can either set a limit to inbound(IN), outbound(OUT), or total(TOT) bandwidth
• LIMIT: You can set a number of bytes(B), kilobytes(KB), megabytes(MB), gigabytes(GB), or petabytes(PB)
• INTERVAL: This is actually the time window we will look for potential abuse. You can set a number of days(D), weeks(W), months(M), or years(Y).

Example triggers

• Look for Incoming (Download) traffic with a 50GB/month

• Look for Outgoing (Upload) traffic with a 500MB/day

• Look for Total (Download + Upload) traffic with a 200GB limit in the last week

Grace Period

When using such violation feature, setting the grace period is really important. You don’t want to put it too low (ie. A user re-enable his network, and get caught after 1 bytes is transmitted!) or too high. We recommend that you set the grace period to one interval window.

Fingerbank, a great device profiling tool developed alongside of A3, now integrates with it to power-up the feature set allowing a A3 administrator to easily trigger violations based on different device types, device parents, DHCP fingerprints, DHCP vendor IDs, MAC vendors and browser user agents.

The core of that integration resides in the ability for a A3 system, to interact with the Fingerbank upstream project, which then allow a daily basis fingerprints database update, sharing unknown data so that more complex algorithms can process that new data to integrate it in the global database, querying the global upstream database in the case of an unknown match and much more.

Since the Fingerbank integration is now the "de facto" device profiling tool of A3, it was a requirement to make it as simple as possible to configure and to use. From the moment a working A3 system is in place, Fingerbank is also ready to be used, but only in a "local" mode, which means, no interaction with the upstream Fingerbank project.

Update Fingerbank Database

Updating the Fingerbank data can’t be easier. The only requirement is the onboarding process which allows you to interact with upstream project. Once done, an option to "Update Fingerbank DB" can be found on top of every menu item sections under "Fingerbank". Process may take a minute or two, depending on the size of the database and the internet connectivity, after which a success or error message will be show accordingly. "Local" records are NOT being modified during this process.

Submit Unknown Data

Saying that we don’t know everything is not false modesty. In that sense, the "Submit Unknown/Unmatched Fingerprints" option is made available (after onboarding) so that unknown fingerprinting data going in and out on your network can easily be submitted to the upstream Fingerbank project for further analysis and integration the in the global database.

Upstream Interrogation

By default, A3 is configured to interrogate the upstream Fingerbank project (if onboarding has been completed) to fulfill a query with unmatched local results. Unmatched local results can result of an older version of the Fingerbank database or a requirement for a more complex algorithm due to the data set. That behavior is completely transparent and can be modified using the "Settings" menu item under the "Fingerbank"section of the A3 "Configuration" tab.

Local Entries

It is possible for an administrator who wants to customize an existing record (or create a new one) to do so using the "Local" entries. An upstream record (DHCP Fingerprint, DHCP Vendor, MAC Vendor, User Agent, Device type, even a Combination) can be cloned and then modified on a local basis if needed. Local records are always matched first since their purpose is to override an existing one. A local combination can be created to match either "Local" or "Upstream" or both entries to allow identification of a device.

Settings

Fingerbank settings can easily be modified from the "Settings" menu item under the "Fingerbank" section of the A3 "Configuration" tab. There’s documentation for each an every parameter that allow easier understanding.

Regex Syslog Parser

You are now able to create syslog parser using regex. This will allow you complex filters and rules to work on data receive via syslog.

Configuring a Regex Syslog Parser

• Enabled - You can enable/disable the parser from running
• Alert Pipe - A previously created alert pipe (FIFO)
• Rules - The list of rules that defines how to match log file entries and what action(s) to take when matching

Regex Syslog Parser Rule

• Name - The name of the rule
• Regex - The regex to match against a log entry. The regex may have named captures which can be used for parameter replacement start a $.
• Actions - A list of actions to take when the regex matches
• IP to MAC - Perform automatic translation of IPs to MACs and the other way around
• Last if matches - Stop processing the other rules if this rule matched

Defining Actions

An action has two parts

• method - The name of the action you want to take
• parameter list - The list of parameters you want to provide to the method. Each parameter is seperated by a comma. The parameters that are to be replaced by a named capture.

Example Action

Regex -

Action -

Suricata IDS

A3 already contains a syslog parser for Suricata. This is an example to raise a violation from a syslog alert on the Suricata SID.

The first step is to create the syslog regex parser and then create the violation.

Syslog regex parser configuration

To create the syslog regex parser you will need to go to Configuration → Integration → Syslog Parsers → Add a Syslog Parser → regex

Here is the configuration of the syslog regex parser:

Save the regex rule.

You can directly test your rule. In the previous example the parser expect a syslog string like this:

In order to have a correct match in the rule, you will need to have a valid iplog entry in the database. Put the string in the test box and then click on the RUN TEST button, you should get:

• ET P2P Kaaza Media desktop p2pnetworking.exe : trigger_violation(mac, 00:11:22:33:44:55, tid, 2000340, type, detect)

We can see that A3 will execute the violation on the MAC address 00:11:22:33:44:55.

Violation Creation

Now you will need to create the violation with the trigger id 2000340 in order to isolate the device. In order to do so, go to Configuration → Compliance → Violation → ADD VIOLATION

Definition:

Triggers:

• Click on the + button
• Look for detect in the dropdown list
• Add the trigger ID: 2000340 and click the ADD button
• Click on the < button next to Select Some Options

Remediation:

Click on the SAVE button.

Now you will need to restart the pfqueue and the pfdetect services.

Make sure that you have your pipe file otherwise the process won’t start.

Security Onion

Installation and Configuration

Security Onion is a Ubuntu-based security suite. The latest installation instructions are available directly from the Security Onion website, https://github.com/Security-Onion-Solutions/security-onion/wiki/Installation

Since a security suite consists of multiple pieces of software tied together, you may be prompted for different options during the installation process. A detailed "Production Deployment" guide can also be found directly from the Security Onion website: https://github.com/Security-Onion-Solutions/security-onion/wiki/ProductionDeployment

A3 Integration

Once Security Onion is installed and minimally configured, integration with A3 is required to be able to raise violations based on sensor(s) alerts. syslog is used to forward sensor(s) alerts from Security Onion to the A3 detection mechanisms.

The simplest way is as follow (based on https://github.com/Security-Onion-Solutions/security-onion/wiki/ThirdPartyIntegration);

On the Security Onion server:

• Must be done on the master server running sguild.

Configure /etc/syslog-ng/syslog-ng.conf by adding the following to enable sending sguild log entries to A3:

Sending sguild alert output to syslog requires DEBUG to be changed from 1 to 2 under /etc/sguild/sguild.conf

A restart of the sguild daemon is then required

A restart of the syslog-ng daemon is then required

On the A3 server:

Modify rsyslog configuration to allow incoming UDP packets by uncommenting the following two lines in /etc/rsyslog.conf:

Configure /etc/rsyslog.d/securityonion_ids.conf so it contains the following which will redirect Security Onion sguild log entries and stop further processing of current matched message:

Make sure the receiving alert pipe (FIFO) exists

Restart the rsyslog daemon

At this point, Security Onion should be able to send detected alerts log entries to A3.

A configuration of a new syslog parser as well as some violations are the only remaining steps to make full usage of the Security Onion IDS integration.

Configuration of a new syslog parser should use the followings:

Configuration of a new violation can use the following trigger types:

ERSPAN

ERSPAN permits to mirror a local port traffic (low bandwidth) to a remote IP, E.G: your Security Onion already deployed box. ERSPAN encapsulates port traffic into ERSPAN then GRE and send that traffic to one/multiple destination(s). ERSPAN is a Cisco technology which is available only on some platforms, including: Catalyst 6500, 7600, Nexus, and ASR 1000.

One way of accessing encapsulated traffic at the destination host is through a software called RCDCAP, which is a daemon that creates a virtual interface if not existing, on which both GRE and ERSPAN headers are decapsulated prior to the traffic being injected to the previous interface. Security Onion can then feed on that interface like it would on any other, and if the RCDCAP daemon dies, continue to listen to that interface even though decapsulated traffic won’t be available anymore.

Assumptions for the example:

The switch is at IP 172.16.0.1, the monitored switch port is GigabitEthernet0/10 and the Security Onion monitoring destination IP is 10.10.10.10 on eth2, eth2 ideally being a dedicated interface.

On Security Onion:

• Enable Inverse repository for Security Onion:

• Install RCDCAP

• Modify network file (/etc/network/inferfaces) so that eth2 has an IP and a proper MTU. Decapsulated traffic will be injected on mon1. Make sure that the configuration is similar to the following:

• Rerun Security Onion wizard and make sure to skip network configuration step. Make sure that mon1 is selected for monitoring purposes, note that eth2 doesn’t need to.

On the Switch:

StreamScan Comprimise Detection System (CDS)

This is an example to raise a violation from a syslog alert on a StreamScan alert ID.

The first step is to create the syslog regex parser and then create the violation.

Syslog regex parser configuration

To create the syslog regex parser you will need to go to Configuration → Integration → Syslog Parsers → Add a Syslog Parser → regex

Here is the configuration of the syslog regex parser:

Save the regex rule.

You can directly test your rule. In the previous example the parser expect a syslog string like this:

In order to have a correct match in the rule, you will need to have a valid iplog entry in the database. Put the string in the test box and then click on the RUN TEST button, you should get:

- violation : trigger_violation('mac', '00:11:22:33:44:55', 'tid', '2022985', 'type', 'detect')

We can see that A3 will execute the violation on the MAC address 00:11:22:33:44:55.

Violation creation

Now you will need to create the violation with the trigger id 2000340 in order to isolate the device. In order to do so, go to Configuration → Compliance → Violation → ADD VIOLATION

Definition:

Triggers:

• Click on the + button
• Look for detect in the dropdown list
• Add the trigger ID: 2022985 and click the ADD button
• Click on the < button next to Select Some Options

Remediation:

Click on the SAVE button.

Now you will need to restart the pfqueue and the pfdetect services.

Make sure that you have your pipe file otherwise the process won’t start.

Rsyslog Configuration

You will need to create a rsyslog configuration to forward all the syslog messages sent by StreamScan to the pipe file /usr/local/A3/var/cds

First you need to enable the syslog under the rsyslog configuration file located at /etc/rsyslog.conf, uncomment the two parameters:

Then create the forwarding configuration:

Put the follow configuration in it where the IP 1.2.3.4 is your syslog source server:

Restart rsyslog to apply the configuration

A3 is able to update some firewall based on device information, like the IP address, the username connected on it. (Look for integration guides to see how you can configure your firewall with A3)

By default A3 uses the DHCP traffic to trigger an update on the firewall but it’s also possible to do it with the RADIUS accounting traffic.

In order to manage the way you want to update the firewall, go in Configuration → System Config → Main Configuration → Advanced, then there are two choices,

Trigger Single-Sign-On on dhcp and Trigger Single-Sign-On on accounting.

You can use both methods at the same time but this will result in duplicate SSO requests if you receive the DHCP and accounting of the same device which can cause unexpected load on your firewall.

Barracuda

Content to come.

Checkpoint

Content to come.

FortiGate

Content to come.

JSON-RPC

Content to come.

Palo Alto

Content to come.

A3 supports either Nessus, OpenVAS and WMI as a scanning engine for compliance checks.

Since A3 v5.1 you are now able to create multiples scan engines configuration and assign them on specific captive portals.

It mean per example that you are now able to active a scan for specific Operating System only on a specific SSID.

Installation

Nessus

Please visit https://www.tenable.com/downloads/nessus to download Nessus v7 and install the Nessus package for your operating system. You will also need to register for the HomeFeed (or the ProfessionalFeed) in order to get the plugins.

After you installed Nessus, follow the Nessus documentation for the configuration of the Nessus Server, and to create a user for A3.

• You may run into some issue while using Nessus with the Net::Nessus::XMLRPC module (which is the default behavior in A3). Please refer to the bug tracking system for more information.

OpenVAS

Please visit http://www.openvas.org/install-packages.html#openvas4_centos_atomic to configure the correct repository to be able to install the latest OpenVAS scanning engine.

Once installed, please make sure to follow the instructions to correctly configure the scanning engine and create a scan configuration that will fit your needs. You’ll also need to create a user for A3 to be able to communicate with the server.

It is important to get the correct scan config ID and NBE report format ID to populate the parameters in the A3 configuration file. The easiest way to get these IDs is by downloading both of the scan configuration and report format from the OpenVAS web gui and retrieve the IDs in the filenames.

For example report-format-f5c2a364-47d2-4700-b21d-0a7693daddab.xml gives report format ID f5c2a364-47d2-4700-b21d-0a7693daddab.

WMI

You just have to enable WMI on each Micrsofot Windows devices with a GPO from Active Directory.

Configuration

In order for the compliance checks to correctly work with A3 (communication and generate violations inside A3), you need to configure these sections:

Scanner Definition

First go in Configuration and Scanner Definition: Configuration→Compliance→Scans Engines

Then add a scan:

There are common parameters for each scan engines:

Specific to Nessus:

Specific to OpenVAS:

Specific to WMI:

WMI Rules Definition

If you have configured a WMI scan engine then you need to define WMI Rules.

WMI is a sort of database on each windows devices, to retrieve information on the device you need to know the sql request.

In order to help you to find and make a rule you can use a third party tool like WMI Explorer.

Go in configuration → WMI Rules Definition:

There are already 3 rules defined:

Let’s take the Software_Installed rule:

This rule will do the following:

• retrieve all the installed software on the device and test if the attribute Caption contain Google.
• if it matched then we will trigger a violation (with the trigger internal::888888) for the mac address of the device.

The second one, logged_user:

This rule will do the following:

• retrieve the current logged user on the device and register the device based on the user account.

The last one, Process_Running:

This rule will do the following:

• retrieve all the running process on the device and if one match explorer.exe then we bypass the scan.

Rules syntax

• the syntax of the rules are simple to understand:
• the request is the sql request you will launch on the remote device, you must know what the request will return to write the test.
• Inside the Rules Actions we define 2 sorts of blocs:
  • The test bloc (ie [explorer]) and the action bloc (ie [1:explorer])
• The test bloc is a simple test based on the result of the request:
  • - attribute is the attribute you want to test
  • - operator can be:
    • is
    • is_not
    • match
    • match_not
  • - value is the value you want to compare
• You can define multiples test blocs
• The action bloc is where you will define your logic, per example let's take this one [1:google&explorer], this mean that if the google test is true and explorer is true then we execute the action.
• The logic can be more complex and can be something like that [1:!google|(explorer&memory)] that mean if not google or (explorer and memory)

WMI tab

It is possible to have the result of a WMI scan in the node section. To have this, go into the rule configuration and check the box On Node tab. Now configure your WMI scanner as you would usually do and you will be able to have the results in the tab WMI Rules under Node.

Violations Definition

You need to create a new violation section and have to specify:

Using Nessus:

Using OpenVAS:

Where violationId is either the ID of the Nessus plugin or the OID of the OpenVAS plugin to check for. Once you have finished the configuration, you need to reload the violation related database contents using:

• Violations will trigger if the plugin is higher than a low severity vulnerability.

Assign Scan definition to connection profiles

The last step is to assign one or more scanner you configured to one or more connection profiles.

Go in Configuration → Policies and Access Control → Connection Profiles → Edit a Profile → Add Scan

Hosting Nessus / OpenVAS remotely

Because of the CPU intensive nature of an automated vulnerability assessment, we recommend that it is hosted on a separate server for large environments. To do so, a couple of things are required:

• A3 needs to be able to communicate to the server on the port specified by the vulnerability engine used
• The scanning server need to be able to access the targets. In other words, registration VLAN access is required if scan on registration is enabled.

If you are using the OpenVAS scanning engine:

• The scanning server need to be able to reach A3’s Admin interface (on port 1443 by default) by its DNS entry. Otherwise A3 won’t be notified of completed scans.
• You must have a valid SSL certificate on your A3 server

If you are using the Nessus scanning engine:

• You just have to change the host value by the Nessus server IP.

A3 Apple, Android and Windows Wireless Provisioning

Provisioners allow devices to automatically configure themselves to connect to the proper SSID (if applicable), use the proper authentication method (e.g. EAP-TLS) and trust the CA certificate and any certificate signed by it.

Apple devices such as iPhones, iPads, iPods and Mac OS X (10.7+) support wireless profile importation using a special XML file format (mobileconfig). Android is also able to support this feature by importing the wireless profile with the Android A3 Agent. In fact, installing such file on your Apple device will automatically configure the wireless settings for a given SSID. This feature is often used when the SSID is hidden, and you want to ease the configuration steps on the mobile device (because it is often painful to configure manually). In A3, we are going further, we generate the profile according to the administrator’s preference and we pre-populate the file with the user’s credentials (without the password). The user simply needs to install its generated file and he will be able to use the new SSID.

The Windows agent will import and apply the provisioned profile so that the user only needs to enter his username and password.

Configure the feature

• If EAP-TLS provisioning is desired, you have to configure a PKI before going any further. Two guides exists to assist you: A3 PKI Quick Install Guide, which covers A3’s implementation, or A3 MSPKI Quick Install Guide which covers Microsoft’s.

First of all, you need to configure the SSID that your devices will use after they go through the authentication process.

In the administration interface, go in Advanced Access Configuration → Provisioners. Then select android / ios / Windows provisioner. Enter the SSID information and roles for which the provisioner applies. Repeat for all desired provisioners. Note that the default RADIUS certificate path is /usr/local/A3/raddb/certs/server.crt.

After, you simply need to add the Android, iOS and Windows provisioners to your Connection Profile configuration.

To add a new provisioner for another class of devices to be supported, click on the Add Provisioner button, and fill out the form, choosing a different Provisioning ID per provisioner.

• Roles: The "Roles" field defines which devices will be affected by the provisioning item. If empty, all devices for this class will be affected.
• SSID: The "SSID" field defines which SSID will be configured on the device using the authentication profile.
• EAP-Type: The EAP type defines the authentication method supported and should be set to EAP-TLS to integrate with the A3 PKI.
• Security type: The security type should be set to WPA2-Entreprise to integrate with the A3 PKI.
• PKI Provider: This should match the provider you configured in the PKI provider section.

We also advise you to configure a SSID for provisioning, for instance: OnBoarding-PF, open with MAC Authentication, pointing to A3. Create a new Portal Profile, add a filter SSID with this SSID name, add the source you want the users to authenticate from and add your provisioners to this Portal Profile. From there, users who logged in will have to follow the captive portal instruction to get provided their certificate.

Android specifications

For Android provisioning support, you must activate and adjust the passthroughs. You might need to adapt them depending on your geolocality. Please refer to the Passthroughs section of this guide if needed.

In the administation inferface, go in Network Configuration → Fencing. Activate Passthrough and make sure the following passthrough are present:

Then run the following commands so that passthroughs become effective:

iOS specifications

Mac OS X/iOS require the provisioning profile to be signed if you want to remove the untrusted warning when installing the profile. For more information, please refer to the PKI guides referred earlier in Configure the feature above.

Other Corporate Devices

Let’s say that you now need to add some Linux computers as corporate devices.

Those devices cannot be authenticated via Machine Authentication, so we will need to use EAP-TLS and provide those devices with a certificate.

First of all make sure that your RADIUS certificate from the A3 server and the certificates that you will be provided are delivered from the same CA, else your authentication will not work. To enable EAP-TLS you will need to reconfigure the new RADIUS server certificate in the file conf/radiusd/eap.conf.

While creating the RADIUS server certifcate make sure to have the Extended key usage: servAuth.

Under the section tls-config tls-common, search for ‘private_key_file’, ‘certificate_file’ and ‘ca_file’. Those should contain respectively the path of:

• the private key for your A3 server,
• the server certificate issued by your CA for your A3 server,
• the public key of your CA.

If you have an OCSP capable PKI you can configure it in the section OSCP in the eap.conf file.

Lastely you will need to restart RADIUS to ensure the use of the new configuration and certificates. Please do the following:

• bin/pfcmd configreload hard
• bin/pfcmd service radiusd restart

Make sure everything happens without errors.

Now that your RADIUS is ready to handle EAP-TLS, configure your SSID connection profile on the corporate device using this method. Generate a client certificate for your device and install it on.

Please configure an EAPTLS source which can be found while adding a new sources under Internal->, simply give it a name, a description and a catch-all rule. This will allow you to validate the authentication via EAP-TLS.

You can now create a new Portal Profile for EAP-TLS. Under the tab configuration, section Policies and Access Control->Connection Profiles, Add profile and select as a filter the Sub Connection Type as EAP-TLS, add your source EAP-TLS. Check the box "Automatically register devices".

You now have a full flow working for your corporate devices.

The following is an example on how to configure an EAP-TLS connection for Windows/Android/Mac OS X/iOS

Mac OS X/iOS require the provisioning profile to be signed if you want to remove the untrusted warning when installing the profile. You need to sign it with a Certification Authority already trusted by the device such as e.g. VeriSign. Configuring this has to be done in the Signing tab in the "Apple devices".

Fill out the fields with the contents of the Base64 encoded certificates.

To extract this information from a pem formatted certificate, copy the file content included between the begin and end tag, not including the delimiters themselves.

Certificate file example:

Copy everything between the BEGIN and END lines, but not the lines themselves.

Repeat this operation for the certificate key and intermediate certificate.

Profile generation

Upon registration, instead of showing the default release page, the user will be showing another version of the page saying that the wireless profile has been generated with a clickable link on it. To install the profile, Apple user owner simply need to click on that link, and follow the instructions on their device. Android user owner simply click to the link and will be forwarded to Google Play to install A3 agent. Simply launch the application and click to configure will create the secure SSID profile. It is that simple.

MobileIron

Content to come.

OPSWAT

Content to come.

SentinelOne

Content to come.

Symantec SEPM

Content to come.

Microsoft PKI

Content to come.

A3 PKI

Content to come.

RHEL7 systemd early swapoff bug mitigation

A known bug is still present in systemd-219-30.el7_3.7.x86_64 shipped with CentOS. (Debian fixed it in 228-3).

The bug arises because not all swap aliases are registered, which results in an incorrect dependence tree which results in swapoff being called way too early at shutdown.

Workaround

Obtain the list of swap items that should be considered by systemd for it to enforce a correct ordering:

In our example, that gave the following output:

Create /etc/systemd/system/swap.target and fill it with all swap aliases obtained from the previous command:

IPTables

IPTables is now entirely managed by A3. However, if you need to perform some custom rules, you can modify conf/iptables.conf to your own needs. However, the default template should work for most users.

Log Rotations

A3 can generate a lot of log entries in huge production environments. This is why we recommend to use logrotate to periodically rotate your logs. A working logrotate script is provided with the A3 package. This script is located under the /usr/local/A3/A3.logrotate file, and it’s configured to do a daily log rotation and keeping old logs with compression. It has been added during A3 initial installation.

NTLM Authentication Caching

This section assumes that you already have an Active Directory domain configuration both in Configuration→Policies and Access Control→Domains→Active Directory Domains and Configuration→Policies and Access Control→Sources. If you don’t, you need to first configure those. Refer to the appropriate sections of this guide for details on how to configure those two components.

• The cache requires minimally Windows Server 2008. Older versions will not work.

When using NTLM authentication against an Active Directory for 802.1X EAP-PEAP connections, this can become a bottleneck when handling dozens of authentications per seconds.

To overcome this limitation, it is possible to use a Redis driven cache inside A3 to reduce the amount of authentications requiring an external NTLM authentication call. Should a user be in the cache, A3 will attempt to compare the 802.1X credentials with those. In the even that the validation fails, a call to ntlm_auth is made. In the event of a cache miss, an ntlm_auth call is made as well. This ensures that even if a user changes his password, his new password is immediately valid for 802.1X EAP-PEAP connections even if the cache contains the outdated entry.

• The NTLM cache doesn’t cache clear text passwords, it caches the NT hash of the user password.

Additional Packages

In order to use this cache, you will need to install additional packages available from the A3-extra repository. These packages will allow A3 to query your Active Directory for the NT hash of the users.

CentOS:

Debian:

A3 Configuration

First of all, you will need to enable the NTLM caching globally by enabling NTLM Redis cache in Configuration→System Configuration→Main Configuration→Advanced. You then need to restart radiusd.

Once that is done, you need to configure A3 to start caching the credentials. In order to do so, go in Configuration→Policies and Access Control→Domains→Active Directory Domains and select the domain you want to cache the credentials for.

Next, go in the NTLM cache tab and:

• Enable NTLM cache
• Select the Active Directory authentication source that is tied to this domain.
• Adjust the LDAP filter if necessary. Note that this is only used for the batch job.
• Adjust the Expiration
• Enable NTLM cache background job and/or NTLM cache on connection. In the case of this example, both will be enabled.

Once done, click Save to commit your changes.

After that, you will need to enable the redis_ntlm_cache service which is used by A3 to store the cached credentials. In order to do so, go in Configuration→Main Configuration→Services' and enable redis_ntlm_cache and save the changes.

Next, start the service via pfcmd:

If you chose to enable NTLM cache background job in one of your domains, you will need to enable the pfmon job that will periodically cache the credentials. This can be configured in Configuration→System Configuration→Main Configuration→Maintenance→populate_ntlm_redis_cache. It is advised to set the interval of this task to half the expiration of the credentials you have set in the domain configuration. This will ensure you have an optimal cache hit. Once done, restart the pfmon service.

Active Directory configuration

In order for A3 to be able to fetch the NTLM credentials from your Active Directory, it will need a user who has replication rights. The user to which you have to grant the rights, is the one that is configured in the authentication source that you associated in the NTLM cache section of your domain.

Please refer to the following Microsoft KB entry to configure the replication rights: https://support.microsoft.com/en-us/kb/303972

SNMP Traps Limit

A3 mainly rely on SNMP traps to communicate with equipment. Due to the fact that traps coming in from approved (configured) devices are all processed by the daemon, it is possible for someone who want to generate a certain load on the A3 server to force the generation of non-legitimate SNMP traps or a switch can randomly generate a high quantity of traps sent to A3 for an unknown reason.

Because of that, it is possible to limit the number of SNMP traps coming in from a single switch port and take action if that limit is reached. For example, if over 100 traps are received by A3 from the same switch port in a minute, the switch port will be shut and a notification email will be sent.

Here’s the default config for the SNMP traps limit feature. As you can see, by default, A3 will log the abnormal activity after 100 traps from the same switch port in a minute. These configurations are in the conf/pf.conf file:

Alternatively, you can configure these parameters from the A3 Web administrative GUI, in the Configuration → Network Configuration → SNMP section.

MySQL optimizations

Tuning MySQL

If you’re A3 system is acting very slow, this could be due to your MySQL configuration. You should do the following to tune performance:

Check the system load

Check iostat and CPU

As you can see, the load is 1.25 and IOWait is peaking at 20% - this is not good. If your IO wait is low but your MySQL is taking +%50 CPU this is also not good. Check your MySQL install for the following variables:

A3 relies heavily on InnoDB, so you should increase the buffer_pool size from the default values.

Go in the administration GUI , in Configuration → System Configuration → Database → Advanced and raise the value of "InnoDB buffer pool size".

Then restart packetfence-mariadb

Wait 10 minutes re-check iostat and CPU

MySQL Optimization Tool

We recommend that you run the MySQL Tuner on your database setup after a couple of weeks to help you identify MySQL configuration improvement. The tool is bundled with A3 and can be run from the command-line:

Keeping Tables Small

Over time, some of the tables will grow large and this will drag down performance (this is especially true on a wireless setup).

One such table is the locationlog table. We recommend that closed entries in this table be moved to the archive table locationlog_archive after some time. A closed record is one where the end_time field is set to a date (strictly speaking it is when end_time is not null and not equals to 0).

We provide a script called database-backup-and-maintenance.sh located in addons/ that performs this cleanup in addition to optimize tables on Sunday and daily backups.

Avoid "Too many connections" problems

In a wireless context, there tends to be a lot of connections made to the database by our freeradius module. The default MySQL value tend to be low (100) so we encourage you to increase that value to at least 300. See http://dev.mysql.com/doc/refman/5.0/en/too-many-connections.html for details.

Avoid "Host <hostname> is blocked" problems

In a wireless context, there tend to be a lot of connections made to the database by our freeradius module. When the server is loaded, these connection attempts can timeout. If a connection times out during connection, MySQL will consider this a connection error and after 10 of these (by default) he will lock the host out with a:

This will grind A3 to a halt so you want to avoid that at all cost. One way to do so is to increase the number of maximum connections (see above), to periodically flush hosts or to allow more connection errors. See http://dev.mysql.com/doc/refman/5.0/en/blocked-host.html for details.

Using Percona XtraBackup

When dealing with a large database, the database backup and maintenance script (/usr/local/A3/addons/database-backup-and-maintenance.sh) which uses mysqldump may create a long lock on your database which may cause service to hang.

This is fixed easily by using Percona XtraBackup which can complete a full database backup without locking your tables.

The installation instructions below are made for CentOS 7 but adjusting them to Debian should only be a matter of installing the proper packages for your MySQL/MariaDB version.

First install the Percona repository:

Make sure to disable the newly installed repository not to interfere with future updates:

Next, install Percona XtraBackup by manually specifying the Percona repository:

Once this is done, grant the proper rights to the pf user (or the one you configured in pf.conf):

Next, run the maintenance script /usr/local/A3/addons/database-backup-and-maintenance.sh and ensure that the following line is part of the output:

If the backup fails, check /usr/local/A3/logs/innobackup.log for details and refer to the Percona XtraBackup documentation for troubleshooting.

• In the event that you want to stop using Percona XtraBackups for your MySQL backups, simply uninstall it and the database script will fallback to mysqldump.

Captive Portal Optimizations

Avoid captive portal overload due to non-browser HTTP requests

By default we allow every query to be redirected and reach A3 for the captive portal operation. In a lot of cases, this means that a lot of non-user initiated queries reach A3 and waste its resources for nothing since they are not from browsers. (iTunes, Windows update, MSN Messenger, Google Desktop, …​).

Since version 4.3 of A3, you can define HTTP filters for Apache from the configuration of A3.

Some rules have been enabled by default, like one to reject requests with no defined user agent. All rules, including some examples, are defined in the configuration file apache_filters.conf.

Filters are defined with at least two blocks. First are the tests. For example:

The last block defines the relationship between the tests and the desired action. For example:

This filter will return an error code (501) if the user agent is Dalvik and the URI doesn’t contain _/generate_204.

Dashboard Optimizations (statistics collection)

The collection and aggregation of statistics in the whisper database can be I/O intensive per moment. This means that it can be beneficial to separate them on another disk even if it is a virtual disk that will share the same underlying physical disk.

First, add a disk in your virtual machine or bare metal server and reboot (this example will use /dev/sdb as the new device.

Make sure A3 is stopped:

Create an ext4 partition:

Then move the old databases to a backup point:

Mount your new disk and check that it is mounted:

Apply the proper user rights and restore your database from your backup

Start A3 and make sure your stats are still there and being collected properly. Then remove the backup you made rm -fr /usr/local/A3/var/graphite.bak/.

Troubleshooting

This section will address specific problems and known solutions.

"Internet Explorer cannot display the webpage"

Problem: Internet Explorer 8-10 may raise an "Internet Explorer cannot display the webpage" error while attempting to access A3 administration interface because TLSv1.2 is not activated but required since A3 7.

Solution:

• A3 administration interface is not started:

• It is strongly advised that you update your browser to Internet Explorer 11 or download an alternative.
• TLSv1.2 needs to be activated manually in Internet Explorer 8-10.
• Within Internet Explorer: click Tools, Internet Options, Advanced and make sure that TLS v1.2 is enabled under the security section. Retry.

Floating Network Devices

A3 supports floating network devices. A Floating network device is a device for which A3 has a different behavior compared to a regular device. This functionality was originally added to support mobile Access Points.

• Right now A3 only supports floating network devices on Cisco and Nortel switches configured with port-security.

For a regular device, A3 put it in the VLAN corresponding to its status (Registration, Quarantine or Regular VLAN) and authorizes it on the port (port-security).

A floating network device is a device that A3 does not manage as a regular device.

When a floating network device is plugged, A3 will let/allow all the MAC addresses that will be connected to this device (or appear on the port) and if necessary, configure the port as multi-vlan (trunk) and set PVID and tagged VLANs on the port.

When an floating network device is unplugged, A3 will reconfigure the port like before it was plugged.

How it works

Configuration:

• floating network devices have to be identified using their MAC address.
• linkup/linkdown traps are not enabled on the switches, only port-security traps are.

When A3 receives a port-security trap for a floating network device, it changes the port configuration so that:

• it disables port-security
• it sets the PVID
• it eventually sets the port as multi-vlan (trunk) and sets the tagged Vlans
• it enables linkdown traps

When PF receives a linkdown trap on a port in which a floating network device was plugged, it changes the port configuration so that:

• it enables port-security
• it disables linkdown traps

Identification

As we mentioned earlier, each floating network device has to be identified. There are two ways to do it:

by editing conf/floating_network_device.conf

through the Web GUI, in Configuration → Network Configuration → Floating Device

Here are the settings that are available:

• MAC Address: MAC address of the floating device
• IP Address: IP address of the floating device (not required, for information only)
• trunkPort: Yes/no. Should the port be configured as a multi-vlan port?
• pvid: VLAN in which A3 should put the port
• taggedVlan: Comma separated list of VLANs. If the port is a multi-vlan, these are the Vlans that have to be tagged on the port.

Production DHCP access

In order to perform all of its access control duties, A3 needs to be able to map MAC addresses into IP addresses.

For all the networks/VLANs where you want A3 to have the ability to isolate a node or to have IP information about nodes, you will need to perform one of the techniques below.

Also note that this doesn’t need to be done for the registration, isolation VLANs and inline interfaces since A3 acts as the DHCP server in these networks.

IP Helpers

If you are already using IP Helpers for your production DHCP in your production VLANs this approach is the simplest one and the one that works the best.

Add A3’s management IP address as the last ip helper-address statement in your network equipment. At this point A3 will receive a copy of all DHCP requests for that VLAN and will record what IP were distributed to what node using a pfdhcplistener daemon.

By default no DHCP Server should be running on that interface where you are sending the requests. This is by design otherwise A3 would reply to the DHCP requests which would be a bad thing.

Obtain a copy of the DHCP traffic

Get a copy of all the DHCP Traffic to a dedicated physical interface in the A3 server and run pfdhcplistener on that interface. It will involve configuring your switch properly to perform port mirroring (aka network span) and adding in A3 the proper interface statement at the operating system level and in pf.conf.

/etc/sysconfig/network-scripts/ifcfg-eth2:

Add to pf.conf: (IPs are not important they are there only so that A3 will start)

Restart A3 and you should be good to go.

Interface in every VLAN

Because DHCP traffic is broadcast traffic, an alternative for small networks with few local VLANs is to put a VLAN interface for every VLAN on the A3 server and have a pfdhcplistener listen on that VLAN interface.

On the network side you need to make sure that the VLAN truly reaches all the way from your client to your DHCP infrastructure up to the A3 server.

On the A3 side, first you need an operating system VLAN interface like the one below. Stored in /etc/sysconfig/network-scripts/ifcfg-eth0.1010:

Then you need to specify in pf.conf that you are interested in that VLAN’s DHCP by setting type to dhcp-listener.

Repeat the above for all your production VLANs then restart A3.

Host production DHCP on A3

It’s an option. Just modify conf/dhcpd.conf so that it will host your production DHCP properly and make sure that a pfdhcplistener runs on the same interface where production DHCP runs. However, please note that this is NOT recommended. See this ticket to see why.

Routed Networks

If your isolation and registration networks are not locally-reachable (at layer 2) on the network, but routed to the A3 server, you’ll have to let the A3 server know this. A3 can even provide DHCP and DNS in these routed networks and provides an easy to use configuration interface.

For dhcpd, make sure that the clients DHCP requests are correctly forwarded (IP Helpers in the remote routers) to the A3 server. Then make sure you followed the instructions in the DHCP and DNS Server Configuration (networks.conf) for your locally accessible network.

If we consider the network architecture illustrated in the above schema, conf/pf.conf will include the local registration and isolation interfaces only.

• A3 will not start unless you have at least one internal interface, so you need to create local registration and isolation VLANs even if you don’t intend to use them. Also, the internal interfaces are the only ones on which dhcpd listens, so the remote registration and isolation subnets need to point their DHCP helper-address to those particular IPs.

Then you need to provide the routed networks information to A3. You can do it through the GUI in Administration → Networks (or in conf/networks.conf).

conf/networks.conf will look like this:

DHCP clients on the registration and isolation networks receive the PF server IP as their DNS server (dns=x.x.x.x), and PF spoofs DNS responses to force clients via the portal. However, clients could manually configure their DNS settings to escape the portal. To prevent this you will need to apply an ACL on the access router nearest the clients, permitting access only to the PF server and local DHCP broadcast traffic.

For example, for the VLAN 20 remote registration network:

If your edge switches support vlan-isolation you can also apply the ACL there. This has the advantage of preventing machines in isolation from attempting to attack each other.

Network Devices Definition (switches.conf)

This section applies only for VLAN enforcement. Users planning to do inline enforcement only can skip this section.

A3 needs to know which switches, access points or controllers it manages, their type and configuration. All this information is stored in /usr/local/A3/conf/switches.conf. You can modify the configuration directly in the switches.conf file or you can do it from the Web Administration panel under Configuration → Policies and Access Control → Switches - which is now the preferred way.

The /usr/local/A3/conf/switches.conf configuration file contains a default section including:

• Default SNMP read/write communities for the switches
• Default working mode (see the note below about possible working modes)

and a switch section for each switch (managed by A3) including:

• Switch IP/Mac/Range
• Switch vendor/type
• Switch uplink ports (trunks and non-managed IfIndex)
• per-switch re-definition of the VLANs (if required)
• switches.conf is loaded at startup. A reload is required when changes are manually made to this file /usr/local/A3/bin/pfcmd configreload.

Import from CSV

From A3 7.3 and onwards, you have the possibility to import switches from a CSV file.

The CSV must look like: "description, IP or MAC, switch group". The first line will be skipped. If an entry with one provided IP/MAC already exist it will not be added. You MUST create switches group before.

Working modes

There are three different working modes for a switch in A3:

• Testing: pfsetvlan writes in the log files what it would normally do, but it doesn’t do anything.
• Registration: pfsetvlan automatically-register all MAC addresses seen on the switch ports. As in testing mode, no VLAN changes are done.
• Production: pfsetvlan sends the SNMP writes to change the VLAN on the switch ports.

RADIUS

To set the RADIUS secret, set it from the Web administrative interface when adding a switch. Alternatively, edit the switch config file (/usr/local/A3/conf/switches.conf) and set the following parameters:

Moreover, the RADIUS secret is required to support the RADIUS Dynamic Authentication (Change of authorization or Disconnect) as defined in RFC3576.

SNMP v1, v2c and v3

A3 uses SNMP to communicate with most switches. A3 also supports SNMP v3. You can use SNMP v3 for communication in both directions: from the switch to A3 and from A3 to the switch. SNMP usage is discouraged, you should now use RADIUS. However, even if RADIUS is being used, some switches might also require SNMP to be configured to work properly with A3.

From A3 to a switch

Edit the switch config file (/usr/local/A3/conf/switches.conf) and set the following parameters:

From a switch to A3

Edit the switch config file (/usr/local/A3/conf/switches.conf) and set the following parameters:

Switch Configuration

Here is a switch configuration example in order to enable SNMP v3 in both directions on a Cisco Switch.

Command-Line Interface: Telnet and SSH

• Privilege detection is disabled in the current A3 version due to some issues (see #1370). So make sure that the cliUser and cliPwd you provide always get you into a privileged mode (except for Trapeze hardware).

A3 needs sometimes to establish an interactive command-line session with a switch. This can be done using Telnet. You can also use SSH. In order to do so, edit the switch configuration file (/usr/local/A3/conf/switches.conf) and set the following parameters:

It can also be done through the Web Administration Interface under Configuration → Policies and Access Control → Switches.

Web Services Interface

A3 sometimes needs to establish a dialog with the Web Services capabilities of a switch. In order to do so, edit the switch config file (/usr/local/A3/conf/switches.conf) and set the following parameters:

It can also be done through the Web Administration Interface under Configuration → Policies and Access Control → Switches.

Role-based enforcement support

Some network devices support the assignment of a specific set of rules (firewall or ACLs) to a user. The idea is that these rules can be a lot more accurate to control what a user can or cannot do compared to VLAN which have a larger network management overhead.

A3 supports assigning roles on devices for switches and WiFi controllers that support it. The current role assignment strategy is to assign it along with the VLAN (that may change in the future). A special internal role to external role assignment must be configured in the switch configuration file (/usr/local/A3/conf/switches.conf).

The current format is the following:

And you assign it to the global roles parameter or the per-switch one. For example:

would return the full-access role to the nodes categorized as admin or engineering and the role little-access to nodes categorized as sales. It can also be done through the Web Administration Interface under Configuration → Policies and Access Control → Switches.

Make sure that the roles are properly defined on the network devices prior to assigning roles!

More on VoIP Integration

VoIP has been growing in popularity on enterprise networks. At first sight, the IT administrators think that deploying VoIP with a NAC poses a huge complicated challenge to resolve. In fact, depending of the hardware you have, not really. In this section, we will see why.

CDP and LLDP are your friend

For those of you who are unaware of the existence of CDP or LLDP (or LLDP-MED), I suggest you start reading on this topic. Cisco Discovery Protocol (CDP) is device-discovery protocol that runs on all Cisco-manufactured equipment including routers, access servers, bridges, and switches. Using CDP, a device can advertise its existence to other devices and receive information about other devices on the same LAN or on the remote side of a WAN. In the world of VoIP, CDP is able to determine if the connecting device is an IP Phone or not, and tell the IP Phone to tag its ethernet frame using the configured voice VLAN on the switchport.

On many other vendors, you are likely to find LLDP or LLDP-MED support. Link Layer Discovery Protocol (LLDP) is a vendor-neutral Link Layer protocol in the Internet Protocol Suite used by network devices for advertising their identity, capabilities, and neighbors. Same as CDP, LLDP can tell an IP Phone which VLAN id is the voice VLAN.

VoIP and VLAN assignment techniques

As you already know, A3 supports many VLAN assignment techniques such as port-security, MAC authentication or 802.1X. Let’s see how VoIP is doing with each of those.

Port-security

Using port-security, the VoIP device rely on CDP/LLDP to tag its ethernet frame using the configured voice VLAN on the switch port. After that, we ensure that a security trap is sent from the voice VLAN so that A3 can authorize the mac address on the port. When the PC connects, another security trap will be sent, but from the data VLAN. That way, we will have 1 mac address authorized on the voice VLAN, and 1 on the access VLAN.

• Not all vendors support VoIP on port-security, please refer to the Network Configuration Guide.

MAC Authentication and 802.1X

On Cisco switches, we are looking at the multi-domain configuration. The multi-domain means that we can have one device on the VOICE domain, and one device on the DATA domain. The domain assignment is done using a Cisco Vendor-Specific Attributes (VSA). When the phone connects to the switchport, A3 will respond with the proper VSA only, no RADIUS tunneled attributes. CDP then tells the phone to tag its ethernet frames using the configured voice VLAN on the port. When a PC connects, the RADIUS server will return tunneled attributes, and the switch will place the port in the provided access VLAN.

On other vendor hardware, it is possible to make VoIP work using RADIUS VSAs. When a phone connects to a switchport, A3 needs to return the proper VSA to tell the switch to allow tagged frames from this device. When the PC will connect, we will be able to return standard RADIUS tunnel attributes to the switch, that will be the untagged VLAN.

Again, refer to the Network Configuration Guide to see if VoIP is supported on your switch hardware.

What if CDP/LLDP feature is missing

It is possible that your phone doesn’t support CDP or LLDP. If it’s the case, you are probably looking at the "DHCP way" of provisioning your phone with a voice VLAN. Some models will ask for a specific DHCP option so that the DHCP server can give the phone a voice VLAN id. The phone will then reboot, and tag its ethernet frame using the provided VLAN tag.

In order to make this scenario work with A3, you need to ensure that you tweak the registration and your production DHCP server to provide the DHCP option. You also need to make sure there is a voice VLAN properly configured on the port, and that you auto-register your IP Phones (On the first connect, the phone will be assigned on the registration VLAN).

DHCP Option 82

A3 is able to locate a device on the network even if the switch port is not managed by A3. To use this feature you need to add all the switches in A3 and enable SNMP read (switch and A3 side) and enable DHCP option 82 in Configuration → Network Configuration → Networks → Network. Once enabled, restart the pfdhcplistener and pfmon services.

• pfmon will query via SNMP all the switches to create a map (MAC <→ switch)
• pfdhcplistener will parse the DHCP Option 82 and will use the map to resolve the MAC to the switch and will update the locationlog of the device.

DHCP Remote Sensor

The DHCP remote sensor consists of a lightweight binary that is installed on your production DHCP server in order to replicate the DHCP traffic 1 to 1 to the A3 server. This solution is more reliable than the DHCP relaying since A3 receives a copy of all your DHCP traffic and not only the broadcasted DHCP traffic. Supported DHCP servers are Microsoft DHCP server and CentOS 6 and 7.

These sensors work by capturing the packets at the lowest level possible on your DHCP server and forward them to the A3 management interface

Microsoft DHCP Sensor

DHCP-Forwarder is an optimized version of precedent udp-reflector, which installs easily and only copy DHCPREQUESTS and DHCPACK packets to the destination.

Download the installer here.

It will install WinPCAP, nssm, launch a configurator to ask for interface, IP and port, save the configuration, install and launch DHCP-Forwarder service.

When you will be asked for a host IP and port, specify A3 management IP and 767 as the UDP port.

The project page can be found here.

Linux-based Sensor

First download the RPM on your DHCP server.

CentOS 6 and 7 servers

For CentOS 6:

For CentOS 7:

Now install the sensor:

Compiling the sensor from source on a Linux system

First make sure you have the following packages installed:

• libpcap
• libpcap-devel
• gcc-c++

Get the source code of the sensor:

Configuring the Sensor

Place the following line in /etc/rc.local

• where pcap0 is the pcap interface where your DHCP server listens on. (List them using udp_reflector -l)
• where 192.168.1.5 is the management IP of your A3 server

Start the sensor:

The DHCP traffic should now be reflected on your A3 server.

Active Directory Integration

Deleted Account

Create the script unreg_node_deleted_account.ps1 on the Windows Server with the following content. Make sure to change @IP_A3 to the IP address of your A3 server. You’ll also need to change the username and password as they must match the credentials defined in the Web admin interface under Configuration → Integration → Web Services.

Create the scheduled task based on an event ID

Start → Run → Taskschd.msc

Task Scheduler → Task Scheduler Library → Event Viewer Task → Create Task

General

• Name: A3-Unreg_node-for-deleted-account
• Check: Run whether user is logged on or not
• Check: Run with highest privileges

Triggers → New

• Begin on the task: On an event
• Log: Security
• Source: Microsoft Windows security auditing.
• Event ID: 4726

Actions → New

• Action: Start a program
• Program/script: powershell.exe
• Add arguments (optional): C:\scripts\unreg_node_deleted_account.ps1

Settings:

• At the bottom, select in the list "Run a new instance in parallel" in order to unregister multiple nodes at the same time.

Validate with Ok and give the account who will run this task. (Usually DOMAIN\Administrator)

Disabled Account

Create the script unreg_node_disabled_account.ps1 on the Windows Server with the following content. Make sure to change @IP_A3 to the IP address of your A3 server. You’ll also need to change the username and password as they must match the credentials defined in the Web admin interface under Configuration → Integration → Web Services.

Create the scheduled task based on an event ID

Start → Run → Taskschd.msc

Task Scheduler → Task Scheduler Library → Event Viewer Task → Create Task

General

• Name: A3-Unreg_node-for-disabled-account
• Check: Run whether user is logged on or not
• Check: Run with highest privileges

Triggers → New

• Begin on the task: On an event
• Log: Security
• Source: Microsoft Windows security auditing.
• Event ID: 4725

Actions → New

• Action: Start a program
• Program/script: powershell.exe
• Add arguments (optional): C:\scripts\unreg_node_disabled_account.ps1

Settings:

• At the bottom, select in the list "Run a new instance in parallel"

Validate with Ok and give the account who will run this task. (Usually DOMAIN\Administrator)

Locked Account

Create the script unreg_node_locked_account.ps1 on the Windows Server with the following content. Make sure to change @IP_A3 to the IP address of your A3 server. You’ll also need to change the username and password as they must match the credentials defined in the Web admin interface under Configuration → Integration → Web Services.

Create the scheduled task based on an event ID

Start → Run → Taskschd.msc

Task Scheduler → Task Scheduler Library → Event Viewer Task → Create Task

General

• Name: A3-Unreg_node-for-locked-account
• Check: Run whether user is logged on or not
• Check: Run with highest privileges

Triggers → New

• Begin on the task: On an event
• Log: Security
• Source: Microsoft Windows security auditing.
• Event ID: 4740

Actions → New

• Action: Start a program
• Program/script: powershell.exe
• Add arguments (optional): C:\scripts\unreg_node_locked_account.ps1

Settings:

• At the bottom, select in the list "Run a new instance in parallel"

Validate with Ok and give the account who will run this task. (Usually DOMAIN\Administrator)

Switch Login Access

A3 is able to act as an authentication and authorization service on the port 1815 for granting command-line interface (CLI) access to switches.

A3 currently supports Cisco switches and these must be configured using the following guide: http://www.cisco.com/c/en/us/support/docs/security-vpn/remote-authentication-dial-user-service-radius/116291-configure-freeradius-00.html

From the A3’s web admin interface, you must configure an Admin Access role (Configuration→System Configuration→Admin Access) that contains the action Switches CLI - Read or Switches CLI - Write and assign this role to an internal user or in an Administration rule in an internal source.

Any user that has the ALL administrative role will be able to login into your switches. If you want to provide all A3 administrative access to some users without allowing them to login into the switches, then apply the ALL_PF_ONLY administrative role which will contains all the necessary A3 roles without the switch login.

Cisco Mobility Services Engine (MSE)

This section has been created to give a quick start to configure the Cisco MSE with A3. In the first part we will explain how to use the Cisco MSE in order to present a captive portal based on the localization. Then in the second part we will integrate the device localization in the node view.

Assumptions

• You have at least one server with A3 6.3 or later.
• The A3 management IP will be 192.168.1.5.
• An account has been created on the MSE in order to use RESTful API of the MSE. (Read only for localization , write to create notifications)
• The Cisco MSE IP will be 192.168.1.6.

Portal Based on Localization

Enable httpd.collector service on A3

This service is mandatory and will receive the mse notifications in json format.

To enable this service go in Configuration -> services and tick services.httpd_collector and leave the default order.

Create a Notification

This part can be done directly on the MSE web admin GUI but we include a Perl script in addons/mse-subscribe.pl that will help you to create one using the RESTful API of the MSE.

So let say that you have a username with write permissions on the MSE (mswrite/password) now go in /usr/local/A3/addons then run:

This will create the notification and print out the notifications configured on the MSE.

So now each time a device will enter or leave the specific zone A3 will be notified.

Configure a Portal Filter

In Configuration Policies and Access Control → Connection Profiles → Add profile → Advanced filter specify an advanced filter like that:

And fill the other configuration needed to configure a connection profile then save it.

That’s all, now when a device will hit the captive portal and will be in the specific zone then

it will hit this connection profile.

MSE Tab

This configuration is really simple, you just have to enable and fill the URL, the username and password in Configuration → Integration → Cisco Mobility Service Engine.

So in our example:

Now go in Nodes and click on a MAC address and you will see that a new tab appears, then if you click on it you will be able to retrieve the map and the localization of the device.

This section covers advanced topics in A3. Note that it is also possible to configure A3 manually using its configuration files instead of its Web administrative interface. It is still recommended to use the Web interface.

In any case, the /usr/local/A3/conf/pf.conf file contains the A3 general configuration. For example, this is the place where we inform A3 it will work in VLAN isolation mode.

All the default parameters and their descriptions are stored in /usr/local/A3/conf/pf.conf.defaults.

In order to override a default parameter, define it and set it in pf.conf.

/usr/local/A3/conf/documentation.conf holds the complete list of all available parameters.

All these parameters are also accessible through the web-based administration interface under the Configuration tab. It is highly recommended that you use the web-based administration interface of A3 for any configuration changes.

Custom Reports

Using the report.conf configuration file, you can define reports that create SQL queries to view tables in the A3 database. These reports will appear under the Reports tab of the administration interface.

In order to configure a report, you need to edit /usr/local/A3/conf/report.conf and add a section that will define your report.

The following attributes are available to define your report (the ones that have an asterisk are mandatory):

• description : The user friendly description that will display for this report
• base_table : The base SQL table that will be used to create the view
• columns : The columns to select from the table(s) (ex: node.mac).
• date_field : The field to use for date filtering. Will also be used as default sorting field unless order_fields is set in the report.
• joins : The tables to join to the base table and how to join them. See example below and the following documentation.
• group_field : The field to group the entries by. No grouping is done if this field is omitted or empty.
• order_fields : Comma delimited fields for the ordering of the report. The field should be prefixed of - if the sort should be made in descending order for the field (ex: -node.regdate,locationlog.start_time,+iplog.start_time).
• base_conditions : Comma delimited conditions that should be applied to the report. This can be used to filter the report without using the search in the administration interface to provide the proper unsearched view. Conditions should match the following format : field:operator:value (ex: auth_log.source:=:sms,auth_log.status:!=:completed).
• base_conditions_operator : Whether the base conditions should be matched using an all or any logic. Accepted values are all and any.
• person_fields : The fields in your report that represent a user in the A3 database. Field values in this field will be clickable and will allow to view/modify the values of the user in question. The fields must be listed with the name they have in the report header without any quotes and are comma delimited.
• node_fields : The fields in your report that represent a node in the A3 database. Field values in this field will be clickable and will allow to view/modify the values of the node in question. The fields must be listed with the name they have in the report header without any quotes and are comma delimited.
• searches : Comma delimited searches that should be available on the report. Should match the following format type:Display Name:field (ex: string:Username:auth_log.pid).
• type defines the type of the search, the only one currently supported is string.
• Display Name is the user friendly name of the field for display.
• field is the SQL name of the field to search
• You should always prefix the fields with the table name and a dot (ex: node.mac, locationlog.role, …​) so that they are not ambiguous. Although your query may work with a single table, it will not if you decide to add joins that contain column name(s) that are the same as the base table.

Examples:

View of the auth_log table:

In this simple example, you will be able to select the whole content of the auth_log table and use the date range on the attempted_at field as well as search on the pid field when viewing the report.

View of the opened violations:

In the example above, you can see that the violation table is left joined to the class, node and locationlog tables. Using that strategy we make sure all the violations are listed even on deleted nodes. Then, base conditions are added to filter out outdated locationlog entries as well as include devices without locationlog entries. Removing those conditions would lead to duplicate entries being shown since the report would reflect all the historical locationlog entries.

Admin Access

You can manage which access you give to A3 administrators. To do that go through Configuration→System Configuration→Admin Access. Then go to your source which authenticate administrator and create an administration rule and assign the wanted Admin role. This functionality allows you to have a granular control on which section of the admin interface is available to whom.

Built-in roles

• ALL: Provides the user with all the admin roles without any exception.
• ALL_PF_ONLY: Provides the user with all the admin roles related to the A3 deployment (excludes switch login rights).
• Node Manager: Provides the user the ability to manage the nodes.
• User Manager: Provides the user the ability to manage other users.
• Violation Manager: Provides the user the ability to manage the violations (trigger, open, close) for the nodes.

Content-Security-Policy (CSP)

The Content-Security-Policy HTTP response header tells modern browsers what can be accessed from a generated web page. The default policy is pushed for both the captive portal and the admin interfaces and enforces that everything the browser executes comes from within A3, with the exception of the configured network detection host that is by default the Inverse IP address.

If, for some reason the portal is modified with content that needs to be accessed from A3 generated web pages, CSP can be deactivated through Configuration → System Configuration → Main Configuration → Advanced → CSP Security Headers.

pfcmd

pfcmd is the command line interface to most A3 functionalities.

When executed without any arguments pfcmd returns a basic help message with all main options:

The node view option shows all information contained in the node database table for a specified MAC address

If you enabled Percona XtraBackup for your nightly backup, you can use the following instructions to restore it. In this example we will be restoring /root/backup/A3-db-dump-innobackup-2016-12-20_00h31.xbstream.gz

First, create a restore directory, move the backup to it and gunzip the backup:

Then extract the xbstream data:

Once done, you should have a lot of files that were extracted in the restore dir. Now, lets place the xbstream back in the backup directory

Next, install qpress (available from the percona repository) and process any qp file that were extracted:

CentOS:

Debian:

Next, apply the innodb log:

We will now stop MySQL, move the existing data directory and replace it by the data that was extracted:

• On Debian the service will be called mysql and on CentOS 7 mariadb. Make sure you adjust the commands above to your environment.

Should the service fail to start, make sure you look into the MySQL error logs.

Blocking malicious activities with violations

Policy violations allow you to restrict client system access based on violations of certain policies. For example, if you do not allow P2P type traffic on your network, and you are running the appropriate software to detect it and trigger a violation for a given client, A3 will give that client a "blocked" page which can be customized to your wishes.

In order to be able to block malicious activities, installation and configuration of a A3 compatible IDS is required. A3 currently support Snort, Suricata and Security Onion.

Suricata

Installation

Since the Suricata IDS is not packaged with the distros (except maybe Fedora, which we do not officially support), you need to build it the "old" way.

The OISF provides a really well written how-to for that. It’s available here: https://redmine.openinfosecfoundation.org/projects/suricata/wiki/CentOS5

To benefit the OPSWAT Metadefender Cloud integration, Suricata needs to be built with libnss / libnspr support. Make sure to use JSON output. More information on how to achieve this can be found there: https://redmine.openinfosecfoundation.org/projects/suricata/wiki/MD5

Configuration

You will need to follow the configuration below related to the Suricata configuration (Syslog).

OPSWAT Metadefender Cloud

It is possible to trigger violations based on threat level of downloaded files using the Metadefender Cloud integration in conjunction with the Suricata MD5 extraction feature. Without entering in the details, here are the basic steps to make it work.

First, an OPSWAT portal account is required to make use of the API. Such account can be obtained through the OPSWAT portal: https://portal.opswat.com.

Other requirement is a Suricata working installation built with libnss / libnspr support as described in the upper "Installation" section.

Along with the OPSWAT API key for Metadefender Cloud (they call it License Key) and the working Suricata installation, some configuration (A3 based AND Suricata based) is also required.

Assuming that all the steps for Suricata MD5 extraction have been followed, here’s what to do next.

On A3, under Configuration→Integration→OPSWAT Metadefender, enter your Licence Key.

On the Suricata server (syslog-ng is preferred due to easier and more powerful configuration. If not installed, it might be an idea):

Configure /etc/syslog-ng/syslog-ng.conf by adding the following to enable sending MD5 file store log entries to A3:

A restart of the syslog-ng daemon is required

On the A3 server:

Modify rsyslog configuration to allow incoming UDP packets by uncommenting the following two lines in /etc/rsyslog.conf:

Configure /etc/rsyslog.d/suricata_files.conf so it contains the following which will redirect Suricata MD5 file store log entries and stop further processing of current matched message:

Make sure the receiving alert pipe (FIFO) exists

Restart the rsyslog daemon

At this point, Suricata should be able to extract MD5 checksum of downloaded files and send the related log entry to A3.

A configuration of a new syslog parser as well as some violations are the only remaining steps to make full usage of the OPSWAT Metadefender Cloud integration.

Configuration of a new syslog parser (Configuration→Integration→Syslog Parsers) should use the following:

• Type: suricata_md5
• Alert pipe: the previously created alert pipe (FIFO) which is, in this case, /usr/local/A3/var/suricata_files

Configuration of a new violation can use the following trigger types:

• Type: metadefender
• Triggers ID: The scan result returned by Metadefender Cloud online
• Type: suricata_md5
• Trigger ID: The MD5 hash returned by Suricata

Violations

In order to make A3 react to the Snort alerts, you need to explicitly tell the software to do so. Otherwise, the alerts will be discarded. This is quite simple to accomplish. In fact, you need to create a violation and add the Snort alert SID in the trigger section of a Violation.

A3 violations are configured in Configuration→Compliance→Violations

The example below will guide you to create a violation that will isolate device that have generated Peer-to-peer traffic and that are using Mac OSX or have a malware and are using Microsoft Windows

Violation Definition

First you need to configure the violation definition

Where :

• Enabled is whether or not the violation is currently activated (should be ON).
• Identifier is the violation ID. Any integer except 1200000-120099 which is reserved for required administration violations.
• Description is the user friendly description of the violation.
• Actions is the list of actions to be executed when this violation is raised.
  • Unregister node will unregister the node.
  • Send email to owner will email the violation details to the owner of the device. Will only work if the person has it’s email field populated.
  • Send email to admin will email the violation details to the address specified in [alerting].emailaddr, using [alerting].smtpserver. Multiple emailaddr can be separated by comma.
  • Reevaluate access will place the device in the destination VLAN configured in the violation. It opens a violation and leaves it open. If it is not there, the violation is opened and then automatically closed.
  • Log message will log the violation in the log file violation.log.
  • External command will execute a command on the operating system when this violation is raised.
  • Close a violation will close an existing violation for this device when this one is raised.
  • Set role will modify the role of the device.
  • Enforce provisioning will trigger a check of compliance on the provisioners defined for the device.
• Priority defines the order onto which violations should be handled should there be more than one for a device.
• Whitelisted Roles is the list of roles that are not affected by this violation.

Triggers

Next, in the Triggers tab, you need to define the triggers that will raise the violation. In the case of this example it will be these two cases :

* A device that has generated Peer-to-peer traffic and that is using MAC OSX.

* A device that has been detected as being a rogue DHCP.

Click the + sign at the top right in order to create a new trigger, then in the dropdown select Suricata.

A menu will appear into which you can select ET P2P which will match all P2P alerts from Suricata.

Once you added this trigger, select Device from the dropdown and enter 38 which is the device identifier for Mac OSX.

Next hit the < button, then the + to add another trigger.

Select the type Internal, then in the menu that appears below it, select Rogue DHCP detection and click Add.

Remediation

Next, in the Remediation tab, you can configure the behavior when a client gets isolated.

Where :

• Auto Enable is whether or not the user can release the violation himself after acknowledging the message on the captive portal.
• Max Enables is the amount of time a user can use the Auto Enable functionality. After this amount of times, he will not be able to release the violation and it will have to be manually release by an administrator using the A3 administration interface.
• Grace is Amount of time before the violation can reoccur. This is useful to allow hosts time (in the example 2 minutes) to download tools to fix their issue, or shutoff their peer-to-peer application.
• Dynamic Window will only work for accounting violations. The violation will be opened according to the time you set in the accounting violation (ie. You have an accounting violation for 10GB/month. If you bust the bandwidth after 3 days, the violation will open and the release date will be set for the last day of the current month).
• Window is the amount of time before a violation will be closed automatically. Instead of allowing people to reactivate the network, you may want to open a violation for a defined amount of time instead.
• Delay by is the delay before triggering the violation.
• Template is the HTML template the host will be redirected to while in violation. You can create new templates from the Connection Profiles configuration section.
• Button text is the text of the button that is used when the user is releasing the violation directly from the captive portal.

Advanced

In the Advanced tab you configure the destination VLAN of the device when it has the Reevaluate access action and its redirection URL when the user is released.

Guests Management

A3 supports the ability to manage guests by establishing expire dates and assign different roles which will permit different accesses to the network resources.

Guests can self-register themselves using an activation code sent to their mobile phone or they can use their email address and receive and activation link to activate their network access.

A3 has the option to have guests sponsored their access by local staff. Once a guest requests a sponsored access an email is sent to the sponsor and the sponsor must click on a link and authenticate in order to enable his access.

Moreover, A3 also has the option for guests to request their access in advance. Confirmation by email and by a sponsor are the two pre-registration techniques supported at this point.

The admin GUI allow A3 administrators or guests managers to create single accounts, multiple accounts using a prefix (ie.: guest1, guest2, guest3…​) or import data from a CSV to create accounts. Access duration and expected arrival date are also customizable.

Usage

Guest self-registration

Self-registration is enabled by default. It is part of the connection profile and can be accessed on the registration page by clicking the Sign up link.

Managed guests

Part of the web administration interface, the guests management interface is enabled by default. It is accessible through the Users → Create menu.

Guest pre-registration

Pre-registration is disabled by default. Once enabled, A3’s firewall and Apache ACLs allow access to the /signup page on the portal even from a remote location. All that should be required from the administrators is to open up their perimeter firewall to allow access to A3’s management interface IP on port 443 and make sure a domain name to reach said IP is configured (and that the SSL cert matches it). Then you can promote the pre-registration link from your extranet web site: https://<hostname>/signup.

• Pre-registration increases the attack surface of the A3 system since a subset of it’s functionality is exposed on the Internet. Make sure you understand the risks, apply the critical operating system updates and apply A3’s security fixes.

A portal interface type is required to use this feature. A portal interface type can be added to any network interface using the web admin GUI.

Configuration

Access Duration

Default values are located in /usr/local/A3/conf/pf.conf.defaults and documentation for every settings is available in /usr/local/A3/conf/documentations.conf.

The format of the duration is as follow:

Let’s explain the meaning of each parameter:

• DURATION: a number corresponding to the period duration.
• DATETIME_UNIT: a character corresponding to the units of the date or time duration; either s (seconds), m (minutes), h (hours), D (days), W (weeks), M (months), or Y (years).
• PERIOD_BASE: either F (fixed) or R (relative). A relative period is computed from the beginning of the period unit. Weeks start on Monday.
• OPERATOR: either + or -. The duration following the operator is added or subtracted from the base duration.
• DATE_UNIT: a character corresponding to the units of the extended duration. Limited to date units (D (days), W (weeks), M (months), or Y (years)).

These parameters should be configured from the Configuration → Advanced Access Configuration → Access Duration section of the Web admin interface.

From the Users page of the A3 Web admin interface, it is possible to set the access duration of users, change their password and more.

Guest pre-registration

To minimally configure guest pre-registration, you must make sure that the following statement is set under [guests_self_registration] in /usr/local/A3/conf/pf.conf:

This parameter should be configured from the Configuration → Policies and Access Control → Connection Profiles → Profile Name section.

Finally, it is advised that you read the whole guest self-registration section since pre-registration is simply a twist of the self-registration process.

• A valid MTA configured in A3 is needed to correctly relay emails related to the guest module. If localhost is used as smtpserver, make sure that a MTA is installed and configured on the server.