Adding Metadata

This page has been superseded by ChangingMetadata.

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

  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 Ingrid 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 the latest unsigned metadata master file from http://sdss.ac.uk/fed/sdss-metadata-unsigned.xml to your local machine (from Internet Explorer, right click and Save Target As...). Don't use the signed metadata files linked from the SDSS "Technical" web page.
  8. Edit the local copy as described in the following steps. If you are using a Windows machine, you will need to use an editor that accepts Unix-style line terminators (most things except Notepad should work, including WordPad and EDIT). The description here is in terms of a text editor, which is what I use, but an XML structure editor should work too.
  9. Look in the metadata for an existing <EntityDescriptor> of the same type (IdP or SP) from the applicant's organisation, failing which find an existing provider of the same type from any organisation. Look for simple ones from external organisations rather than the more complicated ones used for some SDSS entities.
  10. Copy this text and paste it elsewhere in the metadata (which is split into two sections, one for IdPs, one for SPs, with the SDSS entries first and the non-SDSS entries generally sorted alphabetically by domain/certificate name).
  11. For an IdP, edit the copied <EntityDescriptor> 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 an IdP within the metadata which has an <ArtifactResolutionService> element, and copy the element to just before the <SingleSignonService> element. Change the Location="..." string to the supplied Artifact Resolution Service Location.
      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 <EntityDescriptor> 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 an <AssertionConsumerService> element with a 'browser-artifact' Binding from elsewhere in the metadata file. Change the Location="..." strings to the supplied Browser/Artifact Assertion Consumer Service Locations.
    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. Save the modified metadata and run a text-difference program to compare it with the original to ensure that only the required changes have been made. In particular, accidentally modifying any of the certificate information at the top of the file, even line-breaks and spacing, would be Bad.
  14. E-mail the modified metadata file to Ian, who will check it and sign it if he deems it satisfactory.

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

Refresh Metadata

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.