Requirements for SAML2 Identity Providers

This page documents the history of SAFIRE’s Requirements for SAML2 Identity Providers and will display the most recent version. You should always reference this page when linking to the Requirements for SAML2 Identity Providers, unless you intend to link to a specific, versioned document.

Changes to the Requirements for SAML2 Identity Providers that are purely technical must reach rough consensus/no opposition among SAFIRE’s service advisory group. Changes to the administrative requirements are synchronised with the Metadata Registration Practice Statement.

Version History

Requirements for SAML2 Identity Providers v20231130

Changes to the Requirements for SAML2 Identity Providers that are purely technical must reach rough consensus/no opposition among SAFIRE’s service advisory group. Changes to the administrative requirements are synchronised with the Metadata Registration Practice Statement. This version reached rough consensus on 30 November 2023.

The following describes the technical and administrative checks made before an identity provider is admitted into the SAFIRE federation within the SAML2 Technology Profile. It also serves as a checklist for identity provider operators for assessing their readiness to participate.

Metadata

In order to be included in the federation registry, identity provider metadata:-

  • MUST1 have an entityID that is a URL (well-known location). The URL SHOULD use the https scheme2, and it is RECOMMENDED that valid metadata be available at this URL.
  • MUST use secure (https) end-points for any <md:SingleSignOnService>, <md:SingleLogoutService> or <md:ArtifactResolutionService>.
  • MUST contain <shibmd:Scope> elements detailing every possible scoping value (domain) for eduPersonPrincipalName and eduPersonScopedAffiliation. All scopes MUST be rooted in the DNS domain name space, expressed in lowercase, and those domains MUST be owned by the organisation (or have written confirmation from the domain owner). Please see the “Scope Format” section of the Metadata Registration Practice Statement for normative requirements about the use of scopes.
  • MUST contain an <md:Organization> element, where:
    • <md:OrganizationName> MUST reflect the legal name of the juristic person.
    • <md:OrganizationDisplayName> MUST be present and SHOULD reflect a commonly known or shortened version of the organisation’s name.
    • <md:OrganizationURL> MUST contain the organisation’s web site address.
  • MUST contain at least one <md:ContactPerson> of contactType="technical" and SHOULD contain one of contactType="support". Where <md:EmailAddress> is given this SHOULD be a role account rather than an individual.
  • MUST contain at least one <md:ContactPerson> conforming to the REFEDS Security Contact Metadata Extension that reflects the entity’s security contact(s). It is further RECOMMENDED that entities consider whether they can attest Sirtfi compliance.
  • MUST contain an <mdui:UIInfo>, with at least the following elements set:
    • <mdui:DisplayName> — meaningful name for the identity provider.
    • <mdui:Description> — short (max 140 chars) description of the purpose.
    • <mdui:Logo> — a logo representing the identity provider and that is identifiable to its end users. Logos MUST be either served from a secure (https) server or expressed as a data: URI3. At least one logo SHOULD have an aspect ratio as close to 1:1 as possible and SHOULD be at least 100x100 pixels (although 300x300 is RECOMMENDED). Ideally, logos should be smaller than 40KB.
  • It is RECOMMENDED that <mdui:PrivacyStatementURL> be set and point at the organisation’s privacy policy. This MAY be required in future.
  • SHOULD NOT contain a <mdrpi:RegistrationInfo> element (any existing one SHALL be removed by the federation aggregator).
  • Certificates included in <ds:X509Certificate> elements and used for assertion signing or encryption:
    • SHOULD be self-signed.
    • MUST use public keys that contain least 2048 bits (RSA) or 256 bits (EC). It is RECOMMENDED that new RSA deployments use key lengths of at least 3072 bits.
    • MUST have a Validity Period4 of more than 1 year. Certificates SHOULD be replaced before they expire.
    • MUST NOT reuse private key material for public-facing web servers or other non-SAML purposes.
  • Web server certificates used for end-points MUST use PKI that is reasonably likely to be embedded in the browser of all users of the identity provider. Unless an explanation is provided, these SHALL be tested against the root CA lists of common browsers.
  • Where cryptographic signatures are required in SAML, these MUST NOT use algorithms based on MD5 or SHA1; use of RSA-SHA256 is RECOMMENDED.

Note: SAFIRE curates metadata to ensure both technical correctness and compliance with administrative controls. Changes to metadata are not automatically propagated. Organisations that need to make changes to their metadata need to submit a change request.

Language and Localisation

The SAML metadata specification allows display elements such as <md:OrganizationName> to be localised by using the xml:lang attribute to specify a BCP 475 language code. In common with other federations worldwide, English (xml:lang="en") MUST always be included and will be used as the default when no localised version is available.

It is strongly RECOMMENDED that official translations of organisation, display, or service names be included in metadata. In particular, prominent South African languages such as isiZulu (zu), isiXhosa (xh) and/or Afrikaans (af) are encouraged.

Attributes

  • The minimum attributes MUST be provided for all users; the Federation hub will generate an error should these not be provided for a particular user.
  • It is strongly RECOMMENDED that identity providers provide as many attributes as they are able.
  • The eduPersonPrincipal name attribute supplied by the identity provider is used to generate a persistent NameID. For this reason,  in addition to the eduPerson schema requirements, the eduPersonPrincipalName provided to the Federation MUST NOT be reassigned.
  • It is RECOMMENDED that attribute assertions are NOT encrypted. Such encryption is unnecessary given the requirement for an encrypted transport (https endpoints) and makes debugging difficult.

Technical

  • Clocks MUST be synchronised via the Network Time Protocol (NTP; SNTP) or equivalent such that they ultimately derive their time from the South African master clock maintained by the National Metrology Institute of South Africa or an acceptable alternative (e.g. za.pool.ntp.org).
  • Logs of successful authentications MUST be retained for at least 184 days.
  • Federation metadata SHOULD be refreshed at least once per day and MUST be refreshed at least once per cacheDuration.

Administrative

  • Participants that are not already signatories of the REN Service Agreement MUST provide documentary proof of legal name by means of one of the following:
    • CIPC registration certificate;
    • Trust deed;
    • SARS tax clearance certificate;
    • NPO registration; OR
    • Any other mutually acceptable means.
  • Participants MUST have signed a Participation Agreement.
  • Written permission MUST be provided for the use domains in <shibmd:Scope> if not verifiable by whois.
  • Each entity must be accompanied by a separate registration request form, including:
  • Only one <md:IDPSSODescriptor> per juristic person will be registered.

  1. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14↩︎

  2. Rescorla, E., “HTTP Over TLS”, RFC 2818, DOI 10.17487/RFC 2818, May 2000 ↩︎

  3. Masinter, L., “The ‘data’ URL scheme”, RFC 2397, August 1998. ↩︎

  4. From RFC 5280: “The period of time from notBefore through notAfter, inclusive.” ↩︎

  5. Phillips, A., Ed., and M. Davis, Ed., “Tags for Identifying Languages”, BCP 47, September 2009 ↩︎

South African Identity Federation