eduroam CAT: purpose and scope

Introduction

eduroam CAT is the eduroam Configuration Assistant Tool. Its purpose is to support you, an eduroam Identity Provider administrator, by allowing you to generate customised eduroam installers for various platforms. If, instead of native CAT installers, you prefer to use the geteduroam app, which is now available for most platforms, you still need to provide configuration information in CAT - geteduroam will automatically download these settings after the user select the correct institution/profile.

...

There is a "Choose another installer to download" link which takes users to the full platform selection if they so wish. A screenshot of the download area is below. Try it out yourself: hop over to https://cat.eduroam.org, and select any organisation on the download page!

Device Support

eduroam CAT supports a broad selection of common end-user client devices and many EAP types.To view the full compatibility matrix of supported EAP types and devices, please visit the frontpage of eduroam CAT and click on About eduroam CAT in the About item of top menu. You will see that not all EAP types are supported on all platforms - we largely rely on the target Operating System's capabilities.

...

Notably, Android versions below 4.3 are not supported and likely never will be, sorry. Your helpdesk will have to take care of legacy Android users by other means.

Support Policy for operating systems versions

eduroam CAT generally tries to follow vendors' end of life dates:

• Microsoft products:http://windows.microsoft.com/en-us/windows/lifecycle
• Apple products: https://support.apple.com/en-gb/HT201624
• ChromeOS products: https://support.google.com/chrome/a/answer/6220366
• Android products: there is no clear support strategy that could be linked against. Status as of Oct 2021 is that apparently Android 8.1 AOSP is the oldest that still receives security updates.

Scope

eduroam CAT is not replacing your helpdesk! While we hope to do you a good service by taking the technical task of generating secure installers for many platforms into our hands, we can not take your users' phone calls or tell them how to fix problems on their computers. The CAT's installers work on the target platforms if these have not been modified beyond reason by the end-user, and we hope the installation process with them is intuitive enough; but we can not give you guarantees that you will not ever hear from failing users again.

Enrolling my institution for eduroam CAT

Step 1: Requesting an entry for your institution

eduroam CAT follows the usual organizational model of eduroam: your national federation administrators has control over all the Identity Providers in their country.

...

If self-registration option does not work for you then just ask your national to send you an invitation token ny email (the token is valid for 24 hours after sending it to you). You can then follow the supplied link with the token, log into the eduroam Administration interface, and start managing your institution - see the next section for details of institution and profile setup.

Step 2: How to log into eduroam CAT?

Under the Manage Tab, go into eduroam® admin access, you will be automatically sent to the eduroam Support Services' federated login service. This login service does not work with site-specific usernames and passwords, instead you are presented with a list of sources of identity. Choose any organization that you have an account with:

...

Sometimes, when you have not used CAT for a long time, you may be unsure of how you logged in before (you may have switched from Google to a local IdP, for instance). You could then try to use IdP Reminder option on the login page.

Configuring my institution's properties

Overview

• There are basically four groups of information which we need to ask of you before we can create good-looking installers for you:
   general information about your institution (e.g. logo, approximate location, name)

...

Institution-wide settings

After you've followed the invitation token from your national administrator or created the new institution yourself based on the eduroam DB contents, you'll be dropped right in the "Edit IdP" page. On that first time, you'll see a "wizard mode" which provides lots of explanatory text about the meaning of all the settings you can make. You can add and delete any of those options; don't be shy and try them all out! Adding a new option is done by pushing the corresponding button, selecting which option you want to set, and then the content of that new option. Changes will only be saved when you hit the "Continue ..." button on the bottom of the page.

...

You can configure four of the five areas mentioned above in this first page. The RADIUS and EAP settings are configured in the more specific Profile configuration at a later stage.

General Information

The options in this area - organization name; logo, acronym, alternative names are self-explanatory. You should add several language variants so that installers and user GUI can display things in the most appropriate manner.

Location

The reason for this option is to help the user GUI order institutions based on distance from the user location. This should be helpful in most situations, as most of your users will be probably configuring eduroam while relatively close to your institution.

Helpdesk Contact Details

You should provide information for your users. This information will be shown on the CAT download pages and also by some of the installers. The information may be given in several languages. You can also add a Terms of Use text file. This text will be shown by the installers at the start of the so that the users will be able to read and confirm.

Media Properties

Here, you can now configure all media properties of your eduroam setup.

...

• SSID:
  If you deploy other SSIDs for which eduroam credentials are valid, you can add these here and they will be configured alongside the eduroam SSID.
• Additional HS20 Consortium OI:
  If you want to enable Passpoint/Hotspot 2.0 and have a Consortium Organization Identifier, you can enter it here. The consortium OI for eduroam is 001BC50460 and we configure it by default in devices that support Passpoint - we make an exception for Apple devices which force the user to submit their credentials twice - we find this an extra trouble for the user, probably not worth the limited usage of Passpoint-based eduroam access.
• Configure Wired Ethernet:
  Some eduroam participants also use IEEE 802.1X for wired ethernet ports in their premises, e.g. in dormitories. Administrators can specify that the installers should include wired ethernet eduroam configuration on the client devices. This is currently supported for the Windows installers and Apple OS X. Windows installers will provoke a UAC prompt when wired support is turned on.
• Remove/disable  SSIDs:
  Many eduroam participants deploy several SSIDs; typically, a captive portal SSID for help and/or download of configuration profiles/configuration instructions (a "bootstrap" or "onboarding" network), and the real eduroam network. If your users have connected to the bootstrap network before, their devices usually remember it, and may unfortunately prefer that network over the then-configured eduroam network. To prevent this, you can configure the name of your bootstrap SSID, and then during the installation process, CAT will either remove it from the client device, or at least mark it as "do not join automatically".

Profiles

Profiles are the specific EAP configurations for your user group(s), and installers are always generated for specific profiles. If you only have one user group, the distinction between institution-wide and profile-wide settings does not make a difference. However, many IdPs have different user groups which share some properties, but not all. One example is where on the one hand students have username/password accounts, authenticating with PEAP and generic helpdesk contact points, and on the other hand permanent staff have TLS Client certificates with EAP-TLS and access to a better second-level helpdesk just for them.

...

They are used to create your profiles. You can use either of them, so here are the reasons to choose one.

Manual profile setup

Use this one if one of the conditions below is true:

• your RADIUS server is not yet reachable via the eduroam infrastructure, perhaps you are testing it locally and you want to see how the installers will work;
• your RADIUS server uses a certificate from a private CA.

Autodetect server details

This will save a bit of work but only if all below conditions are met:

...

You will need to provide an outer username that will be accepted by your server (no password is necessary as no actually connection will be made). CAT will then reach you server and try to validate the server certificate against the well-known CAs. If one is found then it will be marked in the CAT profile as the one to be trusted. Your server name will also be retrieved from the server certificate and added to CAT settings. Finally the outer username will ne used to set up realm information and the name used for anonymous authentication. You will find all these settings already filled in when you are taken to the profile editing page.

Profile settings

General properties

If you are going to use a single profile for your institution then you do not need to set up neither profile name nor description, as they will not be shown anyway. If you have multiple profiles, both of these are necessary and should be provided in multiple languages if you find this appropriate. 

...

 If you want users of that profile NOT to be given an installer from the CAT page, you can also specify that we should send your users to your own support page instead. A typical use case for that is if you, the admin, want to generate installers but only download them yourself and present them on your own eduroam support page.

EAP types

The third part of profile generation is about the EAP types which you've configured in your RADIUS server for this user group. By simple drag&drop, please drag all the EAP types you support into the upper green area. The list is ordered by preference, so drag the EAP types into your preferred order. The CAT will always compare the EAP types you've configured here with the capabilities of the various devices which are to be configured. If the device supports your most preferred EAP type, installers will always be generated for that EAP type. If your preferred EAP type does not work on a given device, the preference list is worked through until a match occurs, and then installers for that device will use that not-so-preferred EAP type (which is better than not supporting eduroam configuration at all). Finally, if there is a complete mismatch between the EAP types you support and the EAP types on a device, then we can't generate installers for that device. You might be luckier if you can change your RADIUS setup to support more EAP types then.

EAP Details

In the EAP Details section, you can upload common properties of your RADIUS installation's EAP configuration. If you have used the autodetect setup then this section will be filled and you probably do not need to do anything (unless your servers use separate names and in such case you need to add them all).

...

If CA certificates in your configuration expire then your installers will stop working. CAT profile page will show you warnings when the expiry time is getting closer and then use the rollover procedure to supply new ones in time. Unfortunately users configured with the expired certificate only will need to rerun the installation procedure. The same is true if for some reason you need to change the root CA to a new one.

Overriding IdP-wide helpdesk settings

After these steps, you can enter/override helpdesk and media properties if you haven't done so on the institution-wide settings already (see above). If you have entered one specific option institution-wide already, and you enter something else here, then the settings on profile level supersede the institution-level ones. 

That's all - the CAT then proceeds to a sanity check of the things you have configured and will tell you about any things which need fixing, it any. You are then transported to the Institution dashboard - from where you can continue to download your installers, change institution or profile details, perform sanity checks and more.

Optional: OpenRoaming support

OpenRoaming is a Wi-Fi roaming consortium independent from eduroam, but using similar underlying technologies. You can find more details about this consortium and eduroam's interaction, and information for eduroam end users.

...

Note on geteduroam and user choice: the in-app workflow only installs OpenRoaming if one the "Always" variants has been selected. If "Ask user" has been selected, geteduroam in-app workflow will only install eduroam, not OpenRoaming. "Ask user" will soon work (2.1.1 or as a hotifx) by downloading the Android installer from the end-user download interface of CAT and an "Open with ... geteduroam" (known as 'side-loading' in geteduroam).

Changing the order of profiles

By default the profiles are ordered chronologically, but you can easy reorder them by clicking the Change the order of profiles button. You will then be shown a drag&drop interface to do the reordering.

Duplicating profiles

In some cases you may need to create a new profile based on the one you have. You can then need to click the Duplicate this profile button. You will be asked to provide a new name for the duplicate and it will be automatically created with all settings, except that the new profile will bot be set as "production ready", you will need to do this manually once you are done with all corrections.

Generating installers for my users

On the institution dashboard page, you see the most important pieces of data that you have entered.

...

Maybe you have something special to communicate to your users? E.g. hints which password to use for EAP-TTLS, or which secretariat to turn to to get for the client certificate for EAP-TLS? Maybe you ban Apple Smartphones from your campus and want to alert users to that end?

For all these options, the Fine-Tuning page has extra buttons: you can add free-text for either specific EAP Types or specific devices. This text will then be displayed on the user download page before the download begins. For devices, you can also specify a Redirect target; if this is set, CAT will not provide a download button, but instead will redirect users to the URL you specified. This could, for example, be useful if you have a custom-made or commercial installer for one of the devices, and don't want to use CATs services for that device. If this option is set, the background for this device will turn white in the matrix (see screenshot above).

Image RemovedImage Removed

You can now push the download buttons and use the generated installers as you see fit. This is also possible for redirected devices; even though your users don't get this installer from CAT, you as an admin might want to have it anyway, e.g. to include it in your own eduroam support pages.

Installer visibility on the user download page

You are in full control which of the installers, if any, and when you want to show on the CAT end-user download pages. Your control options are as follows:

Image Added

Image Added

There is one option (currently available for Android devices only) which is of special interest. It is called Show the dedicated geteduroam download page for this device. If you turn this on then the users accessing this profile on Android devices will see:

Image Added 

The plan is that in future this approach may ba available for more devices and possibly become a default one.

Once you have finalised all settings you can push the download buttons which open the extra window allowing you either to do the download or just copy the deep link to this particular installer. Providing a link is actually much better that downloading the installer and making it available locally as the link will always download the newest version ot the installer with all configuration updates you may have made and also all CAT updates (should there ever be any).

Image Added

This is also possible for redirected devices and profiles and profiles which are fully configured but nie "production-ready".

Installer visibility on the user download page

You are in full control which of the installers, if any, and when you want to show on the CAT end-user download pages. Your control options are as follows:

• Make the EAP profile visible, but redirect users to your own support pages (entry is listed, but no download on the public page). This can be set in Profile options - see screenshot.
  Image Added
• Make the EAP profile visible with installers, but redirect certain devices to your own
• Make the EAP profile visible, but redirect users to your own support pages (entry is listed, but no download on the public page). This can be set in Profile options - see screenshot.
  Image Removed
• Make the EAP profile visible with installers, but redirect certain devices to your own pages. Use the Fine-Tuning matrix to set the Redirect option for the device (see previous section).
• Make all installers visible.

All of three options will require confirmation by you that you have entered all details and have reviewed the profile to be "production-ready". No details of your EAP deployment will be made visible until you have declared your data set production-ready. You do this by adding the option with that same name in your Profile properties.

On the institution overview page you can also see icons showing the status of your profile, some examples are shown below:

Image AddedImage AddedImage Added

The visibility status of your EAP deployment is indicated with either a green (published) or yellow (unpublished) status icon on the Profile info (see screenshot). If the status is yellow, you can hover with your mouse over it to get a more detailed explanation why the profile is not published.of the meaning of each of the icons.

Image AddedImage AddedImage Removed

Verifying my RADIUS setup

If you have supplied the CAT with the realm which you are using in eduroam, an extra service is enabled for you: the CAT can send live data probes through the eduroam infrastructure to see if your realm's RADIUS server is reachable and whether it passes various sanity checks. All these tests are triggered by pushing the button "Check realm reachability". You will be presented with an overview page immediately while various tests are executed in the background:

...

• a DNS check whether your realm is publishing NAPTR records for eduroam Dynamic Discovery; and if so, whether all DNS records are correct (if you don't know what Dynamic Discovery is, please talk to your national federation operator. It's cool!). If the DNS checks were successful, the CAT will make actual use of the discovered RADIUS Dynamic Discovery server targets and try to connect. It will present a mix of valid and invalid certificates and will check whether the server acted correctly on receipt of these certificates.
  
• the results of actual authentication tests which were sent in the moment you pushed the button: these will not log anybody in (we don't have actual user credentials) but even with the planned failed authentication, we can run lots of diagnosis on your server. The web page will let you know if we found some oddities you might want to take care of:
  • Authentication round-trip times to your realm which take more than 5 seconds are suspicious
  • Your server must be able to send and receive UDP fragments (some firewalls choke on that)
  • There are a number of RADIUS attributes that are commonly present in authentication requests; some servers behave strangely on receipt - we'll let you know if yours is problematic
  • Checks regarding the structure and validity of your server, intermediate and root CA certificates. These checks are as thorough as checking everything that is described in prose on the EAP Server Considerations page. Here is a typical output if your server certificate is "from the 1990s" (i.e. didn't keep up with all the recommendations and requirements on server certificates in recent years):

           
  
  

• If you feel comfortable giving CAT access to short-lived real authentication credentials (for debugging purposes with test user accounts only!), then you can run an actual positive authentication test; in which case we can run even more diagnosis.
  

Other features

User API

A full access WEB API makes it possible to create different user interfaces to CAT. In particular you can list countries with configured institutions, list institutions globally or within a country, list profiles within institution, ask for the institution logo or even geolocate users's IP address and, of course download installers for given user profiles and devices.

Silent Windows installers

.

Windows installers features

CAT Windows installers can be run silently with the /S flag, which is useful for institutions which want to build the installers into their own, larger ones.

if you run the installer with -debug=n (where n can be from 1 to 4) to turn on various levels of debugging. The log is written into the CAT.log file and also temporary profile XML files used for setting up the network are not deleted. One of these files will contain the actual login credentials, to delete them it is easiest to run the installer again without the debug flag.

Linux installer features

The Linux installer is a Python 3 script. It is meant to interact with the Network Manager and for GUI uses one of tkinter, zenity, kdialog, yad and if none is found it falls back to simple text. If you are not using Network Manager then you could still generate a complete configuration file for either spa_supplicant or iwd. Run the installer with --help option to see more detailsCAT 1.1 Windows installers can be run silently with the /S flag, which is useful for institutions which want to build the installers into their own, larger ones.

Replacing the RADIUS server root CA certificate

When your RADIUS server's root CA certificate is about to expire and you need to replace it with a new one, the new CA certificate needs to be communicated to all your users' devices. The procedure to achieve this is as follows:1. Create a new “migration”

1. Modify your eduroam profile in eduroam CAT,

...

1. to contain both the current and new root CA certificates

...

1. .
2. Require all new and existing end-users to download the

...

1. modified profile. Their devices

...

1. will then be capable of trusting both the current and the new CA, and will accept server certificates from either CA.

...

1. Once you are confident that all end-user devices have

...

1. the “migration” profile installed, apply the new server certificate

...

1. on the Radius server(s). Ideally, the host name in the certificate CN/subjectAltNames should be identical to the old server certificate.

...

2. Modify the eduroam profile in eduroam CAT

...

1. by deleting the

...

1. old root

...

1. certificate

...

1. .

Getting Help with eduroam CAT

If you have any questions about the eduroam CAT website or the underlying software, don't hesitate to ask on the mailing list cat-users@lists.geant.org . If possible, please subscribe to the list before posting; this guarantees that you'll get replies even if someone forgets a "reply to all", and also ensures that your post doesn't accidently get classified as spam and discarded.