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

1.2. Product Dependency

The Sponsoring Portal requires at least the following MPP and / or Macman product versions.

Table 2. Product dependency

Sponsoring Portal

MPP Version

Macman Version

2.5.0

>= 6.7.1

>= 2.6.11

1.3. Install

To install the Sponsoring Portal, we need either a bare metal server or a virtual machine that meets the requirements as specified above.

Download the latest CloudGuard ISO from https://packages.cloudguard.ch/iso/.

After you have started from the disk image a similar GRUB screen will show up:

grub
Figure 1. GRUB boot screen

Select Install Sponsoring-Portal 2.5.0 and press return. As next, the setup wizard pops up. Follow the instructions. Next, to the wizard, the Sponsoring Portal gets installed on the local disk. This may take some minutes. To finish the installation the server reboots once, and a yellow Linux prompt appears.

1.3.1. VMware Tools

If you are running the Sponsoring Portal in a VMware virtual environment, we recommend that you install the open VM tools.

Install Open VM Tools
apt update
apt install open-vm-tools

1.3.2. 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

sp login screen
Figure 2. Sponsoring Portal Login

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 -Djavax.net.ssl.trustStorePassword=<password>"
<password> must be replaced with the real trust store password (see above).

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 configured beforehand. The Org Unit - Group relation owns the permissions & settings.

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

  1. Guest User (MPP user)

  2. MPP Device

  3. MPP Voucher

  4. Macman User

  5. Macman Device

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

Any configuration issue is shown either as an error or as a warning. Errors indicate a configuration issue which must be corrected by the administrator of the Sponsoring Portal.

The optional field Delete After relates to an Input Template field. If it is defined here, make sure is is visible or enabled on the input template, and vice versa.

Guest User

Guest user specific settings are applied here.

User groups are retrieved from MPP MPP Configuration. These settings need to be configured, and are used to create a guest user.

MPP Device

MPP device specific settings are applied here.

User groups are retrieved from MPP MPP Configuration. These settings need to be configured, and are used to create a MPP device.

MPP Voucher

MPP voucher specific settings are applied here.

Voucher groups are retrieved from MPP MPP Configuration. These settings need to be configured, and are used to create a MPP voucher.

Macman User

Macman user specific settings are applied here.

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

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. The user chooses the directory on the login page.

2.5.1. LDAP Directory

Four sections of a LDAP directory can be configured:

  1. General

  2. Connection

  3. User account LDAP attributes

  4. 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 3. 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 4. 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

The MPP configuration is required to connect the Sponsoring Portal with the MPP.

2.6.1. Connection

Configure the MPP host and port and preferably use HTTPS, if configured. Set credentials, i.e. mpp-admin with the corresponding password.

The connection timeout defines how long the Sponsoring Portal tries to establish a connection to the MPP. The sync interval specifies the interval in which the Sponsoring Portal fetches data from the MPP.

2.6.2. Guest User Template Settings

The Sponsoring Portal lets you display or download the data of a created Guest User.

The template settings define how the data shall be rendered. The data is shown as PDF or plain TXT. Please see the supported fields information box for all available fields.

The file download time limit defines after how many minutes the template data shall be deleted. It must be deleted as it contains sensitive information.

2.6.3. MPP Voucher Template Settings

The Sponsoring Portal lets you display or download the data of a created MPP Voucher.

The template settings define how the data shall be rendered. The data is shown as PDF or plain TXT. Please see the supported fields information box for all available fields.

2.7. Macman Configuration

The Macman configuration is required to connect the Sponsoring Portal with the Macman.

2.7.1. Connection

Configure the Macman host and port and preferably use HTTPS, if configured. Set credentials, i.e. BYOD with the corresponding password.

The connection timeout defines how long the Sponsoring Portal tries to establish a connection to the Macman. The sync interval specifies the interval in which the Sponsoring Portal fetches data from the Macman.

2.7.2. Macman User Template Settings

The Sponsoring Portal lets you display or download the data of a created Macman User.

The template settings define how the data shall be rendered. The data is shown as PDF or plain TXT. Please see the supported fields information box for all available fields.

The file download time limit defines after how many minutes the template shall be deleted. It must be deleted as it contains sensitive information.

2.8. My Device Configuration

2.9. Custom Fields

Custom fields can be defined to enhance Input Templates with additional input fields.

A custom field consists of a unique name and has a type. Based on the type, additional fields such as values or regular expression can be defined.

The following types are available:

  • List: defines a list with values; a value can be selected

  • Text: any text is possible, supports a regular expression to validate the text

  • Yes/No: offers a simple yes-or-no checkbox

An ID is assigned to a custom field, if it is added to the Sponsoring Portal. The ID can be used to identify a custom field from the MPP configuration, for TXT or PDF export.

2.10. 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. Some input templates can be enhanced with Custom Fields.

Input templates exist for the following forms:

  • New Guest User (supports custom fields)

  • New MPP Device (supports custom fields)

  • New MPP Voucher

  • New Macman User (supports custom fields)

  • New Macman Device (supports custom fields)

2.10.1. Configure Input Template

An input template has a unique name, an optional comment, and a priority. It 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 5. 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!

Two types of value providers do exist:

  1. Static value. A default value is defined in the input template and is applied to the form; example: Valid For 1440 minutes, Enabled: true

  2. Generated value. A value generator produces a value for the form; example: Valid From First Login, Voucher Code: 5313

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

The MPP Device field MAC Addresses can’t be modified. It is shown for completeness.

The field Delete After (not available in MPP Voucher) needs to be visible or enabled if it is configured within Permissions & Settings. Adding this field to an input template without setting the permissions & settings doesn’t have any effect.

Custom Fields

Some input templates can be extended with Custom Fields. A custom field of an input template supports the same configuration options. An additional optional field can be configured. It specifies if the field requires an input value or not.

2.11. FTP Servers

The Sponsoring Portal uses one or multiple FTP servers to download CSV files for import tasks.

2.12. Import Tasks

Import tasks are used to automatically download files from an FTP server and create or update entities via CSV Import. They can be created for Guest Users, MPP Devices, Macman Users and Macman Devices using the CSV dropdown button on the Organizational Unit view.

guest user csv dropdown

Existing import tasks can be managed in the Administration / Import Tasks view.

import tasks

The Import task history view shows the status of the executions of a task. The number of task executions that are stored can be configured.

2.12.1. Configuration

An import task runs with the permissions and settings of the user that last edited it. If you want to use a specific input template you can create a new user and change the settings accordingly.

An import task is configured in the following 4 steps:

Step 1: General Settings
Source

The FTP server used to download files. At least one server must be configured in order to create an import task.

Import Strategy

  • Full: Creates or updates all entities that are in the downloaded file and deletes all existing entities that are not.

  • Cumulative: Creates or updates all entities that are in the downloaded file. No entities are deleted.

Step 2: Information Settings
Email Notification

E-mail notifications can be sent after a task execution. The SMTP server settings must be defined in the application.properties file.

One of the following notification types can be used:

  • Always: A notification is sent after each task execution.

  • Failure: A notification is sent after a failed task execution.

  • Success: A notification is sent after a successful task execution.

  • Never: No notifications are sent.

Step 3: File Settings
File Retention Policy

  • None: No action is performed.

  • Delete File: The downloaded file will be deleted from the FTP server after a successful task execution.

File Pattern

The file pattern is a regular expression that defines which file should be downloaded.

If no pattern is defined, or if multiple files match the pattern, the newest file (ordered by last modified) will be used.
Directory

The directory specifies the path on the FTP server used to download files.

File Selection

In order to reach the next step, a CSV file is required. Use the load button to get a list of all files that match the current settings. The file highlighted in green will be used for the field mapping in step 4.

Step 4: Field Mapping

The CSV field mapping is configured in the same way as for a manual CSV import. Please refer to Section 8.1.1, “CSV Field Mapping” for more information.

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.

  1. To fill out the input form

  2. To use the CSV Import / Export 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.

  1. To fill out the input form

  2. To use the CSV Import / Export 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 / Export

The tool can add or delete a number of entities (Guest Users, MPP Devices, Macman Users or Macman Devices) to the Sponsoring Portal at once. The input data is a comma (,) or semicolon (;) separated file, encoded with UTF-8 or ISO-8859-1, also called Latin 1. Former Microsoft Excel versions use this encoding, typically, when exporting to a CSV file.

CSV files can be imported manually, or by an import task. The import task allows to update entities.

8.1. Manual Import

Importing a CSV file is done in three steps:

  1. Uploading the file by choosing the file, encoding and separator

  2. Mapping the column fields

  3. Executing the import

8.1.1. CSV Field Mapping

First of all, it must be defined on which row the import shall start.

Then, each column of the CSV file must be mapped to a field name of the Sponsoring Portal. This is done in the Column-Field Name Mapping table. If a field is provided by an Input Template, it cannot be mapped. The sponsoring portal tries to guess the correct mapping by reading the first line of the file.

The first few lines of the uploaded file are shown in a Preview below, to support the mapping decision.

It is not needed to map all fields to delete entities. An information box shows which fields are required.
For Macman devices, it is not possible to map MAC addresses to particular device slots. MAC addresses are mapped to slots in ascending slot number order.

8.1.2. Import

If the mapping is set, the uploaded file is imported by clicking Add or Delete. Based on the number of lines that are imported, it might take some time. The Sponsoring Portal connects to remote systems such as MPP or Macman, and does several validation checks to assure data integrity over all involved systems.

A success message is shown at the end, if no errors are detected.

Updated entries are just counted for MPP and Macman Devices with multiple MAC addresses. A device is updated if some (not all) MAC addresses were deleted.

8.1.3. Errors

If errors occur, a Summary page with Failed Lines appears. The summary shows deleted, updated and failed entries. Failed lines can be downloaded (as CSV), for correction. The error causes are added in a separate column. The whole import process can start over with the corrected CSV file.

8.2. Automatic import

A CSV import can be automated using an import Task. Please refer to Section 2.12, “Import Tasks” for more information.

8.3. Export

The entities of an organizational unit can be exported as CSV. The encoding is chosen, while the field separator (typically comma or semicolon) is determined automatically by the underlying locale. A header line is added to show the field names.

9. API

9.1. Paths

9.1.1. API login

POST /api/login
Description

Sample cURL login request:

curl -v -H "Content-Type:application/json" \
-d '{"username":"api-user","password":"top-secret","userDirectoryId":1}' \
https://sp01.example.org/api/login
Parameters
Type Name Description Schema

Body

body
required

API login request object (JSON)
Responses
HTTP Code Description Schema

200

Successful operation

400

Invalid credentials or user directory ID

500

Internal server error
Consumes

  • application/json

Produces

  • application/json

Example HTTP request
Request body
{
  "username" : "api-user",
  "password" : "top-secret",
  "userDirectoryId" : 1
}
Example HTTP response
Response 200
{
  "token" : "9be7d5fe-b4a1-4e7f-894e-496916df1f94",
  "username" : "api-user",
  "userDirectoryId" : 1
}

9.1.2. API logout

POST /api/logout
Description

Sample cURL logout request:

curl -v -i -X POST -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json"  \
https://sp01.example.org/api/logout
Parameters
Type Name Description Schema

Header

X-AUTH-TOKEN
required

Authentication token

string (uuid)
Responses
HTTP Code Description Schema

200

Successful operation

No Content

401

Unauthorized request, missing or invalid authentication token

500

Internal server error

9.1.3. Current version description

GET /api/version
Description

Sample cURL version request:

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json"  \
https://sp01.example.org/api/version
Parameters
Type Name Description Schema

Header

X-AUTH-TOKEN
required

Authentication token

string (uuid)
Responses
HTTP Code Description Schema

200

Successful operation

401

Unauthorized request, missing or invalid authentication token

500

Internal server error
Example HTTP response
Response 200
{
  "idAbbreviation" : "75e0c49",
  "version" : "2.4.2",
  "buildDate" : "2018-04-16"
}

9.2. Definitions

9.2.1. ApiLoginRequest

Name Description Schema

password
required

Clear text password
Example : "top-secret"

string (password)

userDirectoryId
required

User directory ID
Example : 1

integer (int64)

username
required

Username
Example : "api-user"

string

9.2.2. ApiLoginResponse

Name Description Schema

token
required

UUID formatted token that must be used for any subsequent API call
Example : "9be7d5fe-b4a1-4e7f-894e-496916df1f94"

string (uuid)

userDirectoryId
required

User directory ID
Example : 1

integer (int64)

username
required

Username
Example : "api-user"

string

9.2.3. Problem

Name Description Schema

detail
optional

A human readable explanation specific to this occurrence of the problem.
Example : "Connection to database timed out"

string

instance
optional

An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

string (uri)

status
optional

The HTTP status code generated by the origin server for this occurrence of the problem.
Minimum value : 100
Maximum value (exclusive) : 600
Example : 503

integer (int32)

title
optional

A short, summary of the problem type. Written in english and readable for engineers (usually not suited for non technical stakeholders and not localized); example: Service Unavailable

string

type
optional

An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).
Default : "about:blank"
Example : "https://zalando.github.io/problem/constraint-violation"

string (uri)

9.2.4. Version

Name Description Schema

buildDate
required

Build date as ISO 8601
Example : "2018-04-16"

string (date)

idAbbreviation
required

ID abbreviation, e.g. leading 7 characters of the SHA-1 value
Example : "75e0c49"

string

version
required

Version string
Example : "2.4.2"

string