Purpose and scope

eduroam CAT

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 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").

...

The web presence of eduroam Managed IdP is https://hosted.eduroam.org

Terms of use

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.

Nomenclature

The 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".

Managing my National Roaming Operator

For users with the NRO management privilege, the toolset provides a dedicated web interface which allows them to

...

For eduroam Managed IdP, you can define the maximum number of users per institution profile.

Invite a new IdP to use eduroam CAT or eduroam Managed IdP

The button on the lower end of the page allows you to send an invitation to use the toolset to an IdP in your NRO. 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.

...

When an invitation has been redeemed, all NRO administrators of your own NRO will receive an email notification by the toolset confirming that a new IdP was created.

Add or delete representatives of existing IdPs

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

In some exceptional circumstances, it may be necessary that you as the NRO operator directly manipulate an IdP in your NRO. 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 tools are not in perfect sync. To avoid fragmentation and desynchronisation of the databases, NRO administrators are encouraged to link the same IdP in both databases together.

...

Simply select the appropriate entry from the dropdown list and click on "Create Link" to link the IdP as seen by the toolset to the entity as seen by the eduroam database.

UI-less Automated Management: the Admin API (2.0)

As a NRO administrator, depending on the number of IdPs in your NRO, you may find it cumbersome to add 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.

...

• Creation of a new IdP
• Creation of a new Profile for an IdP
• Listing and Adding administrtators of an IdP
• For eduroam Managed IdP, managing user populations inside IdP profiles

Getting API access

The CAT Admin API requires the 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 NRO; i.e. you can only create or query IdPs in your own NRO with it.

API keys are distributed from the eduroam Operations Team to 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.

API Usage

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/release_2_0/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/release_2_0/web/lib/admin/API.php : the class constant API::ACTIONS contains two sets of parameters each, "REQ" = required parameters, "OPT" = optional parameters,

...

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 authoritative reference for the list of error codes is on GitHub, https://github.com/GEANT/CAT/blob/release_2_0/web/lib/admin/API.php : the class constants API::ERROR_*

Example

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:

...