Definitions and terminology
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 RFC 21191.
Federation, Identity Federation: An association of organisations that come together to securely exchange information as appropriate about their users and resources to enable collaborations and transactions.
South African Identity Federation, SAFIRE: A federation established to serve the South African research and education community, and operated by the Tertiary Education and Research Network of South Africa, NPC.
Federation Participant, Participant: An organisation that has joined the Federation by completing and signing a participation agreement in writing. Federation Participants MAY also be members of the Federation governance structures.
Federation Operator: Organisation providing the infrastructure for Authentication and Authorisation to Federation Participants.
Entity: A discrete component that a participant wishes to register and describe in metadata. This is typically an Identity Provider or Service Provider.
Registered Representatives: Individuals authorised to act on behalf of the participant. These may take on different roles with different rights attached to them.
This document describes the metadata registration practices of the South African Identity Federation (SAFIRE) with effect from the publication date.
All new entity registrations performed on or after that date SHALL be processed as described here until the document is superseded.
This most recent version of document SHALL be published on the Federation website at https://safire.ac.za/safire/policy/mrps/. Updates to the document SHALL be accurately reflected in entity metadata.
An entity that does not include a reference to a registration policy MUST be assumed to have been registered under an historic, undocumented registration practice regime. Requests to re-evaluate a given entity against a current MRPS MAY be made to the Federation Operator.
Participants in the South African Identity Federation are eligible to make use of SAFIRE’s registrar to register entities. Requests from other sources SHALL NOT be considered.
All participants MUST sign an appropriate participation agreement. Copies of the template agreement, and the process for becoming a participant are documented at https://safire.ac.za/safire/policy/participation/.
The Federation Operator will consider requests from service providers to become Participants only after they’ve shown the support of at least one participating identity provider, which MAY be the same organisation. In general it is expected that service providers SHOULD be domiciled or have substantive representation in the Republic of South Africa. However requests from international parties MAY be considered if there is no viable alternative Federation or if technical considerations require it.
The registration process attempts to verify the legal status of prospective participants against public records such as the higher education management information system, the companies register, or tax registration. In cases where the Participant is already a participant in the South African NREN, these processes MAY be short-circuited.
The process also establishes a canonical name for the Federation Participant. The canonical name of a Participant MAY change during the participation period, for example as a result of corporate name changes or mergers. The Participant’s most recent recorded canonical name is disclosed in the entity’s
Metadata for all entities registered by SAFIRE SHALL make use of the SAML-Metadata-RPI-V1.02 metadata extension to indicate that SAFIRE is the registrar for the entity and to detail the version of the MRPS statement that applies to the entity. The following is a non-normative example:
<md:Extensions xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"> <mdrpi:RegistrationInfo registrationAuthority="https://safire.ac.za"/> <mdrpi:RegistrationPolicy>https://safire.ac.za/safire/policy/mrps-v20160901</mdrpi:RegistrationPolicy> </md:Extensions>
Entity Eligibility and Validation
The process by which a Federation Participant can register an entity is described at: https://safire.ac.za/participants/
Values of the entityID attribute registered MUST be an absolute URI using the http or https schemes. https-scheme URIs are RECOMMENDED to all participants.
http-scheme and https-scheme URIs used for entityID values MUST contain a host subcomponent whose value has corresponding resource records in the domain name system.
The right to use a URI in an entityID SHOULD be established in one of the following ways:
- The Federation Participant demonstrates the right to use the host part of a URL by means of domain validation.
- In the case of multi-tenanted providers, such as software-as-a-service or cloud-hosted solutions, all of the following apply:-
- The format of an entityID is well-known and contains a unique identifier for each specific tenant. Such an identifier could be contained within the path or query subcomponents of a URL, or as a unique subdomain of the domain name identified in the host subcomponent;
- There is reasonable certainty that the unique identifier for a tenant is both persistent and is not reassigned; and
- The tenant’s unique identifier can be directly associated with the Participant in one of the following ways:
- The solution provider has a lookup or API service that returns either the canonical name of the Participant or a domain name the Participant has the right to use; or
- A Registered Representative of the Participant attests to the Participant’s right to use the entityID; and can demonstrate operational control of the tenant by means of login to a protected resource that displays both the tenant’s unique identifier from the entityID, as well as the canonical name of the Participant or a domain name the Participant has the right to use.
For Identity Provider entities, scopes MUST be rooted in the DNS domain name space, expressed in lowercase. Multiple scopes are allowed.
The right to use a particular scope SHALL be established by means of domain validation.
Regular expressions representing multiple scopes MAY be used, but all DNS domains covered by the expression SHALL be included in checks by the Federation Operator for the member’s right to use those domains. For these checks to be achievable by the Federation Operator, the set of DNS domains covered by the regular expression MUST end with a domain under a suffix listed in the Public-Suffix-List3 — that is, a literal ‘.’, followed by at least two DNS labels separated by literal ‘.’s (representing a domain to be validated as “owned” by the entity owner), and ending with a ‘$’ anchor (e.g.
Where required, a Federation Participant’s right to use a domain name SHALL be established in one of the following ways:
- A Participant’s canonical name matches the registrant information shown in public WHOIS records held by the DNS registrar;
- A DNS registrar confirms the Federation Participant’s eligibility from privately-held information; or
- A Registered Representative of the Participant attests to the Participant’s right to use the domain name; and can demonstrate operational control of the domain name by completing Domain Control Validation 4 using any of the mechanisms commonly accepted by public certification authorities.
- A Participant MAY be authorised to make use of a specific domain name in writing from the domain owner on a per-entity basis. Such authorisation SHALL NOT be regarded as including authorisation for use of sub-domains.
On entity registration, the Federation Operator SHALL carry out entity validation checks. These checks MAY include:
- Ensuring all required information is present in the metadata;
- Ensuring metadata is correctly formatted;
- Ensuring URLs specified in the metadata are technically reachable;
- Ensuring protocol endpoints are properly protected with TLS / SSL certificates
Entities that meet the registration criteria for the Research-and-Scholarship-v1.25 entity category MAY request that their metadata reflect this.
Other entity categories MAY be introduced or supported on request, subject to Federation Participants demonstrating to the Federation Operator’s satisfaction that they meet the appropriate eligibility criteria.
Once a Participant has joined the Federation any number of entities MAY be added, modified or removed by the organisation.
Entity Change Requests
Any request for entity addition, change or removal from Federation participants MUST be communicated from or confirmed by their respective Registered Representatives. Communication of change happens via email.
Unsolicited Entity Changes
The Federation Operator may amend or modify the Federation metadata at any time in order to:
- Ensure compliance with this MRPS;
- Ensure the security and integrity of the metadata;
- Comply with inter-Federation agreements;
- Improve interoperability;
- Add value to the metadata.
Depending on the scope of such changes, they MAY be communicated to the Registered Representatives for the entity.
The Federation Operator may make metadata from its registry available to other federations for the purposes of inter-federation. Service Provider entities MUST explicitly opt in before their metadata is re-published in this way. Identity Provider and Attribute Authority entities MAY opt out if they do not wish for their metadata to be published in this way. The Federation’s own metadata SHALL always be re-published.
Most of the organisational and metadata checks are carried out manually. The Federation Operator will not knowingly introduce errors, but cannot be held responsible should any inadvertently be included in published metadata. Metadata is used at the consumer’s risk.
Acknowledgements & License
Parts of this work has been derived from works of others, including the REFEDS MRPS template6 document. This work is licensed under a Creative Commons Attribution 4.0 International License.
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. ↩︎
SAML V2.0 Metadata Extensions for Registration and Publication Information Version 1.0. 03 April 2012. OASIS Committee Specification 01. http://docs.oasisopen.org/security/saml/Post2.0/saml-metadatarpi/v1.0/cs01/saml-metadata-rpi-v1.0-cs01.html. ↩︎
The Public Suffix List. https://publicsuffix.org/. ↩︎
“Validation of Domain Authorization or Control” in “Baseline Requirements for the Issuance and Management of Publicly‐Trusted Certificates”, CA/Browser Forum. https://cabforum.org/baseline-requirements-documents/. ↩︎
Research and Scholarship Entity Category Version 1.2. 28 November 2014. Research and Education Federations. https://refeds.org/category/research-and-scholarship. ↩︎
Federation Operator Practice (FOP): Metadata Registration Practice Statement Document. Research and Education Federations. https://github.com/REFEDS/MRPS/blob/master/mrps.md. ↩︎