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

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.

eduroam NRO administrators can invite their IdPs to make use of the eduroam CAT; 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

Terms of use

eduroam NRO has the full authority to decide and invite the IdPs from NRO's constituency to use eduroam CAT supporting tool.

Managing my National Roaming Operator

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

All of these functions are accessible after logging into CAT with an account with the 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". Additionally there is a link called "The NRO page" in the top menu which serves the same purpose but is available from every page.

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.

After clicking the button or the link, an overview of the NRO occurs, with entry points for the tasks mentioned above.

NRO Properties

You can personalise the appearance and settings of your NRO in CAT.

You can

Use the icon to display help about the meaning of the options.



The list of organisations

This list is meant to help you with managing your federation but also to support your organisations.

The list is interactive, you can type in some text into the Quick search field and the list will only display matching organisation. Matching is done on the displayed name but also on realms registered by the organisations. Next to the name there is a manage or view link. The manage will appear with organisations where you are listed as the administrator, otherwise this will be view and will allow you to examine all details in a read-only mode. 

Various icons are used to display information about each organisation. Place your cursor over an icon to see explanation what it means.

The Status column displays icons about each organisation.

The OR column displays the OpenRoaming tests status.

The Cert column shows which organisations have certificates either close to expiry or already expired. In some cases organisations may have put in a new valid certificate for the roll-over period and then forgot to remove the old one. While this situation does not really hurt end users, it should not be kept for a long time.

The eduroam® Database Link Status column show which organisations are synced with their eduroam database counterparts. Clicking on the buton will allow you to manage the link.

Add/Remove Administrators does what it says and you can also use it to take control (become an admin) of an organisation.

Manage the relationship between an IdP in eduroam CAT vs. an IdP in the official eduroam database

Since the official eduroam database contains production-level and "in preparation" eduroam IdPs it would appear that there is no reason why the two databases should not be identical. Still in reality this is not always the case. Sometimes it may be reasonable to prepare a CAT instance before an institution is added to the eduroam database, also there is room for experimental entries in CAT (after all you can prepare everything in CAT and even be able to download installers with a link, but if you do not set any of your profiles as production-ready, the institution will not appear on the user-facing list).

Whatever may be the reasons, CAT NRO interface allows you to create od delete links between individual institutions. You can see the "not-linked" institutions marked with the red icon on the Manage DB Link button. You can also set the check-box in this column to display only those not linked.

IdPs are automatically linked correctly if you used the "Existing IdP" dropdown list when inviting the first IdP administrator ori the automatic institution creation is used; 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.

However if you created a new not using the entry form the eduroam DB list (see below), then this new IdP will not be linked automatically to an entity in the eduroam database. If this IdP 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 CAT to the entity as seen by the eduroam database.

Creating new IdPs in CAT

There are two ways in which this can be done:

  1. creating IdPs using invitations,
  2. allowing for automatic creation based on the contents of the eduroam database.

See below for details.

Inviting a new IdP to use eduroam CAT

The button on the lower end of the page allows you to send an invitation to use CAT to an IdP in your NRO. This can either be an IdP which is 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). If you create such a bootstrapping institution then it is highly advisable that once it appears in the eduroam database you manually link it with the Manage DB Link function.

After clicking the button, the following window will appear, which allows to take the required actions:

You can either select an institution which is already listed in the eduroam database ("Existing IdP") or you can instead use the "New IdP" row to enter an institution name and NRO by hand.

In both cases, you need to enter the email address to send the invitation to. Before actually sending the invitation, keep in mind that the invitation token for the IdP admin will only be valid for 24h and that the token can only be consumed once. It is thus wise to check that the mail address is going to be read in the next business day and that tokens sent to a mailing list will only be valid for the first person who redeems the invitation token. It may be a good idea to use personal email addresses only. You may put in sevaral addresses separated by commas. Each of the addresses will receive a personalised invitation. The first person to use the invitation will create the new IdP, the next ones will be added to the admins list once they use the invitation.

Once you have sent an invitation, you will be taken back to the NRO management overview, which now lists the new pending invitation. You can revoke the invitation even before it expires after 24h if you feel the need to.

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

Automatic creation of IdP based on eduroam database

We strongly suggest that if this feature is enabled then the NRO admins should keep their CAT organisations in sync with the eduroam database. Obviously it is also crucial that the eduroam database is up to date.

The prerequisite for this type of self registration is that the potential admin must log in with an eduGAIN registered IdP and the email retrieved from the SAML authentication must be present in eduroam database in the administrator's data for the given institution.

Enabling of automatic creation is done via the NRO option Self registration from eduroam DB: allow creating new institutions.

One you have set this on, if a user logs in with and account from an eduGAIN IdP we do the following:

Add representatives of existing IdPs

Again there are more than way in which this can be done:

  1. creating using invitations,
  2. taking control of the organisation by the NRO administrator,
  3. allowing for automatic addition based on the contents of the eduroam database,
  4. allowing for self-addition based on SAML eduPersonEntitlement.

See below for details.

Inviting a new administrator

Once an IdP exists in in CAT, the IdP admins can add more administrators or delete others as they see 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 CAT for further details of administrator management, available here.

Taking control over an IdP by an NRO administrator

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 write access to IdP data of the IdPs which you have invited; they are expected to manage their own IdP in self-service.

Circumstances in which this is not sufficient may include, for example:

You can immediately add yourself as an IdP admin for each IdP in your NRO by using the "Add/Remove Administrators" dialog box. For 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.

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.

Automatic addition based on the contents of the eduroam database

This approach is closely related to automatic creation of IdPs but is controlled by a separate option Self registration from eduroam DB: add listed admins to CAT institutions. Also for this to work well you should have synchronization between cat institutions and eduroam DB (described in detail above).

One you have set this on, if a user logs in with and account from an eduGAIN IdP we do the following:

Self-addition based on SAML eduPersonEntitlement.

For this to function a few of prerequisites are required.

Note: The eduPersonEntitlement attribute is used to mark users' rights to perform some actions in the name of the institution they authenticate with. In this case we are looking for the entitlement to manage eduroam tasks for this institution which is signaled with an appropriate value of this attribute. The NRO admins may set the value to be used within their federation. They do that by setting the value of Custom entitlement value for self-registration option. According to the eduPersonEntitlement specification this value must be an URI. If this option is not set then the default of geant:eduroam:inst:admin will be used.

With all of these prerequisites met, when a user logs is we do the following:


Requesting RADIUS/TLS Certificates

As an NRO admin, you can use the NRO management interface to request new RADIUS/TLS certificates; both for your own NRO servers as well as for any IdPs and SPs within your NRO.

Two prerequisites need to be fulfilled for this to work:

1) The server names need to be listed in the eduroam database

2) There needs to be at least one non-nominative contact for the entity in the eduroam database

An example entry in the ro.json file is below (entries are placed between "coordinates" and "info_url"):

     "coordinates":"49.62,6.15", 
     "server":[
       {
      "server_name":"server1.eduroam.tld",
       "server_type": 1
       },
       {
      "server_name":"server1.eduroam.tld",
       "server_type": 2
      }
    ],
    "contact":[{
       "name":"eduroam Feedback",
      "email":"feedback@eduroam.tld",
      "phone":"+9994244091",
       "type":1,
       "privacy":1
     }
   ],
     "info_URL":[


Once these prerequisites are fulfilled, you can access the Certificate Management interface from the NRO Management page:



You need select for which institution you desire a RADIUS/TLS certificate, and to upload a CSR. The interface provides an openssl command-line with which you can generate a compatible CSR.

The institution selection is limited to the ones that have the prerequisites mentioned above fulfilled.

If the list does not contain an institution that you expect to find, you may check the database status using the dedicated page by clicking the link:


In this example you see what required data is missing.

The eduPKI CA will issue certificates only with information that is vetted, i.e. confirmed correct as per the eduroam database. In particular,

The certificate will always contain the RADIUS/TLS server names that are listed in the eduroam database, all in one certificate.


It takes at least 2 minutes before the request is processed and the certificate is issued. You can download the certificate from the management interface by pushing the corresponding "Display" button.

If your CSR does not follow the rules in some way then the problem may either be caught by CAT even before submission to eduPKI or an error returned by eduPKI will be displayed. To avoid this it is best to use the provided example command without making any changes.




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.

For cases like this, a small API was created which allows NRO administrators to automate a limited amount of actions:

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,

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 content of the response details is given in the constant API::ACTIONS along with the list of parameters (see above) as "RETVAL".

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:

{
    "ACTION": "NEWINST",
    "APIKEY": "foobar123",
    "PARAMETERS": [
        {
            "NAME": "general:instname",
            "LANG": "de",
            "VALUE": "Universit\u00e4t Logohausen"
        },
        {
            "NAME": "general:logo_file",
            "VALUE": "iVBORw0KGgoAAAANSUhEUgAAAIoAAAAyCAMAAAC0wLNOAAAAAXNSR0IArs4c6QAAAwBQTFRFAAAAdHFyyt\/ngbLFVFFSwtnm8fb55\/D1yt7q2Obvrs7a8vf6nMLRxdvo8\/PzlJSV3ury5O703d3d0uPtpKKi7u7uwdjmk73Nlb7OwsHBEW2R\/Pz8zN\/reHV24ezzpsjWS5Gt+fn56urq9\/r82ejuJXma4+Lia6a9srGxtNHc09LSeq7CJSEi0eLs1tbWjLnKfHl6MYGgcqm+vby9t7W2bqa8zuDrvdbkTUlK3OnxPYilPjo7YJ627PP33erxfbDDxNrnZWNjNTEyxtzlhoSFx9zpNIOhZqK5SUZGXFlar62uGXKV6fH1Ooel0ePqDGqPbmts4+309\/r79PT03Orv1uXu1eXsWpqzWFVW2djZ9vb2RkNEKXycRIyp5ubmpMjWo8fUz87O8Pb67PP4UJSu4e3xeYGHMS0uHXWXvdbgXZy0N4WjUE1NdKq\/7vX3sK+vFnCTLSkqLn+ewNfmudTfIHeYODQ1ysnKJyQkQT4\/\/P3+6vL3v9fl\/v\/\/7fT4QIqnvtbl+vz9\/f7+vdXk2ujwz+Hs9Pj7zeDr6fH27vT47vX5Ojc4qKan1+bvyd3p1eXu6PH29vn77\/X5\/v7\/7fX4+fv93uvw+\/z96\/L3+Pv8\/v7+DmuQ1eTuiIaG7vX44u3z8\/j62+jw1OTuXJu0yN3p9fn7SI+r+fz94uHh9Pj66vL2uNPjyNzp2Ofvw9rn5e\/1My8w0OHsFW+TrKurmZeY6Ofn7\/X42+nx7fX54+7y\/Pv81+bsgX9\/t9Lj+\/39H3aYtLOz19fXb3Z70+TtY6C3KycovLq7z+Lp4eDgUk9QcKe9uLe3+Pr8+fv8cHZ79fn6hYOEcG1uutXg8PX5SkdH8vf5u9Tlp8rX5O\/zudPk3+zwWldYw9vkqcrX0M\/PaGVm+\/3+i42Qnp2dzeLpzuHoVJaw6vL1\/\/\/\/ubi47PT44N\/gkY+Q9Pn6o8jWhLTGL4CfxsXFqqmpb6m+qsvYqaeosM\/bpcnW8fHx1OXrGnOWg4GBwL+\/hIKDIx8gCmmOvNXkBVegfAAAAAF0Uk5TAEDm2GYAAAAJcEhZcwAACxMAAAsTAQCanBgAAAAHdElNRQfbCg0FNTZntxP0AAAIIklEQVRYw81XeVhTVxa\/SkIiIYqmRohA1ahFC7UoBcUNF9wXRNFqsbXoFGq1Lp1aGtaYBBEFRWRzLVatO1pbty7Wrmrb6Uxr931fZmtnpk6ZTpJ5795zbpKDfOr3jdL7z7vnvHvP+b2zP8ZaedUPM25gv4FVENzO7PVW2FodyKboCi9fztY3SpxA4k16q\/X8UiCeVi1gWdU6OFYGh+0Mg30jQPGuv+4wbIaOLxgdXm9xMHGRvuB6Q8lDK0QCIzgJGPuul08MVtgdoR4xAe269iDshtJhcUavvkrQhmJilmNAF++91lDWFzuEKh0wdqBZtgFDD3TYtTBEvSEvOmM1xOkB0FQBcbkNoZTD8WgMXGVfVWK1\/d\/i17ZOb8z3Twkdqi4kVkj5TNAl4LL8Ssb2efO1qatMGc56LEBVV6F7dWlj9PFykx4dMAhVDwVsRmKFMDwAdmMVMpAL9DSGpx1K1Ue6TC+YjjVTXHLQedxZvsOUaHoMOAfhthFaWm0KMExwoIEcyPKS4EAJDWw+hrABXpXiWefK5hV7GL50gensKSQ70SxaO5gNb0BVsx0COo5UXBdrR75CyvaF9JOfdOqK++0oOZqoxvsGR2Bw2LHPNMKBVUCnwsdsAHqnDCMdjWiMmDlPL3PHjj+LWBJbMLgRbLjSSLBGAj0I6AygzWC2SohbLUPQjxDQ+BGsjVtdd3Sm\/lsd+NX5VtJWnKSSbAEafYwXqs0AjZkDX9hSCLRbYjkU9xdA78J62VHQVamCdOCFcni\/DmgaAWj2pL2BGptBqQXaUQI3Jwgk7jSgrfmBDtgEDknCC04C5WBLUEoolJTAAC\/YCXQe3HwVoNwKdCFpaNK+1XBgHXHQOgItjDgIPWyWYTiN2Bc\/oscKAWUAkYySEFoFI8G2HWgX0MOIAgxbNLNWgsSZDnPLWwqMmFh\/owx1EKgo+SDQtdrAficzSkegHYDWYJDJbEgihRg\/+wFgzOkbpfn0u+4w6qCifIjSSvCPF39mhmKJqxX0IyDfsZdAiyMpecSXfJFQGOwYLcXbOe6tbfo+2enPW\/m7jhizmD9sCx2UkbGD1MQDVaQEhpEa2eA3zWANsqaiPn2pAm+0OzY31h2lfE8dVitf\/WqkjbcknzAiSRRvp+0w0S8gZDPFyK12SZUpGZM68Kj9fF87o+SaseEMxc9ox4h7I2noZZGoToFq\/brZNySwAhf9VtZRK9U+cw+H8vwzkuONq0Q3own0+KtZR2YEObsmYotKIuDX+41OihUq5GiFIqsHIZj9Asof9gPtSETTszB0uxGLvvUQqfKyCtWRgifD3BQYOvUSywE5o9Q2uh5oBsWR6jTI2QVN7TVioX0We6sRxhlbBRmGrGbiwEowbDHKsEsfOXZUyuGgOu+4y\/gOOOh9rX7LNMMm+c4pk0n\/Gk6TKKV4A2kCchiSRtlH8ueI76e+QUZCcYbB\/2\/fDmH7Wq0ft7LBLM+X44T1mEwwrGY6OrFlJZHcr9eSPsO96ksQb0V0iW\/wHs2hRPlOWhtXOXwphkHANqTQTCzE\/HJ9S\/zl2EbMFvijas+Ta71uta1FKJuydLpS9VTd\/LITJ+x+A3dhWdnGjRsLpVGz8k4IDg7C9u\/LlFXof6Rw47ay+XV5JVc00zezynVY3c+8HBMTsaerb6b9dUlCJ7YVoNju3NNbWUoz6qFuzk5XKtyMmpoZk9ixPvPaCgfMePPixZ+nvOGT+XrPN9+9eLHPl2IEuV85X1NjZzNC\/trnd2o\/+iXkrpCezYD0\/uPDvAXnLrpBtL4ebV5SyNi0TwFK+8Hu3Nzcl84wNl7duH9i7B8ei8WzcEqmx\/OicmFv+GSLR1lTMxfXCJknb16+2cNXziwV7N+U85uXjhqrMi1jd82cO1U9vqAmEMmSbLdc5\/aoSO5w+y8Fyhr1GatAuZ1z1jJ2k6pl92QPh\/LKGI9cj4eqMu9t8nE8U29kLEjdWDKBU4Sb5Hp\/JM9x6SPTRixTn+M643SdO3DN5aBYpnIov+Rwsb3ihR3CGZu5VN1sTv7675yTGSygXGJp\/ZB05moOd2JsAFczmp3lmNxPsDmay0Dhayzrxp8L0lm4sMtTbF58fK8my8eMpcdz1isApVdIyIPCa6HzBP53\/aDcwIUPvPvHh37ljhrMYjhn2Z2+DGoZSv+vek5qK7b3Kr8Ewu7DeSdo+LlP+PDzQnNbgLKYsbF4ZBbf3OgHJc1N1g9PiL+fU1cAZa4qoQvfWpT5h+3m291qsCzMtPjcgFCCGDuPTlzYDMp4CuUTUe4HsiuAcpsqQWh5\/ANlK1yVzNKHCAhLx0ykUG7jmy6MPdqCVS7EHD06YcLRJQkJCd3BKkqR2Xo5KItVCaEiTWYq2yK+7cb682dTqI7NvQooa7nwh+eoo6xmRFrU0+0jRAKdQZgIxR3Beo8MhNJflfCU8ESIUvdOC+vbT6O+9OVXAaW9KCIfTkiIEo6xgeIL\/\/pPLECZLjiD\/zTYfQko4P7kmbrFfLP8L9\/wXPYMee\/kzZ6rgMLuPuwfKYf7MtbBTUoc+EW11aWg7FrAic3COjltMXzVgizWqCuDwmZrfGo1s9V+EgV6R+QClAHwIz8uKhDKeSEhfbgvWxaojWVKL6Dih4DzgjCHJZRZl4DCukbcumhFdvaKgVERp6ACj1+RPfLcq7MXndNoxnVQGA+NWJN9eNx\/\/51wQaPRXHiZsX5jioqKxnRBER\/065bZ1PRgcv9RMDkFTc6ZmDM56O2P7lPPhbNQfj4UL\/5TSTx1c9\/v+fH\/Adrcls52O+PPAAAAAElFTkSuQmCC"
        }
    ]
}