Child pages
  • A guide to eduroam CAT for federation administrators

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
outlinetrue
eduroam CAT: 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 debug their RADIUS setup. Authorisation for IdPs to use eduroam CAT is determined by the eduroam National Roaming Operator (the eduroam "federation").

...

API actions are executed by sending an HTTP POST to https://cat.eduroam.org/admin/API.php. Different actions need different POST parameters as per the following table. More details about the actions is available in their respective sections below.

ActionExplanationRequired ParametersOptional ParametersReturns
NEWINSTCreates a new IdP in your federation

APIKEY

NEWINST_PRIMARYADMIN

option, value (arrays of properties of the new institution)

enrollment_URL: The URL your new IdP admin must visit to be registered as IdP admin

inst_unique_id: The unique identifier in CAT for the newly created institution

ADMINCOUNTQueries the number of registered IdP admins

APIKEY

INST_IDENTIFIER

nonenumber_of_admins: The total number of administrators of the institution

STATISTICS

(in 1.0.4+)

Queries the number of downloads per device and in totalAPIKEYnoneXML structure with intformation per-device with their admin & user downloads, and the grand total for all devices

 

The response is an XML file which either informs of success or failure.

Success responses may contain further details. All failure responses contain an integer error constant detailing what went wrong, along with a human-readable description:

Integer return valueMeaningExplanation
1ERROR_API_DISABLEDThe Admin API is disabled on this instance of CAT.
2ERROR_NO_APIKEYThe request did not contain an API Key.
3ERROR_INVALID_APIKEYThe requst contained an API Key, but it was invalid.
4ERROR_MISSING_PARAMETERThe selected action requires parameters, but at least one such parameter was missing.
5ERROR_INVALID_PARAMETERAll required parameters for the action were specificed, but some are invalid.
6ERROR_NO_ACTIONThe request did not specify which action should be done.
7ERROR_INVALID_ACTIONThe request requested an action which is unknown to the system.

(defined in web/admin/API.php)

...

The parameter NEWINST_PRIMARYADMIN is the value which will later be shown in the administrator management as "originally invited as". For user-interactive IdP creation, you are probably used to see email addresses in this field, because the invitations are then sent by email. Since the API puts the burden of showing the enrollment URL to your users on your shoulders, you are free to use any distribution channel for that (you could, for example, put the return code into an HTTP REDIRECT). Therefore, the text in this field is arbitrary. You can use it to correlate it to user IDs in your own customer management system or fill in arbitrary fantasy values. Just note that the values will be seen by the institution admin later on, so watch your wording (smile) (smile)

If you already know some properties of the institution (e.g. if you already register details about institutions in your own customer management system) then you can send almost all institution attributes inside the POST as optional parameters. The new institution will then be pre-provisioned with these attributes. The attribute-value format of the optional parameters is a bit peculiar:

...

The available options on the institution-wide level are:

Option NameExplanationvalue Data TypeMulti-language?
eap:ca_urlURL to a CA certificate which signs the server certificate (root or intermediary)0 
eap:ca_filefile of a CA certificate which signs the server certificate (root or intermediary)2 
eap:server_namename (CN) of authorized RADIUS server0 
general:geo_coordinates

geographical coordinates of the institution or a campus (a PHP-style serialised

array of two numbers "lat" and "lon"), using a full stop "." as decimal separator

1 
general:instnamename of the institution0YES
general:logo_urlURL to a file containing institution logo0 
general:logo_filefile containing institution logo2 
general:SSIDadditional SSID to configure, WPA2/AES only0 
general:SSID_with_legacyadditional SSID to configure, WPA2/AES and WPA/TKIP0 
support:emailemail for users to contact for local instructions0YES
support:phonetelephone number for users to contact for local instructions0YES
support:urlURL where the user will find local instructions0YES
support:info_filefile containing the Terms of Use/Acceptable Use Policy for this IdP2YES

When only these options are set, the API will create a new institution without profiles. It is also possible to add a (one) profile to the institution automatically by including one or more of the following options (at least on the set of the first three must be set):

Option NameExplanationvalue Data TypeMulti-Langauge?
profile:nameThe user-friendly name of this profile, in multiple languages0YES
profile:descriptionextra text to describe the profile to end-users1YES
profile:productionprofile is ready and can be displayed on download page (only acceptable value is "on")3 
profile-api:realmthe realm associated with this profile0 
profile-api:anonthe local part of the anonymous outer identity to use, if that feature is turned on0 
profile-api:useanonturn on anonymous outer identity support3 
profile-api:eaptype

integer value of a supported EAP type, as per the following table. Preference of EAP types is determined by the order induced by their option[Sx] sequence number.

valueEAP Type
1TTLS-PAP
2PEAP-MSCHAPv2
3TLS
4FAST-GTC
5TTLS-GTC
6TTLS-MSCHAPv2
7EAP-pwd


0 

 

Example

A new institution should be created:

...