Consultation: MRPS Template v2

This document is billed as a template. There are plenty of "template text" within. This document also provides useful  metadata registration practices guidance. One might even say this document sets expectations across the REFEDS community. In attempting to do all this, there are places in this document where it's difficult to discern whether the text is "suggested template text" or "guidance". A clearer delineation between "template text" and "guidance" would be very helpful.

Given this consultation is mostly about changes to Section 5. I'll cite specific examples within Section 5 in the following comments. I encourage the editors to also review the rest of the document for similar ambiguities.

Splitting hair, mostly because the SAML Metadata spec actually does not require an EntityID to be "globally unique". See lines 216-217 in https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf. Suggest the following wording to describe "EntityID": 

"A persistent identifier used in SAML software configuration and databases to uniquely identify an Entity. An EntityID MUST be unique across all registered entities in an extended ecosystem (ala Federation)."

Then why not literally re-use the referenced portion of that SAML spec? That would yield (for "EntityID"):
"An identifier for SAML entities, unique across all entities that interact within a given deployment."
The second sentence ("For the purpose of this document ...") could remain when we change "such identifiers must be" to "such an identifier is". – Peter/ACOnet

The change also clarifies that this document expects a SAML implementation. In the REFEDS community, that's an assumed truth today. We might review that assumption, therefore impact to this document, in a future work item.

Not all federations require membership to be able to register services. There may be other registration criteria for services than membership. What should be descirbed in this section is how registration of entities is defined in the federation policy. The rest of the section is more or less ok due to that identity providers normally needs to be members from a larger trust perspective.

I don't think you can have a license (i.e., give others certain rights) without having a copyright statement (clarifying who is giving out those rights), cf. Before licensing.

Since REFEDS is not itself a legal entity, I'm not sure who would own the copyright for the template. The copyright for the MRPS for the federation should belong to the federation. We have added the following:

Copyright

[The copyright for the final MRPS should be listed as the federation or its operating entity.]

In line with my comment 16 also remove everything else that might need changing for local use but that's not essential to be present in the template, including the logo box (lines 1-6), the table with publication date and the version history (line 16) and the CC "license logo" (lines 32-33).

Those who insist on putting a logo in their MDRPS can certainly add one without us telling them where to do that. (It's certainly not required and no best practices to have a logo in there.)

There's no need for a version history within that document. Note that MDRPS documents are supposed to be referenced by the entities (in mdrpi:RegistrationPolicy XML elements in SAML 2.0 Metadata) that have been registered under a certain practice:

The <mdrpi:RegistrationPolicy> element is a URL to a localized registration policy of the registrar. The URL MUST represent a single, immutable, policy document.  Any changes made to an existing policy document MUST result in a new URL.

I.e., it's the unique URL that identifies a document (and version therof) and each of those versioned-by-URL documents does not need to carry a history of other document versions. Keep it simple.

The only reason I have a date-based identifier (think publication date or "document version") in my own MDRPS is because I generate those automatically in post-processing (I.e., the date is inserted when the document is generated/rendered) and those date-based identifiers serve as unique, immutable URLs for each version, as per the spec quoted above, e.g. version 2014-06-06. But I wouldn't have to show that date within the document for the document to be useful – the URL itself would help make it uniquely identify- and adressable. Which is what matters.

RFC2119 language doesn't make sense (to me) in a description of your own actual practices. (Your MDRPS is now a how-to document for your consistituency).
Suggest to get rid of any, cf. mailing list.

I'd suggest to remove all the "Review and remove this box" boxes that explain what a section is about and move that to a separate document, if that's even deemed necessary.
(If the provided example wording itself isn't sufficient in showing what a given section is about then we've failed on a much more fundamental level and need to change the actually suggested example wording, not merely prefix unintelligible text with black boxes of explanations.)

That would leave a much shorter and much more straightforward (example) practice statement that most people could use as is, without much (or any) editing in the most cases – except to replace occurances of "<url>" where those are unavoidable.

We have a version of this document available in Markdown format – which not only makes applying (or suggesting) changes easier for more people (instead of one person being in charge to update a "Microsoft Word" document and then generate PDFs from it) and also makes adoption by federation operators easier: Markdown can easily be converted to other formats as needed, e.g. using pandoc or (m)any suitable other tool.

Happy to help revert that process again to work the changes into the existing Markdown document.

is most useful for the largest audience. People can convert into markdown from there if they choose; they will almost certainly convert it to PDF to submit to eduGAIN and possibly HTML for their websites.

Besides RFC2119 language (see comment 15) I see no reason for the document text to be containing the URL at which it is being published. (If you can read this very document you have already found it and don't need a URL reference to it.)
Removing this sentence also avoid things that need changing for local adoption – or for yourself, over time.

We think having the URL here is useful because there's no certainty as to how someone got the document. They may have gotten it directly from eduGAIN rather than the website, and having the source can be useful.

We do agree that the second sentence after the URL reference is unnecessary and are removing it.

Not sure what "Updates to the documentation" would have effects on "entity metadata"? If anything I might rather point out that changed practices should be reflected in a new MDRPS document – which already follows from MDRPI section 2.1.2 as mention in comment 14 above.
Even after reading the black box above I'm not quite clear what the second sentence here is about. Remove.

"Registry" isn't used throughout the document, only one (lowercase) use on line 95. Given that the definition here is virtually unused and also semantically rather empty (registry: a system to register entities) we could probably remove it.

We agree. Removing this text.

We are also removing "Members of the Federation are eligible to make use of the Federation Operator’s registry to register entities. Registration requests from other sources SHALL NOT be accepted. "

Consistently write "Federation Member" with init caps (also within def of "Federation Policy" on line 69)

Same with "Federation Policy" which is written as "Federation policy" on line 102.

The "membership procedure" is referenced by a URL in line 98. The 2 paragraphs that folllow seem to either repeate or prescribe/mandate the content of the just referenced document, neither of which seems necessary/appropriate as content of this document.

For IDPs I feel this is missing mdui:DisplayName, which should be just as canonical a name for a Federation Member than md:OrganizationName (maybe more so, looking at DFN-AAI's use of md:OrganizationName).

Not sure what this paragraph (or calling a name "canonical") provides us with. The name is "canonical" (by fiat) but without any references to it maybe being unique (at least as unique as the entityID, see my addition to Albert's comment 11 or globally unique)?

Seems to be (from this and the comment before) that the only real content of section 3 is lines 95-98. At least I wouldn't miss anything that comes after.

Why should every fedop's MDRPS contain the same "non-normative example" XML how mdrpi:RegistrationInfo looks like? Remove everything after "entity." on line 131.
(If help for the fedop is needed to know how MDRPI works they can look up the spec or an FAQ-style document could be added to the REFEDS wiki. But this should not be needed here.)

"Variables" that need to be replaced should use a consistent format or marker, such as "<url>" so that they can be searched for or referenced more easily.

"interFederation" → interfederation

revise last line → "enable collaboration and transactions." Very minor point

revise → "An organisation that has joined the Federation by agreeing in writing to be bound by the Federation Policy.

revise → "The organisation ... "

"federation members" → "Federation Members"

"federation Operator" → "Federation Operator"

"member" → "Federation Member"

revise → "The system ..."

revise → "Individuals authorised to act on behalf of the Federation Member. Registered Representatives may take on different roles with different rights attached to each role."

Revise paragraph 1 → 

This section should briefly introduce the Metadata Registration Practice Statement (MRPS) and describe the document publication process. It is important to remember that you may wish to change and update your Metadata Registration Practice Statement over time. If changes are significant, you will publish metadata that has been processed against different practice statements. It is important that both the MRPS documentation and the metadata reflect the changes (see section 5). Federation Operators should publish previous MRPS versions to support change tracking.

First line:

"establishes" → "determines" ??

Last line:

add to end ", and whether there is a periodic process to review eligibility."

"registry" → "Registry"

"entities" → "Entities"

"Federation policy" → "Federation Policy"

"The Operator" → "The Federation Operator"

"databases" → "sources including (list examples here)."

"Federation member" → "Federation Member"

It seems like this could use some helper text to explain that the example should be updated a Federation-specific example. The provided example should be localised to something like:  registrationAuthority="http://aaf.edu.au" for AAF.

I'm basically echoing Peter's comment 24. I can easily see brand new federations getting this one wrong and just recycling the same example which doesn't really help anyone.

revise "While they tend to be discouraged, some Federations still permit URN-based entityIDs and may need to include additional wording to cover these cases" → 

"Some Federations permit URN-based entityIDs, and while generally discouraged, you will need additional wording if your Federation supports this entityID format."

"Values of the entityID attribute registered ..." →
"Values of the registered entityID attribute ..."

http-scheme and https-scheme →
HTTP-scheme and HTTPS-scheme

These need to be lowercase because that's what's in the URI schemes registry (https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml).

Revise last paragraph to:

If you have multiple roles under the Registered Representative category (e.g., management contacts, technical contacts, administrative contacts), detail the responsibilities of each role here.

revise →
"Any request for an addition, change or removal of an Entity by a Federation Member must be communicated from or confirmed by their respective Registered Representative."

Maybe must should be MUST here as well.

"interFederation"

This really should be a defined term in section 1. It should probably be "Interfederation" rather than "interFederation" too.

We don't think we need to define interfederation as it's only used once, but we do think it needs to stay consistent with what's in the eduGAIN constitution. We have added text to indicate that.

"will" → "shall" or "SHALL" ???

regarding endpoint TLS / SSL certificate protection: Besides Private CA, another option to consider are self-signed certificates commonly used on backchannel endpoints (typically port 8443).  While these are less common now, they still may be in use.  Perhaps the reference to private CA should be constrained to "browser-facing endpoints" ?

Domain validation: attestation.  In case where the Member is already well known to the Registrar (perhaps because of already being an NREN member), is the DNS validation required?  Could we have "reasonable certainty" as an option?

We put in what's sensible for most federations, but what's more up to the individual federation goes into guidance. We have added more flexibility for a federation to put in what they do

Garbled text at "Please ensure that any processes described here reflect your current practice any any published documentation currently available for your Federation". Substitute "in any" for "any any", perhaps?

The definition of the term "Federation Operator" is maybe a little incomplete ? It refers to an organisation providing the infrastructure underlying the federation, but I think it could be useful to include also something lile "and take cares of the management of the required operational side"

In the disclaimer box (to be then removed within the MRPS) at line 60 I would add thre following text: "Any part of text in this document written between brackets <> is meant to be replaced with actual values/characters within the MRPS to be publshed". 
As a matter of fact, I would use another color, like red, for all the text parts within brackets that will need to be replaced with actuial values: it would  improve readibility and usability of the document. So the disclaimer could be like "Any part of text in this document written in (e.g.) red and between brackets <> is meant to be replaced with actual values/characters within the MRPS to be publshed. 
As an example of what I mean, at line 84:

This document SHALL be published on the Federation website at: <url>

the bit "<url>" should be written in red 

As a general suggestion, I would use <red> for placeholders that need to be replaced , like url mentioned before, and <(blue)>  for free text, even lenghty text, that needs to be added. 

I would add "The procedure to become a member of a federation (both as Service Provider and as an Identity Provider) ...etc. " or this could be evern split into " The procedure to become a member of the federation as an Identity Provider is described <here> and the one to become member as a Service Provider is described <here>"

Verification is achieved by  <(describe process)>       - I would use <> () and blue.

I would add an example of what is meant by lines 152 to 172. It would really help clarifying the meaning of the various parts of this section. Make an example with a tenant with a given name, for a given cloud provider, for example. (Espacially about point 1 in the list)

Line 199-202 iw a bit fuzzy to me. What does it mean, in practice "reasonably likely to be embedded" ...:  I would rather request to mention explictly  what are the steps taken to ensure this is actually the case .

If Improve Interoperability in this case is a reference to assering Entity Categories, maybe this could be mentioned as an examle, by adding a text like "(e.g. Entity Categories)" - otherwise, in any case, I think it could be worth mentioning a couple of example of what is meant by that in this context

This is meant to be more than entity categories (though that is certainly a part of it). It's also about Baseline Expectations and other specific technical changes for each federation.

If the approach of using different font colors like red and blue is adopted, then the lines that require a different font color, in the current proposed template are, lines:

 84, 98, 107, 137, 231