Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

comment #Line/Reference #Proposed Change or QueryProposer / AffiliationAction / Decision (please leave blank)
1General

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.

Albert Wu / InCommon
2135 - 137These lines are meant to be template text. Yes? i.e., a Federation Operator can/should fill-in the URL and use that text as is other wise. Albert Wu / InCommon
3142 - 148Is this templated text or guidance? These paragraphs assumes a federation only accepts URL formatted entityIDs. If it is guidance, it contradicts the guidance (text in the box) introducing Section 5. If it is templated text, it lacks balanced example illustrating how URN support should be handled.

Side note to this area: constraining entityID rules beyond SAML specification carries broader interoperability consequences. The need to validate domain alone isn't likely a strong enough argument to enforce such constraint. It is especially so given the rest of Section 5 provides guidance for "multi-tenanted providers, where DCV style domain validation doesn't work.  We need to be very cautious when making such statements. 
Albert Wu / InCommon
4150 - 173This is very useful. It does read like implementation guidance to a Federation Operator rather than template text within an MRPS though. Are these meant to be guidance?Albert Wu / InCommon
5154Should this only apply to "multi-tenanted providers"? What about a commercial product that is not cloud or multi-tenant that won't let its customer create custom entityIDs?Albert Wu / InCommon
6156 - 159This sentence describes several entityID format options. It might be easier to read if these options were listed in bullet form. Albert Wu / InCommon
7160 - 161An entityID should be the unique identifier to a service registered in its operating domain (ala federation) regardless of its implementation technology. A vendor-issued entityID almost by definition prevents the entityID from being truly persistent (It changes as soon as the service's technology changes). Is it worth pointing out here, as inline guidance or as a pointer to external materials?Albert Wu / InCommon
8162-163I understand why this is mentioned here, but this reads more like an Entity Validation rule, therefore belonging in 5.4.Albert Wu / InCommon
9175 - 219Confirming all this is meant to be template text. (They are also easily interpreted as guidance, for federations adopting this template. So...)Albert Wu / InCommon
1010Given the template asks the adopter to fill in the Federation name, It might be useful to leverage that to help make this template more "template": Insert somewhere near the top of this document the following:

"This the Metadata Registration Practice Statement of the < replace with federation name>. References to Federation (with capital F" is used within this document refers to <replace with federation name>."

Yes. Adding this sentence does affect phrasing in the Definitions section. I raise this example in addition to those in Section 5 to highlight the duo purpose nature of this document: Is this document a template first, or is it really a "metadata registration practices guidance" document?
Albert Wu / InCommon
1169

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.

Albert Wu / InCommon
1295-96

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.

Pål Axelsson / SWAMID
13front matter

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.

Peter / ACOnet
14front matter

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.

Peter / ACOnet
1563-65 ff.

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.

Peter / ACOnet
16everywhere

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.

Peter / ACOnet
17meta

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.

Peter / ACOnet
1884

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.

Peter / ACOnet
1984-85

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.

Peter / ACOnet
2069

"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.

Peter / ACOnet
21109,137,228

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.

Peter / ACOnet
22100-107

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.

Peter / ACOnet
23109-112

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.

Peter / ACOnet
24123-129

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.)

Peter / ACOnet
25231

"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.

Peter / ACOnet
26239

"interFederation" → interfederation

Peter / ACOnet
2769 Federation

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

John Scullen / Australian Access Federation
2869 Federation Member

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

John Scullen / Australian Access Federation
2969 Federation Operator

revise → "The organisation ... "

John Scullen / Australian Access Federation
3069 Federation Policy

"federation members" → "Federation Members"

"federation Operator" → "Federation Operator"

John Scullen / Australian Access Federation
3169 Entity

"member" → "Federation Member"

John Scullen / Australian Access Federation
3269 Registry

revise → "The system ..."

John Scullen / Australian Access Federation
3369 Registered Representatives

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."

John Scullen / Australian Access Federation
3476

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.

John Scullen / Australian Access Federation
3593

First line:

"establishes" → "determines" ??

John Scullen / Australian Access Federation
3693

Last line:

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

John Scullen / Australian Access Federation
3795

"registry" → "Registry"

John Scullen / Australian Access Federation
3896

"entities" → "Entities"

John Scullen / Australian Access Federation
39102

"Federation policy" → "Federation Policy"

"The Operator" → "The Federation Operator"

John Scullen / Australian Access Federation
40103

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

John Scullen / Australian Access Federation
41109

"Federation member" → "Federation Member"

John Scullen / Australian Access Federation
42123-129

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.

John Scullen / Australian Access Federation
43133

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."

John Scullen / Australian Access Federation
44142

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

John Scullen / Australian Access Federation
45145-147

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

John Scullen / Australian Access Federation
46221 

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.

John Scullen / Australian Access Federation
47228-229

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.

John Scullen / Australian Access Federation
48239

"interFederation"

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

John Scullen / Australian Access Federation
49243

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

John Scullen / Australian Access Federation
50155

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" ?

Vlad Mencl / Tuakiri / REANNZ
51164

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?

Vlad Mencl / Tuakiri / REANNZ