|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 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").
The web presence of eduroam Managed IdP is https://hosted.eduroam.org
eduroam NRO has the full authority to decide and invite the IdPs from NRO's constituency to use eduroam CAT and Managed IdP supporting tools.
For the eduroam Managed IdP tool, there is a limit of a maximum number of 10.000 active end users per NRO. Should the number of active end users within an NRO's constituency exceed this number, eduroam Operations team will contact respective NRO to determine further steps. That limit is not technically enforced and can be followed up with delay and asynchronously. So, no online notification in any way is foreseen.
The federation NRO administrator interface of eduroam CAT and eduroam Managed IdP are largely identical. The remainder of this document will refer to both as "the toolset".
National Roaming Operator
For users with the federation NRO management privilege, the toolset provides a dedicated web interface which allows federation administrators them 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 the toolset vs. an IdP in the official eduroam database
All of these functions are accessible after logging into the toolset with an account with the federation NRO operator privilege. With such a user account, a new button will be displayed in the personal overview page: "Click here to manage your National Roaming Operator". NB: if you are a NRO administrator, but do not have a privileged account yet, please see the guide to eduroam Operations Support Services for NRO administrators.
The button on the lower end of the page allows you to send an invitation to use the toolset to an IdP in your federationNRO. 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). eduroam Managed IdP institutions are not typically registered, because their realm is not determined yet - it will be set by the eduroam Managed IdP system.
Once an IdP exists in in the toolset (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 IdP-level guides to the respective tool of the toolset for further details of administrator management.
Take control over an IdP
You can immediately add yourself as an IdP admin for each IdP in your NRO by using the "Add/Remove Administrators" dialog box. For federation NRO administrators, the dialog box has an additional button "Take control of this IdP". By simply clicking this button, you will instantly become IdP administrator of this institution. Most notably, you do not need to send an email invitation to yourself; the process completes instantly.
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 NRO administrators are encouraged to link the same IdP in both databases together.
In your federation NRO overview page, you'll see the database link status on your dashboard page; the IdP is either "linked" or "NOT linked" to the eduroam database.
IdPs are automatically linked correctly if you used the "Existing IdP" dropdown list when inviting the first IdP administrator; then no further action is required. You can still click on the "Manage DB link" button to see some IdP details as seen from both databases, or to unlink them if there is a need.
If you created a new IdP instead, then this new IdP will not (ever) be linked automatically to an entity in the eduroam database. Once the IdP is in production and becomes listed in the eduroam database, you can add the link yourself by again pushing the same "Manage DB link" button.
Simply select the appropriate entry from the dropdown list and click on "Create Link" to link the IdP as seen by eduroam CAT the toolset to the entity as seen by the eduroam database.
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 NRO administrator, depending on the number of IdPs in your federationNRO, you may find it cumbersome to add institutions IdPs 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.
For cases like this, a small API was created which allows federation NRO administrators to automate a limited amount of actions:
- Creation of a new IdP
- Creation of a new Profile for an IdP
- Listing and Adding administrtators of an IdP
- Managing user populations in For eduroam Managed IdP, managing user populations inside IdP profiles
Getting API access
The CAT Admin API requires the federation NRO 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 federationNRO; i.e. you can only create or query IdPs in your own federation NRO with it.
API keys are distributed from the eduroam Operation Operations Team to federation admins NRO administrators 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 authoritative reference for the list of ACTIONs is on GitHub, https://github.com/GEANT/CAT/blob/masterrelease_2_0/web/lib/admin/API.php : the class constants API::ACTION_* are the available strings to put into the JSON ACTION field.
The authoritative reference for the list of PARAMETERs is on GitHub, https://github.com/GEANT/CAT/blob/masterrelease_2_0/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.
If the parameter is the integer representation of an EAP type, you can look up the number to use in the source (const INTEGER_...).
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
The content of the response details is given in the constant API::ACTIONS along with the list of parameters (see above) as "RETVAL".