What does the service do?

The eduGAIN isFederated Check Service allows to find out if the organisations represented by a list of email addresses or domain names are already supporting federated login and if they are already participating in eduGAIN.

How does the service work?

The EIFCS downloads federation metadata for all federations including eduGAIN. The list of federations is stored in a database table and has to be updated manually from time to time. Ideally, only federations are added that self-declare themselves as production federations. The metadata files for each federation then is parsed to filter out all descriptions of Identity Providers. Of particular interest are the domain names that are used fro the endpoints and scopes of the Identity Providers because these domain names then are used to determine if a an organisation is federated and eduGAIN-enabled. The same is also done for eduGAIN metadata.

Some federations use a so-called hub&spoke architecture where only one Identity Provider is listed in their local federation metadata. Sometime this IdP does not list scope elements (domain names) of those organisation that are connected to it. Therefore, in addition to parse this federation's metadata file, EIFCS also allows to run a federation-specific processing script which typically will download a HTML web page of that federation, which lists all organisations connected to that federation. If the listed organisations also contain a domain name or a contact address, this information then also can be parsed and associated with this particular federation.

Architecture

The EIFCS consists of the following components:

  • Cron script This script must be executed regularly. It downloads and parses all metadata files to update the EIFCS data.
  • Web directory All files in the www directory should be accessible via the web server. These files provide the functionality to access the EIFCS via the /isFederatedCheck/ and /isFederatedCheck/Federations URLs.
  • Custom Processing scripts All files of the form process_*.php contain the custom scripts for hub&spoke federations.
  • Other files

Maintenance Jobs

The following things can happen or should be done from time to time:

  • Update federations Every few months, new federations might emerge. Those that consider themselves production federations, should be added to the EIFCS database. To add a new federation, add a new entry in the "Federations" table. An entry for a federation contains the following fields:

    • Name: Full display name of federation
    • Shortname: Short name of federation, which can also be used as identifier
    • metadataURL: URL to local SAML2 metadata file of that federation. This file typically is not the same as the eduGAIN upstream metadata file of that federation.
    • metadataPageURL: URL to web page that contains information about this federation's metadata
    • Country: Two-letter country identifier of that federation
    • Website: URL to website of this federation
    • RegistrationPolicy: URL to federation registration policy document
    • RegistrationAuthority: SAML2 metadata registrationAuthority value used by this federation in eduGAIN
    • EmailAddress: Contact email address for this federation
    • CustomScript: If federation is a H&S federation, you might add a custom script to manually retrieve organisation domain names of that federation
    • IdentityProviders: This field will be set by the updateDatabase.php script

  • Federation metadata cannot be downloaded If the cron script cannot download federation metadata from a particular federation, an email is sent to the administrator of the host or the address configured in the MAILTO variable of the cron script. Often federation metadata is only temporarily not available. In these cases, just ignore the email notifications. If federation metadata is not available for more than a few days, this probably means its URL changed or the federation stopped being active. In these cases, the federation's data has to be updated in the database.

Software Development

The software was developed with NetBeans 8.0. To design the database layout MySQLWorkbench was used initially.

  • No labels