|Table of Contents|
Purpose and scope
eduroam CAT is the eduroam Configuration Assistant Tool. Its purpose is to allow authorised eduroam Identity Providers to generate customised eduroam installers for various platforms, and to their institution's RADIUS setup on many platforms. It also allows them to test and debug their RADIUS setup. Authorisation for IdPs to use eduroam CAT is determined by the eduroam National Roaming Operator (NRO, a.k.a. the eduroam "federation").
eduroam is organised in national federations. A federation administrator works at the eduroam National Roaming Operator (NRO) and An NRO administrator accredits new eduroam IdPs, changes IdP details, or deprovisions eduroam IdPs. The primary vehicle for this is not eduroam CAT, but the official eduroam database, which contains all registered IdPs and their contact details.
An eduroam federation NRO administrator can invite his IdPs to make use of the eduroam CAT if he wishes to; enabling or disabling IdPs for eduroam CAT is done inside the eduroam CAT administration interface. This interface does not replace an NROs internal customer relationship management system; in particular, CAT does not export data into the official eduroam database; it only consumes data from that database. An NRO is still required to maintain records of all its IdPs and SPs on its own, and to export the corresponding data to the official eduroam database.
The web presence of eduroam CAT is https://cat.eduroam.org
eduroam Managed IdP
The purpose of eduroam Managed IdP is to allow authorised eduroam Identity Providers which do not have their own RADIUS infrastructure to provision user accounts for their end users. The complexity of a typical IdP (RADIUS server, identity management system) setup is taken away and replaced by the eduroam Managed IdP web interface. Authorisation for IdPs to use eduroam CAT is determined by the eduroam National Roaming Operator (NRO, a.k.a. the eduroam "federation").
An eduroam NRO administrator can invite his IdPs to make use of eduroam Managed IdP if he wishes to; enabling or disabling IdPs for eduroam Managed IdP is done inside the eduroam Managed IdP administration interface. This interface does not replace an NROs internal customer relationship management system; in particular, CAT does not export data into the official eduroam database; it only consumes data from that database. An NRO is still required to maintain records of all its IdPs and SPs on its own, and to export the corresponding data to the official eduroam database.
The web presence of eduroam Managed IdP is https://hosted.eduroam.org
The federation administrator interface of eduroam CAT and eduroam Managed IdP are largely identical. The remainder of this document will refer to both as "the toolset".
Managing my federation
For users with the federation management privilege, eduroam CAT the toolset provides a dedicated web interface which allows federation administrators to
- invite a new IdP to use eduroam CAT
- add new representatives to existing IdPs
- delete representatives of existing IdPs
- take control over an IdP
- manage the relationship between an IdP in eduroam CAT the toolset vs. an IdP in the official eduroam database
All of these functions are accessible after logging into eduroam CAT the toolset with an account with the federation operator privilege. With such a user account, a new button will be displayed in the personal overview page: "Click here to manage your federationsNational Roaming Operator". NB: if you are a federation NRO administrator, but do not have a privileged account yet, please see the guide to eduroam Operations Support Services for federation NRO administrators (here).
After clicking the button, an overview of the federation NRO occurs, with entry points for the tasks mentioned above.
You can also personalise the appearance of your NRO in the toolset. The options vary slightly depending on the tool: you can always define the name of your NRO, its logo, choose a skin, and provide custom text to be included when inviting new IdPs. You can also define whether you want your name and logo to appear in the generated installers (this will only happen in select operating systems).
For eduroam CAT, you can optionally upload a CA certificate which automatically gets added for your institutions if you so wish.
For eduroam Managed IdP, you can define the maximum number of users per institution profile.
Invite a new IdP to use eduroam CAT
The button on the lower end of the page allows you to send an invitation to use eduroam CAT to an IdP in your federation. This can either be an IdP which is already in production (i.e. already listed in the official eduroam database with at least the "IdP" role) or it can be a new institution which is still in a bootstrapping phase (i.e. not yet registered in the official eduroam database).
When an invitation has been redeemed, all federation administrators of your federation will receive an email notification by eduroam CAT confirming that a new IdP was created.
Add or delete representatives of existing IdPs
Once an IdP exists in CAT (i.e. once the first invitation token for the IdP has been redeemed by an invitee), the IdP admin can add more administrators or delete others as he sees fit. You can do the same though, by using the "Add/Remove Administrators" link on the right side of the list of IdPs. Please consult the guide to eduroam CAT for IdP administrators for further details of administrators management.
Take control over an IdP
In some exceptional circumstances, it may be necessary that you as the federation operator directly manipulate an IdP in your federation. By default, you do not get read or write access to IdP data of the IdPs which you have invited; they are expected to manage their own IdP in self-service.
From this moment on, the IdP will be listed in your Profile Page, from where you can edit and can manipulate it as you see fit.
Manage the relationship between an IdP in eduroam CAT vs. an IdP in the official eduroam database
Since the official eduroa database contains only production-level eduroam IdPs, but the CAT can also be made available to IdPs which are still in a setup/bootstrap phase, the databases of the two tools are not in perfect sync. To avoid fragmentation and desynchronisation of the databases, federation administrators are encouraged to link the same IdP in both databases together.
Once an IdP is linked, there is no user interface possibility to un-link them again, because there no use cases for this. Should the need to un-link an eduroam CAT IdP from an eduroam database entity, you should contact eduroam Operations by mail.
UI-less Automated Management: the Admin API (2.0)
As a federation administrator, depending on the number of IdPs in your federation, you may find it cumbersome to add institutions interactively. Or maybe you already have a customer self-service management system where authorised IdP admins could self-enroll without you being in the middle.
- Creation of a new IdP
- Creation of a new Profile for an IdP
- Listing and Adding administrtators of an IdP
- Managing user populations in eduroam Managed IdP profiles
Getting API access
The CAT Admin API requires the federation admin to be in possession of an API key. The API key is a long random string which needs to be used when executing API actions. The key is also bound to the federation; i.e. you can only create or query IdPs in your own federation with it.
API keys are distributed from eduroam Operation Team to federation admins on email request. Please contact eduroam Operations for your Admin API key; API keys from version 1.x continue to be valid for version 2.0.
The API is JSON based: you send an HTTP POST with a BODY that contains a JSON construct. The JSON always contains the desired ACTION and the APIKEY. Depending on the ACTION, there may be additional required or optional PARAMETERs.
List of ACTIONs
The authoritative reference for the list of ACTIONs is on GitHub, https://github.com/GEANT/CAT/blob/master/web/lib/admin/API.php : the class constants API::ACTION_* are the available strings to put into the JSON ACTION field.
List of required and optional PARAMETERs
The authoritative reference for the list of PARAMETERs is on GitHub, https://github.com/GEANT/CAT/blob/master/web/lib/admin/API.php : the class constant API::ACTIONS contains two sets of parameters each, "REQ" = required parameters, "OPT" = optional parameters,
All parameters with potentially binary value are to be sent base64-encoded. That's also true for PEM files.
List of result codes
The HTTP POST will be answered with a "result" field, which is either "SUCCESS" or "ERROR". It is accompanied by a "details" field, which contains either the response details, or in the case of error, an additional "errorcode" and "description". The auhoritative reference for the list of error codes is on GitHub, https://github.com/GEANT/CAT/blob/master/web/lib/admin/API.php : the class constants API::ERROR_*
To create a new institution with a logo (the logo in this example is the eduroam logo) and a name with non-ASCII characters, use the following JSON request: