Note that the SDSS Federation no longer accepts new applications to join. Applications should instead be made to join the UK Federation. The information on this page is of historical interest only.

Changing Metadata

This is the current operational process for adding metadata for new members joining the SDSS federation, and for modifying metadata for existing members.

All emails between the applicant and any members of the federation support team should be copied to the federation support mailing list.

Overview

The federation metadata is held in two parts:

  1. In file http://sdss.ac.uk/fed/master.xml
  2. As a set of metadata 'fragment' files held in http://sdss.ac.uk/fed/entities/uk000nnn.xml, where nnn is a three digit number, 000 ≤ nnn ≤ 999.

The master.xml file contains federation trust fabric items, federation-level extensions (if any) and metadata for a number of federation entities. Each metadata fragment file contains metadata for exactly one federation entity. The complete federation metadata is represented by a combination of these files, held in http://sdss.ac.uk/fed/sdss-metadata-unsigned.xml

Whenever a new entity, corresponding to a new IdP or a new SP, is to be added to the federation, a new fragment file is created to hold its metadata. Each person designated as a metadata editor has been allocated a range of numbers nnn and is required to use an unallocated number in his or her assigned range when creating a new fragment file.

When an existing entity's metadata needs to be modified, then either it is already held as a fragment file, in which case that file is edited, or it is held within master.xml, in which case the entity's metadata is removed from master.xml and used to create a new fragment file, incorporating the necessary modifications. It follows that the number of fragment files will increase as entities are added to the federation, while the number of entities in master.xml will remain the same or decrease.

A metadata editor should only edit these component files, never the derived file sdss-metadata-unsigned.xml.

The component metadata files are world-readable and available via the Web, as indicated. However, they are not edited directly: once a copy of an existing file has been edited or a new file created, it is submitted to a member of the federation team, Ian Young, whose job it is to check the correctness of the new or modified metadata, generate sdss-metadata-unsigned.xml and the necessary signed files for federation operation, and finally upload the files. This process occurs frequently – for example, whenever a new entity joins the federation – which is why it is important that federation members refresh their copies of the signed federation metadata regularly (at least daily).

Procedure to be followed by metadata editor

Adding metadata for new members

  1. Check that the information supplied by the prospective new member is complete and contains everything asked for at JoinFedIdP (for an IdP) or JoinFedSP (for an SP).
  2. Check that the requested entity ID matches the rules at EntityIDPolicy.
  3. Check that the supplied Location URLs are actually https: rather than http: ones.
  4. For IdP applicants that are not just short-lived projects (e.g., institutions, departments, quasi-institutions like EDINA), check that:
    1. the required hardcopy letter has been received;
    2. it contains a suitable undertaking to abide by the SDSSFederationPolicy;
    3. the letter is not obviously forged.
  5. Pass the letter to Admin for filing.
  6. For any IdP, check the requested domain. If it looks like an institutional or quasi-institutional domain (e.g., uni.ac.uk or edina.ac.uk) then verify that the required hardcopy letter has been provided. If not, contact the applicant, point out that they need to send such a letter and go to step 4.
  7. Download an existing fragment file, as follows:
    For creating an IdP
    http://sdss.ac.uk/fed/entities/uk000004.xml
    For creating an IdP which is not to appear in the federation WAYF
    http://sdss.ac.uk/fed/entities/uk000005.xml
    For creating an SP
    http://sdss.ac.uk/fed/entities/uk000001.xml
  8. Edit the local copy of the downloaded fragment file as described in the following steps. Use an XML structure editor such as oXygen. Select a currently unassigned value of nnn for the fragment you are going to create, set the ID attribute value in <EntityDescriptor> accordingly and name the fragment file accordingly.
  9. Remove or replace existing comments with comments appropriate to the new entity. Comments should be terse and in keeping with current practice.
  10. Preserve the indentation structure of the fragment, and the single final blank line.
  11. For an IdP, edit the copied fragment file as follows:
    1. Change the entityID to the Entity ID value supplied by the applicant.
    2. In each of the three <Extensions> elements, make sure there is one <shibmeta:Scope> for each Domain requested by the applicant, and nothing else.
    3. Within <IDPSSODescriptor>:
      1. Change the <ds:KeyName> to the supplied SSO Service Name.
      2. If an Artifact Resolution Service Location has been supplied, find the <ArtifactResolutionService> element in the file, and change the Location="..." string to the supplied Artifact Resolution Service Location. If no Artifact Resolution Service Location has been supplied, delete the <ArtifactResolutionService> element from the fragment file.
      3. In <SingleSignOnService>, change the Location="..." string to the supplied SSO Service Location.
    4. Within <AttributeAuthorityDescriptor>:
      1. Change the <ds:KeyName> to the supplied AA Name.
      2. In <AttributeService>, change the Location="..." string to the supplied AA Location.
    5. In <Organization>, change both <OrganizationName> and <OrganizationDisplayName> to the supplied Alias value.
    6. Also in <Organization>, change <OrganizationURL> to the supplied OrganizationURL value.
    7. For <ContactPerson>, add the details supplied by the applicant to contactType="support", contactType="technical" or contactType="administrative", as appropriate. A technical contact is required; support and administrative contacts are optional. contactTypes must appear in the order "support", "technical", "administrative"; more than one occurrence of each type is permitted.
  12. For an SP, edit the copied fragment file as follows:
    1. Change the entityID to the Entity ID value supplied by the applicant.
    2. Change the <ds:KeyName> to the supplied Attribute Requester Name. The software is very fussy about the order of fields (CN, OU, O, C) and acceptable syntax, so be very cautious here, generally preserving the order and syntax of what worked previously and filling in the data rather than just copying in the supplied Attribute Requester Name in the order given.
    3. In <AssertionConsumerService>, change the Location="..." string to the supplied Browser/POST Assertion Consumer Service Location. Add additional <AssertionConsumerService> elements (with a 'browser-post' Binding) if more than one Browser/POST Assertion Consumer Service Locations have been supplied, and change the Location="..." strings to the values supplied.
    4. If one or more Browser/Artifact Assertion Consumer Service Location has been supplied, make an equivalent number of copies of the <AssertionConsumerService> element with the 'browser-artifact' Binding in the fragment file. Change the Location="..." strings to the supplied Browser/Artifact Assertion Consumer Service Locations. If no Browser/Artifact Assertion Consumer Service Location has been supplied, delete the <AssertionConsumerService> element with the 'browser-artifact' Binding from the fragment file.
    5. Each <AssertionConsumerService> must have an index value, which must be unique within the <EntityDescriptor>.
    6. In <Organization>, change both <OrganizationName> and <OrganizationDisplayName> to the supplied Alias value.
    7. Also in <Organization>, change <OrganizationURL> to the supplied OrganizationURL value.
    8. For <ContactPerson>, add the details supplied by the applicant to contactType="support", contactType="technical" or contactType="administrative", as appropriate. A technical contact is required; support and administrative contacts are optional. contactTypes must appear in the order "support", "technical", "administrative"; more than one occurrence of each type is permitted.
  13. Check that the resulting metadata fragment file is XML-valid, and save it.
  14. E-mail the new metadata fragment file to Ian Young, who will check it and sign it if he deems it satisfactory.

Changing metadata for existing members

The first task is to determine whether the metadata to be changed is held in master.xml or in a metadata fragment file. With a web browser, look at the unsigned metadata file, http://sdss.ac.uk/fed/sdss-metadata-unsigned.xml, and find the <EntityDescriptor> element of the entity to be changed. If there is no ID attribute specified, then the metadata is held in http://sdss.ac.uk/fed/master.xml and should be retrieved from there. Otherwise, the value of the ID attribute determines which http://sdss.ac.uk/fed/entities/uk000nnn.xml fragment file to copy and edit.

If the metadata was located in fragment file uk000nnn.xml:

  1. Edit your copy of the file, following the instructions above as appropriate.
  2. Submit the resulting file to Ian.

If the metadata was located in master.xml:

  1. Copy the file http://sdss.ac.uk/fed/template.xml to uk000nnn.xml, having selected an unallocated value of nnn, as discussed previously. Change the ID attribute accordingly.
  2. Excise the old clause from master.xml and insert it at the end of uk000nnn.xml. Note that it is wrongly indented, and the file as a whole is currently invalid.
  3. Cut and paste the entityID attribute from the pasted entity into the right place on the second line of the file.
  4. Delete the <!-- body goes here --> comment, the </EntityDescriptor> tag and the following (now broken) <EntityDescriptor> tag.
  5. Select from there to the end of the file and press Shift-TAB to correct the indentation. (oXygen is required for this step, as otherwise you end up doing a lot of manual editing, which is undesirable.)
  6. Move to the end of the file and remove any surplus blank space. You want to end up with a new line after the last '>', and nothing else.
  7. Check that the resulting metadata fragment file is XML-valid, and save it.
  8. Submit the fragment file, and the modified copy of master.xml, to Ian.

Refresh Metadata

Once Ian has uploaded the signed metadata to the SDSS website, the local copies of the metadata held by the SDSS service machines (bodach.ucs.ed.ac.uk and nevis.ed.ac.uk) must be updated (refreshed).

Log on to the SDSS account on bodach and give the command: 

 ./shibb12/shibboleth/etc/refresh

This should just think for a bit and then return to the command prompt. If a new IdP has been added to the metadata, its Alias should now appear in the WAYF's drop-down list of identity providers.

Log on to the SDSS account on nevis and give the commands: 

 cd sysadmin
 ./refresh

Check that things are still working by closing down all browser sessions then logging in via Shibboleth to one service on bodach (e.g., Film & Sound Online) and one on nevis (e.g., Land, Life & Leisure).

Update EDINA Services Authorisation File

Whenever a new institutional IdP is added to the metadata, the file that controls what EDINA services each Shibboleth domain can access may need to be updated.

Log on to the SDSS account on bodach. Look at the datestamp on the file helios.txt in the top directory: 

 ls -l helios.txt

If the file is more than a few weeks old, you may want to update it with the latest EDINA subscription information by giving the command: 

 ./helios-update

(This may take some minutes).

Inspect the output file helios.txt with a text file viewer: 

 less helios.txt

Search for the name of the institution. Any EDINA services it subscribes to will be listed.

Now edit the text file inst-access. This has a line for each Shibboleth institutional domain name, listing the EDINA short-form service names that institution should have access to, for example: 

 dur.ac.uk: media mediamedical

Add a line for the new IdP. Note: the domain required is the Shibboleth domain, not the DNS domain name of the machine running Shibboleth at the institution, i.e., dur.ac.uk, not shibbox.dur.ac.uk. The short service names required can be copied from elsewhere in the file. Mostly it is obvious what services they correspond to. Where it is not obvious, you can ask the service-delivery people. There is no human-readable central list of these codes at present, as far as I know.

Log on to the SDSS account on nevis and edit the inst-access file there similarly, to grant access to nevis-hosted services.

Concluding Activities

Update the Federation website as necessary (News item, Live sites page, etc.)

Email the applicant to inform them that the new or updated metadata is in service. Copy the email to the Helpdesk, if the original enquiry came through them.