Contacts in Metadata

Contact Information in Metadata

The principal use of contact information in metadata is to enable effective incident response between federation participants when systems fail, users encounter problems, or a security incident occurs.

A secondary function is to support user interfaces (UIs), but in general most of the contact information displayed by an identity provider or service provider (for example on error, discovery, login, or consent pages) is for the presenting site (and thus known to it already). A notable exception is an identity provider contact suitable for brokering attribute release changes when users encounter failures accessing services because required information is not released.

There are three types of contacts in Federation metadata:

• end-user support contact: for end-user technical support but may also handle questions from users regarding attribute release policy, user privacy, etc.
• institutional technical contact: for direct communication between InCommon participants regarding technical issues such as troubleshooting software, systems, or networking issues
• institutional administrative contact: for direct communication between InCommon participants regarding non-technical issues such as attribute release policy, on-boarding issues, etc.

All are extremely important in different scenarios, and participants are encouraged to provide at least one of each type. At least one support contact is REQUIRED.

Here are a few potential use case scenarios that rely on contact information:

• A user authenticates successfully at the IdP and is subsequently redirected to the SP. The SP software, seeing that the SAML assertion does not contain the desired attributes, displays an error message that refers the user to the administrative contact at the IdP.

• In the previous scenario, in addition to displaying a message to the user, the SP software sends a back-channel message to an institutional administrative contact at the IdP, describing in detail the event that just occurred. The message includes a pointer to the SP's Requested Attributes in metadata.

• A user encounters and reports a technical failure while accessing a service. The SP's support staff determine that the user's IdP is misconfigured (e.g. its clock is off), and informs the technical contact.

• A user encounters and reports a technical failure while accessing a service. The SP's support staff determine that the user's environment is at fault, and assists the user in informing the support contact.

• A user authenticates successfully at the IdP and is subsequently presented with a consent page. The SP's Requested Attributes are displayed on the consent page, along with a link to the SP's Privacy Statement. An administrative contact at the SP is also displayed on the consent page, for those users who have questions about the SP's Requested Attributes and/or the Privacy Statement.

• When a user attempts to access a protected resource, the SP redirects the user to a centralized discovery service (or displays an embedded discovery interface). The discovery interface displays a fall back link with the text "My institution is not listed, what should I do?" Upon clicking the link, the user is presented with a secondary list of institutions. Selecting an institution from this list, a text area with a prepared message appears. The user edits the message (if desired) and presses the Send button, thereby sending the message to an administrative contact at the user's home institution.

Technical Details

Here is an example of an appropriate set of <md:ContactPerson> elements in metadata:

<md:ContactPerson contactType="support"
     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:EmailAddress>mailto:help_desk@example.org</md:EmailAddress>
  <md:TelephoneNumber>999-999-9999</md:TelephoneNumber>
</md:ContactPerson>
<md:ContactPerson contactType="technical"
     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:GivenName>Infrastructure Support Team</md:GivenName>
  <md:EmailAddress>mailto:infra-support@example.org</md:EmailAddress>
</md:ContactPerson>
<md:ContactPerson contactType="administrative"
     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:GivenName>Federation Policy Support</md:GivenName>
  <md:EmailAddress>mailto:fed-support@example.org</md:EmailAddress>
</md:ContactPerson>

Technical Requirements

• Each <md:EntityDescriptor> element SHOULD contain at least three contacts, that is, three <md:ContactPerson> elements with XML attributes contactType="support", contactType="technical", and contactType="administrative".
• Each <md:ContactPerson> element MUST contain at least one <md:EmailAddress> element.
• If a contact is a real person, the <md:GivenName> and <md:SurName> elements SHOULD reflect the person's real name.
• If a contact is a non-person (such as a mailing list), the <md:GivenName> element MAY contain a title or label, and <md:SurName> element SHOULD be omitted.