Sponsoring Portal

1. Installation

1.1. System requirements

Table 1. System requirements
Component	Minimum	Recommended
Processor	Dual core with 2 GHz or faster	Quad core with 2 GHz or faster
RAM	2 GB	4 GB
Storage	40 GB	>= 80 GB

This Sponsoring Portal requires MPP >= 5.4.2 or Macman >= 2.6.9.

1.2. Install Ubuntu 16.04 LTS

Download the latest Ubuntu Server 16.04 LTS. Boot your server or virtual machine from the CD.

Figure 1. Ubuntu 16.04.2 LTS Install Screen

On the boot screen press F4 and choose Install a minimal system. Make sure that Install Ubuntu Server is selected an press enter to start the installation. During the installation select the parameters that best fits your installation.

We suggest to install the software standard system utilities and OpenSSH server through the installation.

If you install the Sponsoring Portal as a virtual machine, we recommend to select Guided - use entire disk as partitioning method. Guided - use entire disk and set up LVM is a good fit for bare metal installations.

After you have completed the installation and the system has been rebooted, you can login with the credentials defined during the previous basic installation.

1.2.1. Configure Package Sources

Configure APT sources

sudo -i (1)

apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F369C4E68772878E (2)

apt update (3)
apt install apt-transport-https (4)

cat <<EOF >/etc/apt/sources.list (5)
deb https://system:********@packages.cloudguard.ch/system/ xenial main
deb https://sp:********@packages.cloudguard.ch/sp-v2/ xenial main
EOF

apt update (6)

1	Gain root privileges
2	Add GPG key of CloudGuard Software AG
3	Update local package repository
4	Install HTTPS support for APT
5	Configure APT source list
6	Update local package repository after APT has been reconfigured

1.2.2. Finishing OS installation

Install system updates

apt update
apt full-upgrade (1)
shutdown -r now (2)

1	Perform a full system upgrade
2	Reboot system

Don’t forget to install the package open-vm-tools by issuing the command apt install open-vm-tools as root, if you run the server as a virtual machine.

1.3. Sponsoring Portal

Install Sponsoring Portal

apt install sponsoring-portal

The sponsoring-portal package installs and configures all software it requires. Once the installation has completed, you need to finish the Nginx configuration.

1.3.1. Configure Reverse Proxy (Nginx)

With the default configuration the reverse proxy uses the self-signed certificates of the base system. In order to use your own certificates you have to put the certificate key into the directory /etc/ssl/private/ and the certificate combined with the intermediate certificate into the directory /etc/ssl/certs/. After that, edit the Nginx configuration file /etc/nginx/sites-available/sponsoring-portal and set the value of the properties ssl_certificate_key and ssl_certificate to match your setup.

To put the certificate with the intermediate within one file you can simply call cat cert.crt intermediate.crt > cert-chain.crt on the CLI.

If the fully qualified domain name of the system does not match the URL pointing to the Sponsoring Portal, you have to modify the server_name property as well.

Check Nginx’s configuration with nginx -t and restart the Linux Daemon if everything is ok by issuing systemctl restart nginx.

1.4. Access the Web Console

If nothing went wrong, you should now be able to access the web console by https://<server_name>/. Use sp-admin as username and password to login as administrator. This user has been created automatically during the package’s installation process.

2. Administration

Only users with the role Admin, such as the default user sp-admin are allowed to configure the Sponsoring Portal.

2.1. Certificates

All certificates are handled by the external Java trust store. Therefore you must import any SSL certificate that is in place in your environment like MPP, Macman or external User Directory.

2.1.1. How to import a certificate into the Java trust store

In order to verify a remote peer the Sponsoring Portal has to be able to verify the remote host’s certificate. Either you have the certificate already or you have to fetch it from the server.

Fetch certificate from remote host

remote_host=ldap.exmaple.com
remote_port=636
openssl s_client -servername ${remote_host} -host ${remote_host} -port ${remote_port} < /dev/null 2>/dev/null | sed -n '/^-----BEGIN CERTIFICATE-----$/,/^-----END CERTIFICATE-----$/p' > ${remote_host}.crt

Import certificate

remote_host=ldap.exmaple.com
keytool -import -file ${remote_host}.crt -alias ${remote_host} -keystore /usr/lib/sponsoring-portal/truststore.jks

The default password of the trust store is password.

2.1.2. Configure the Sponsoring Portal to use the local trust store

Open the configuration file /usr/lib/sponsoring-portal/sponsoring-portal.conf and extend the JAVA_OPTS as follows:

JAVA_OPTS="-Djavax.net.ssl.trustStore=/usr/lib/sponsoring-portal/truststore.jks"

After the configuration change has been fulfilled do not forget to restart the Sponsoring Portal systemctl restart sponsoring-portal.

2.2. Organizational Unit

An organizational unit (shortened to org unit) is defined with a name and an optional comment. Multiple organizational units can be structured as parent-child relations.

2.2.1. Configure Organizational Unit

The behavior of an org unit (and its children) is configured through its Permissions & Settings view.

Permissions & Settings

New permissions & settings of an org unit are applied to a particular Group. Such a group must be configure beforehand. The Org Unit - Group relation owns the permissions & settings.

Permissions & settings are applied to four general types of entities:

Guest User (MPP user)
MPP Device
Macman User
Macman Device

Permissions are read, create, edit and delete, while settings are entity type specific. Both permissons & settings are inherited within org units.

Guest User

Guest user specific settings are applied here.

This type has an additional Input Template setting.

MPP Device

MPP device specific settings are applied here.

Macman User

Macman user specific settings are applied here.

Macman Device

Macman device specific settings are applied here.

Device type, device groups and organizational units are retrieved from Macman through Macman Configuration. These settings need to be configured, and are used to create a Macman device.

2.3. Group

A group is a container. It is used for Organizational Unit - Group relation, and to limit My Device approval.

Any synchronized user of a User Directory can be assigned to a group. This helps to easily identify remote users on the Sponsoring Portal.

2.3.1. Configure Group

A group has a unique name, an optional comment, and a max. my devices field. It specifies how much devices a user can approve.

2.4. User Account

User accounts are either created locally, or synchronized from a user directory.

If a user account belongs to the Local Directory, it can be assigned to zero, one or more Groups.

If a user account is synchronized from a LDAP Directory, the user is assigned to a standard group. The standard group is configured in the User Directory general administration.

2.5. User Directory

Two types of user directories can be configured:

Local Database
LDAP Directory

You can manage the users locally on the Sponsoring Portal or connect it to several LDAP directories including Microsoft’s Active Directory. If a user tries to login, the Sponsoring Portal queries any configured directory.

2.5.1. LDAP Directory

Four sections of a LDAP directory can be configured:

General
Connection
User account LDAP attributes
Group LDAP attributes

General

A remote user is assigned to a local Standard Group, if it is synchronized. A standard group is like any other Group, with this exception: a synchronized User Account can not unmap itself from the standard group. The LDAP directory is the authority of this user account, and the standard group defines the mapping to the Sponsoring Portal.

A standard group can be remapped to another group, nevertheless.

To remove all users from a directory on the Sponsoring Portal, the standard group can be set to (None).

Connection

This section defines basic connection settings and some synchronization related configuration options.

The LDAP time limit in seconds defines how long one request can go. Synchronization of a large directory uses multiple requests.

The LDAP count limit of 0 means that all entries are synchronized. This should be the default. For a general connection test run, the value can be set to i.e. 10, to limit the amount of transferred entries.

The LDAP sync intervall in minutes defines how often the whole(!) data is transferred from the directory to the Sponsoring Portal for synchronization.

The LDAP page size specifies the batch size of one result, which is transferred from the directory to the Sponsoring Portal.

Active Directory Attribute Mapping

Table 2. User account LDAP attributes
Field	Attribute
User account ID attribute	`objectSid`
Display name attribute	`displayName`
First name attribute	`givenName`
Last name attribute	`name`
Username attribute	`sAMAccountName` or `userPrincipalName`
User group attribute	`memberOf`
Email attribute	`mail`
Phone number attribute	`telephoneNumber`
User object class	`person`

Table 3. Group LDAP attributes
Field	Attribute
Unique group id attribute	`objectGUID`
Display name attribute	`name`
Group description attribute	`description`
Group member attribute	`member`
Group member of attribute	`memberOf`
Group object class	`group`

Synchronization

Sponsoring Portal synchronization goes one way, from remote to local. The remote directory is the authority of the data, and the Sponsoring Portal consumes the data.

LDAP directory synchronization is done on configuration Save, is triggered automatically, or can be activated by pressing the Synchronize button.

Directory Service Groups

All available Directory Service Groups are shown here. It is possible to assign a directory service group to one or more local Groups.

A remote group is assigned to a Local Group, if it is synchronized. All users within the remote group are assigned to this local group. Like with the standard group, a synchronized User Account can not unmap itself from such a group. The LDAP directory is the authority, and the local group defines the mapping to the Sponsoring Portal.

Local groups are optional. If none is chosen, just the standard group is used.

2.6. MPP Configuration

2.7. Macman Configuration

2.8. My Device Configuration

2.9. Input Template

An input template can be defined to configure which fields are visible on an input form. In addition, static or generated values can be assigned to an input field of a template. The purpose is to simplify and automate user input. The user requires less time to fill out the form.

Input templates exist for the following forms:

New Guest User Account

2.9.1. Configure Input Template

An input template has a unique name, an optional comment, and a priority. Such an input template is referenced from the Permissions & Settings of an Organizational Unit.

The input template with the highest permission is presented to a guest user, if he is member of multiple groups.

A collection of field settings define how the input template looks and behaves. Each field is defined with a field name, if it is visible, if a value provider is enabled, and with a default value.

Table 4. Field settings combinations
Visible	Enabled	Value	Result
True	True	A value must be configured	Field is visible and has read-only value
True	False	Value is ignored	Field is visible and uses user-input
False	True	A value must be configured	Field is invisible and has value
False	False	No value	This combination is not allowed for mandatory fields!

New Guest User Account

Mandatory field names are User Group, Username, Password, Valid From, Valid For, Valid To, Enabled. All other fields are optional.

Two types of value providers do exist:

Static value. A default value is defined in the input template and applied to the form; example: Valid For 1440 minutes
Generated value. A value generator produces a value for the form; example: Valid From First Login

Generated value providers, such as the username- or password-provider require additional configuration.

3. Guest User

Manage user accounts on the MPP, in order to grant network access to guests.

4. MPP Device

Manage user devices on the MPP, in order to grant headless or special devices network access.

A MPP device is related to an Organizational Unit. Given the user has the required Permissions & Settings, two options to manage MPP devices are provided here.

To fill out the input form
To use the CSV Import Tool

The first option is interactive and can add / delete one device, while the second option offers bulk actions.

5. Macman User

Manage user accounts on the Macman, in order to grant network access with WPA2 encryption into a dedicated network (VLAN, …).

6. Macman Device

Manage user accounts on the Macman, in order to grant network access with Layer 2 filtering.

A Macman device is related to an Organizational Unit and to a Macman Device Type setting. The device type defines which MAC addresses of a device are available. Given the user has the required Permissions & Settings, two options to manage Macman devices are provided here.

To fill out the input form
To use the CSV Import Tool

The first option is interactive and can add / delete one device, while the second option offers bulk actions.

7. My Device

Connect personal devices to the corporate network by using WPA2 encryption, in order to use this device at work.

8. CSV Import Tool

The tool can add or delete a number of devices at once. Both actions are executed with the same input data. The input data is a comma separated file, encoded with ISO-8859-1, also called Latin 1. Microsoft Excel uses this encoding, typically, when exporting to a CSV file.

The required CSV File Format depends on a first header row, and data rows. The header row is not processed. The data rows must exactly match the expected format. MPP devices have one format, while Macman devices can have multiple formats.

8.1. MPP Devices

MPP devices have one fixed CSV format.

Example 1. MPP Device CSV Import

#mppcustomer,mppusergroup,name,macaddress,(optional)comment,(optional)marker
CloudGuard Software AG,mac-user-group,mpp100,12:12:13:13:14:14,iface1,m1
CloudGuard Software AG,mac-user-group,mpp100,12:12:13:13:14:15,iface2,m1
CloudGuard Software AG,mac-user-group,mpp200,ab:ab:ab:cd:cd:cd,,

Two MPP devices are imported. The first mpp100 has two interfaces, while the second mpp200 has one. A marker m1 is used to group interfaces of device mpp100. Optional fields can be left blank.

8.2. Macman Devices

The format of a Macman device depends on its device type. The tool supports to import multiple formats in the same file.

Example 2. Macman Device CSV Import

# multiple device type formats can be used within the csv file
Type1,Router,Group1,OrgUnit1,true,Test,11-22-33-44-55-61,11-22-33-44-55-62
Type1,Router,Group1,OrgUnit1,true,Test,11-22-33-44-55-66,11-22-33-44-55-67
Type2,Router,Group2,OrgUnit2,true,,aa-bb-cc-dd-ee-ff

Three Macman devices are imported, two of device type Type1, one of device type Type2.

8.3. Errors

The tool reports two types of errors after it was executed, Invalid CSV Lines and Failed Entries. All other entries without errors were processed.

First, it checks the file syntactically and semantically. It verifies that the referenced MPP customer or MPP user group do exist, for example, or that all mandatory fields of the specified device type are available.

Second, it checks that Permissions & Settings are not violated and reports errors that happened while adding or deleting the devices on the remote system (MPP or Macman).