Guidelines for SAML metadata about your SP

This is version 0.9 of the guidelines for metadata about Service Providers to be included in the CLARIN Service Provider Federation.

We kindly ask operators to go through and apply these guidelines regularly (say, once every quarter of a year), in case the version of this document has changed since the last audit. If you fail to adhere to the guidelines, experience has shown that this will result in time-consuming difficulties with various Identity Federations. In contrast, following these guidelines helps you understand important technical aspects of your SP better while also allowing CLARIN to quickly enable your SP for wide use.

Conformance to the guidelines is automatically tested by the CLARIN ERIC SPF administration. The results are regularly communicated to SP operators (i.e., the technical contacts) and come in a matrix in which cells indicate either a pass or a fail for a test, with test name shorthands as column names. For your reference, the shorthands are in bold as prefix to relevant guideline rules.

Note 1: all XPath references using ./ are relative to the md:EntityDescriptor element that describes your SP in your SP file placed under: https://github.com/clarin-eric/SPF-SPs-metadata/tree/master/metadata

Note 2: This document does not pertain to your Shibboleth/SAML Service Provider configuration, but to the SAML metadata that describes it!

Guidelines for SAML metadata about your SP within the CLARIN Service Provider Federation

  1. First, please follow through: https://wiki.shibboleth.net/confluence/display/SHIB2/MetadataCorrectness
  2. Indent all elements with four spaces per level, and do not include empty lines. In other words, make sure visual and structural levels correspond everywhere. Do not use tabs as whitespace (f.i. between element attributes or in element/attribute values). Do not use newline characters or similar breaking characters other than one plain space character, anywhere. Newlines are to be used only after every element.
  3. Always (re)declare all namespace prefixes that you use. Stick to the following namespace prefixes:
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"
    xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"
    xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init"
  4. https_endpoints, saml2_support_with_http_post_endpoint: Support SAML 2.0, and provide a HTTP-POST endpoint for this. Make sure all endpoints (easiest definition: all URLs that your refer to) have the https scheme. Other schemes such as http are often rejected by identity federations.
  5. duplicate_keys: Do not repeat an X.509 certificate or key (henceforth 'key') if you use it for both signing and encryption. Instead, simply do not specify a use attribute ( ./md:SPSSODescriptor/md:KeyDescriptor/@use). Also make sure that X.509 certificates you include have a sufficiently distant expiration date. Please do not use X.509 certificates that are valid more than 5 years, because some Identity Federations do not want this. You are advised to generate a self-signed X.509 certificate: do not re-use an X.509 certificate you use for TLS ('https'). See also https://spaces.internet2.edu/display/InCFederation/X.509+Certificates+in+Metadata. Wildcard X.509 certificates (with an asterisk in the cn field) are not generally accepted, so please don't use them.
  6. https_logo: Include at least one logo for your SP at ./md:SPSSODescriptor/md:Extensions/mdui:UIInfo/mdui:Logo . The logos should at minimum meet the requirements listed here. That includes not using a 'data:' scheme URI but a 'https://' one. Suggested is to also include a logo of 500x300 pixels, PNG, transparent background to make it look nice for SURFconext as well.
  7. mdui_text: Supply the element ./md:SPSSODescriptor/md:Extensions/mdui:UIInfo. The child element mdui:DisplayName should be carefully chosen and spelled, and not exceed 33 characters. Please don't include the organization name here, but indicate the kind of applications/services that use this SP. The child element mdui:Description should be succinct, complete, correctly spelled and should not exceed 100 characters. Always provide all textual elements with an xml:lang attribute ('texts') in at least English, German and Finnish, if not in all languages spoken in the CLARIN consortia. If needed, you are free to use machine translation. This is strongly advised, because a number of national identity federations insist on texts in their native language(s). In the absence of your own, well-written texts, other persons will be making them up. Filling in such translations manually as we register your SP will also cost relatively more time. Supply mdui:Keywords using a space between keywords (and plus characters as spaces within keyword-phrases), e.g. CLARIN+organization language+resources corpus. Also determine an openly accessible web page in English that describes the applications that use your SP and refer to it in mdui:InformationURL.
  8. attributeconsumingservice: Supply the element ./md:SPSSODescriptor/md:AttributeConsumingService, including its child elements md:ServiceName, md:ServiceDescription and one or more md:RequestedAttribute . Also indicate with the isRequired attribute whether the attribute is critical or not. In case you don't need an attribute, the SAML metadata XSD schema does not support zero md:RequestedAttributes. In this case, do request a 'dummy' attribute with low privacy impact such as eduPersonTargetedID.
  9. https_discovery_and_requestinitiator: Supply the elements ./md:SPSSODescriptor/init:RequestInitiator and ./md:SPSSODescriptor/idpdisc:DiscoveryResponse. The former is useful for SP-initiated Single Sign On. The latter is useful even if your SP application is not using a non-embedded (e.g. the central CLARIN one) Discovery Service, it enables you to start using it across identity federations while it requires almost no effort from you and it imposes nothing on your application's mode of operation.
  10. dp_coc_entity_category, privacy_policy, attributeconsumingservice: Adopt the Data Protection Code of Conduct (DP-CoCo), assuming the country that hosts the SP is a European Union member, and attest to that with the official DP-CoCo Entity Category at ./md:Extensions/mdattr:EntityAttributes. Specify each attribute for each NameFormat you use (e.g. the SAML 2.0 and 1.1 ones). Irrespective of the DP-CoCo, it is obvious how important (as in legally) and beneficial (as in encouraging for your users and their IdPs) it is for you to formulate a (brief) privacy policy and refer to it in ./md:SPSSODescriptor/md:Extensions/mdui:UIInfo/mdui:PrivacyStatementURL. The privacy policy should explain why you require the attributes that you require and what you do with that information if you get them.
  11. contactpersons: Include ./md:ContactPerson elements, at least one with contactType="technical"; with contactType="administrative" and with contactType="support", each containing at least an element md:EmailAddress with  a 'mailto:' URI and (in any case) also a real md:GivenName and md:SurName. Please just specify the person who is mainly responsible, even if he/she won't be answering e-mails him-/herself.
  12. organization: Supply the element ./md:Organization and the child elements md:OrganizationName, md:OrganizationDisplayName and md:OrganizationURL, again, at least in English (xml:lang attribute). Put the full official name of your legal organization (thus, not a project or department name) in md:OrganizationName. Put the common name that users would most likely search for in md:OrganizationDisplayName, possibly an abbreviation if that meets said criterion.

  13. refeds_entity_category: Comply with the requirements of the REFEDS Research and Scholarschip Entity Category. These criteria are already covered by the other requirments in this guideline, but to a limited extent relate to aspects hard to test by the SPF such as the SAML MetadataProvider refresh interval in your SP's configuration. Mind to put their entity category alongside other entity categories in ./md:Extensions/mdattr:EntityAttributes.

General rule: whenever you are requested to supply a URL, it should 'work': only supply URLs which should result in a HTTP response with no HTTP error response status code). Don't supply it if the location isn't available (yet) or if it is prone to become a dead link later. Where the https scheme is not absolutely required of your URL, it is still preferred.

Do you have questions and suggestions? Then please e-mail spf /at/ clarin.eu.

Terms & Disclaimer