| Table of Contents | ||
|---|---|---|
|
...
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.
An eduroam 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
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.
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.
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.
An eduroam 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
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".
...
For users with the NRO management privilege, the toolset provides a dedicated web interface which allows them to
- invite a new IdP to use eduroam CATthe toolset
- 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
...
After clicking the button, an overview of the NRO occurs, with entry points for the tasks mentioned above.
NRO Properties
You You can also personalise the appearance and settings of your NRO in the toolset. The options vary slightly depending on the tool: you .
Generally available options
You can always
- define the name of your NRO,
- upload 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).
eduroam CAT specific options
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
As of version 2.1, 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.
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.
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 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.
Circumstances in which this is not sufficient may include, for example:
- an IdP admin has erroneously deleted himself and all other administrators of the IdP - so noone can manage it
- you are deprovisioning an IdP, but the administrator(s) refuse to delete the IdP in the toolset's IdP web interface
- the IdP admin requires assistance in setting up his IdP data, and you want to lend a hand
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.
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.
In your 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 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.
enable the "OpenRoaming" feature set if you are happy to proxy OpenRoaming authentication requests from OpenRoaming hotspots towards your eduroam IdPs. You can read up on this here. There are two options to steer OpenRoaming integration:
- OpenRoaming: Allow organisation opt-in - this is the general switch that makes OpenRoaming available to your IdPs
- OpenRoaming: customer NAPTR target - if you want your IdPs to use your own OpenRoaming → eduroam proxy then you can configure the hostname here; the realm check feature for IdPs will then warn them if the OpenRoaming destination server is not yours. This attribute does not need to be set, and the realm checks default to checking for the OpenRoaming → eduroam proxy operated by eduroam OT.
eduroam Managed IdP
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.
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.
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 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, available here for CAT and here for Managed IdP.
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.
Circumstances in which this is not sufficient may include, for example:
- an IdP admin has erroneously deleted himself and all other administrators of the IdP - so noone can manage it
- you are deprovisioning an IdP, but the administrator(s) refuse to delete the IdP in the toolset's IdP web interface
- the IdP admin requires assistance in setting up his IdP data, and you want to lend a hand
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.
Manage the relationship between an IdP in eduroam CAT vs. an IdP in the official eduroam database
Since the official eduroam 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.
In your 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 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 the toolset to the entity as seen by the eduroam database.
Requesting RADIUS/TLS Certificates (2.1.1+)
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 CA will issue certificates only with information that is vetted, i.e. confirmed correct as per the eduroam database. In particular,
- the hostname(s) given in the CSRs CN and/or subjectAltName extensions areignored
- the Organisation field (O) will be ignored and replaced by either "NRO of <country>", or by the name of the IdP/SP as given in the eduroam database.
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.
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)
...
- Creation of a new IdP
- Creation of a new Profile for an IdP
- Listing and Adding administrtators administrators of an IdP
- For eduroam Managed IdP, managing user populations inside IdP profiles
...
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,
...
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".
The authoritative reference for the list of error codes is on GitHub, https://github.com/GEANT/CAT/blob/masterrelease_2_0/web/lib/admin/API.php : the class constants API::ERROR_*
...