RFC 8409

The Entity Category Security Assertion Markup Language (SAML) Attribute Types ✨

RFC 8409 🎀 is an Independent Submission, and it's Informational 📚, so it's published for info, not as an Internet Standard. The editor is I. Young, Ed. (Independent), with co-authors L. Johansson (SUNET) and S. Cantor (Shibboleth Consortium). It's dated August 2018, and the ISSN is 2070-1721. There are no Obsoletes or Updates listed, so this doc doesn't replace or change any other RFC 🦋.

Abstract 💖

Okay so this doc describes two SAML entity attributes 💅. The first one lets you give an entity category membership semantics. The second one is for claiming you interoperate with, or support, entities in those categories 🫶.

This document is a product of the working group process of the Research and Education FEDerations (REFEDS) group 🌈.

Status of This Memo ✨

This is not an Internet Standards Track spec. It's published just for info 🌸.

This is a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor picked to publish it at their discretion, and they make no statement about how valuable it is for implementing or deploying 💅. Anything approved for publication by the RFC Editor is not a candidate for any level of Internet Standard. Check Section 2 of RFC 7841 for the details 🧚.

For the current status, errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc8409 🔥.

Copyright Notice 🌸

Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved 💜.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please read these carefully, because they spell out your rights and restrictions for this doc 🙈.

Table of Contents 📖

   1. Introduction ....................................................3
      1.1. REFEDS Document Process ....................................3
   2. Notation and Conventions ........................................4
   3. Entity Category Attribute .......................................4
      3.1. Syntax .....................................................4
      3.2. Semantics ..................................................5
      3.3. Entity Category Example ....................................6
   4. Entity Category Support Attribute ...............................7
      4.1. Syntax .....................................................7
      4.2. Semantics ..................................................7
      4.3. Entity Category Support Example ............................9
   5. IANA Considerations .............................................9
   6. Security Considerations .........................................9
   7. References .....................................................11
      7.1. Normative References ......................................11
      7.2. Informative References ....................................11
   Acknowledgements ..................................................12
   Authors' Addresses ................................................12

1. Introduction 🦋

This doc describes a SAML attribute called the "entity category attribute" 🎀. Its values stand for entity types or categories. When you use it with the SAML V2.0 Metadata Extension for Entity Attributes [SAML2MetadataAttr], each entity category attribute value is a claim that the entity labeled with it meets the requirements of the indicated category and is asserted to be a member of it ✨.

A relying party MAY use these category membership claims to set up policy for releasing attributes from an identity provider, to shape UI decisions like identity provider discovery, or for any other purpose 💅. Generally, what a membership claim is used for depends on the details of the category's definition, and those uses often end up written into the definition itself 🌈.

Entity category attribute values are URIs 🔗. So this doc doesn't set up a controlled vocabulary for those values. Any appropriate authority can define them, with no central registration needed. Other specs may come along later with management and discovery mechanisms for these values 🧚.

There's also a SAML attribute called the "entity category support attribute" 💜. It holds URI values that claim an entity supports and/or interoperates with entities in one or more categories. These values are defined alongside specific entity category attribute values, so entities in a category can find the peers that want to interact with them the way the category spec describes 🫶.

This doc doesn't specify any values for either the entity category attribute or the entity category support attribute 🙈.

1.1. REFEDS Document Process 🌸

The Research and Education FEDerations [REFEDS] group is the voice for what research and education identity federations worldwide need together 🌍. It's all about representing research and education needs in the ever-growing world of access and identity management 💅.

Every so often, REFEDS publishes a doc in the RFC Series 📚. These get published through the Independent Submission stream [RFC4844]. Even so, the REFEDS Working Group sign-off process has been followed for them, as the REFEDS Participant's Agreement [REFEDS.agreement] describes ✨.

This document is a product of the REFEDS Working Group process 🎀.

2. Notation and Conventions 📝

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as BCP 14 [RFC2119] [RFC8174] says, but only when they show up in all capitals like that 💖.

The notation "@example" is shorthand for an XML attribute named "example" 🧚.

3. Entity Category Attribute 💅

3.1. Syntax 🌈

Entity category attribute values MUST be URIs 🔗. We call these "category URIs" in this doc 💜.

It is RECOMMENDED to use http:-scheme or https:-scheme URIs 🌸. It's also RECOMMENDED that a category URI resolves to a human-readable doc that defines the category ✨.

Authorities defining entity categories MUST produce a spec for the entity category, and SHOULD arrange for the category URI to resolve to that spec in human-readable form 📚.

Authorities defining entity categories MAY version their category URIs where it makes sense 🦋. If they do, each version of the spec SHOULD clearly point to the latest version of the category URI, and therefore to the latest spec 🎀. The spec SHOULD also describe how the authority governs updates to it 💅.

When used in SAML metadata or protocol elements, the entity category attribute MUST be encoded as a SAML 2.0 Attribute element with @NameFormat set to urn:oasis:names:tc:SAML:2.0:attrname-format:uri and @Name set to http://macedir.org/entity-category 🔥.

A SAML entity gets associated with one or more categories by putting the Attribute element described here into the entity's metadata, using the metadata extension from [SAML2MetadataAttr] 🫶. In that extension, the Attribute element sits inside an mdattr:EntityAttributes element. That one sits directly inside an md:Extensions element, which sits directly inside the entity's md:EntityDescriptor 🧚.

This spec doesn't define what the entity category attribute means if it shows up anywhere else in a metadata instance or in any other XML document 🙈.

If the entity category attribute appears more than once in an entity's metadata, relying parties SHOULD read the combined set of attribute values as if they were all in one single entity category attribute 💜.

3.2. Semantics 💖

When an entity has the entity category attribute in its entity attributes, that's a series of claims, one for each attribute value, saying the entity is a member of each named category 🌸. What each claim actually means depends on how that category is defined ✨.

An entity can be claimed as a member of more than one category 🌈. In that case, the entity is claimed to meet each category's requirements independently, unless the category definitions say otherwise 💅.

This doc deliberately doesn't define "category", so the concept can stay as general as possible 🦋. Still, to be useful, category definitions SHOULD include the following where they apply 🎀:

• A definition of the authorities who may validly assert membership in the category. Some memberships can be self-asserted informally by the entity's owner, while others may need checking by third parties like the entity's home federation or some other registrar 📚.
• A set of criteria that let you objectively assess an entity's membership in the category 🔥.
• A definition of the processes valid authorities use to decide that an entity meets those membership criteria 🧚.
• A description of the anticipated uses of category membership by relying parties 💜.
• A statement on whether membership of the entity category applies to different SAML role descriptors, plus any relevant protocol support restrictions 🫶.

Entity categories SHOULD NOT be used to show the certification status of an entity for conformance with an identity assurance framework 🙈. For that, the SAML extension defined in [SAML2IDAssuranceProfile] SHOULD be used instead ✨.

If a category definition changes significantly, the new version SHOULD get a different category URI, so a relying party can tell the old and new versions apart 💅. That's exactly why authorities defining entity categories MAY use some form of versioning for category URIs 🌈. When they do, each version of the entity category MUST be treated as a separate URI 🦋.

No ordering relation is defined for entity category attribute values 🎀. Entity category attribute values MUST be treated as opaque strings when they're compared 💖. In particular, if the spec defining the entity category depends on versioning of the category URI, a relying party MUST NOT assume any particular ordering between different versions of the category URI 😭. Any order between versions MUST be spelled out in the spec 👑.

3.3. Entity Category Example 🎀

Okay so here's a quick example bestie 💖 This is an md:EntityDescriptor for an entity with the entityID https://service.example.com/entity, and it's giving SAML metadata realness ✨

   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
     entityID="https://service.example.com/entity">
     <md:Extensions>
       <mdattr:EntityAttributes
         xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
         <Attribute xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
           NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
           Name="http://macedir.org/entity-category">
           <AttributeValue
             >http://example.org/category/dog</AttributeValue>
           <AttributeValue>urn:oid:1.3.6.1.4.1.21829</AttributeValue>
         </Attribute>
       </mdattr:EntityAttributes>
     </md:Extensions>
     ...
   </md:EntityDescriptor>

4. Entity Category Support Attribute 🦋

4.1. Syntax 💅

Entity category support attribute values MUST be URIs. Such values are also referred to as "category support URIs" in this document. Bestie, every single one has to be a URI, no exceptions 😭

It is RECOMMENDED that http:-scheme or https:-scheme URLs are used; it is further RECOMMENDED that each such value resolves to a human-readable document defining the value's semantics. So the vibe is http or https URLs, and ideally they lead to a readable doc that explains what the value means 🌸

A given category URI MAY be associated with multiple category support URIs in order to allow for multiple forms of support, participation, or interoperation with entities in the category. The authority defining the category URI and category support URIs MUST clearly describe the relationship between (all versions of) the category URI and (all versions of) the category support URIs as applicable in the entity category specification. So one category can have a bunch of support URIs for different kinds of support 🎀 but the authority MUST spell out how they all connect, for every version. No mystery relationships allowed, periodt 💅

The entity category support attribute MUST be encoded as a SAML 2.0 Attribute element with @NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri and @Name http://macedir.org/entity-category-support. Super specific encoding, no wiggle room 🧚

Claims that a SAML entity implements support for one or more categories are represented by including the Attribute element described here in the entity's metadata through use of the metadata extension defined in [SAML2MetadataAttr]. In this extension, the Attribute element is contained within an mdattr:EntityAttributes element directly contained within an md:Extensions element directly contained within the entity's md:EntityDescriptor. So the nesting is very particular, like a Russian doll of XML 🪆 Attribute goes inside mdattr:EntityAttributes, which goes inside md:Extensions, which goes straight into the md:EntityDescriptor.

The meaning of the entity category support attribute is not defined by this specification if it appears anywhere else within a metadata instance or within any other XML document. So if it shows up somewhere random, this spec just doesn't define what it means there. Not our problem, bestie 🙈

If the entity category support attribute appears more than once in the metadata for an entity, relying parties SHOULD interpret the combined set of associated attribute values as if they all appeared together within a single entity category support attribute. So if it's repeated, the sensible move is to treat all the values as one big happy group 🫶

4.2. Semantics 🔥

The presence of the entity category support attribute within an entity's entity attributes represents a series of claims (one for each attribute value) that the entity supports peer entities in a category in a particular fashion. The precise semantics of such a claim depend on the definition of the category support URI itself. Category support claims will often be defined to be self-asserted. Each value is basically a claim that the entity supports its peers in some specific way, and what that really means is up to the support URI's own definition 👑

An entity may be claimed to support more than one category. In this case, the entity is claimed to meet the support requirements of each category independently unless otherwise specified by the category definitions themselves. So if it supports multiple categories, each one gets judged on its own, unless a category's definition says otherwise ✨

This document intentionally does not define "support" for a category, in order to leave the concept as general as possible. It is assumed that entity category definitions MAY define one or more category support URIs signifying particular definitions for "support" by peers as motivated by use cases arising from the definition of the category itself. Honestly this spec is keeping "support" super open-ended on purpose, so categories can define what it means for their own use cases 🌈

A common case is expected to be the definition of a single category support URI whose value is identical to the category URI. So the usual setup is one support URI that's exactly the same as the category URI 🍓

If significant changes are made to a category support definition, the new version SHOULD be represented by a different category support URI so that the old and new versions can be distinguished by a relying party. It is for this reason that authorities defining entity categories support MAY employ some form of versioning. When versioning is used, each version of the category support URI MUST be treated as a separate URI. Big changes mean a brand new URI, so relying parties can tell old from new. Versioning is allowed, and when it's used, every version is its own separate URI, no merging 💜

No ordering relation is defined for entity category support attribute values. Entity category support attribute values MUST be treated as opaque strings for the purpose of comparison. In particular, if the specification defining the category support URIs relies on versioning, a relying party MUST NOT assume any particular ordering between different versions of the category support URI. Any order between versions MUST be spelled out in the specification. So there's no built-in sorting, the values are just opaque strings when you compare them, and nobody gets to assume v2 comes after v1 unless the spec literally says so 😭

4.3. Entity Category Support Example 🌸

Here's the matching example, with an entityID of https://idp.example.edu/entity and two support URIs plus the OID value 🧚

   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
     entityID="https://idp.example.edu/entity">
     <md:Extensions>
       <mdattr:EntityAttributes
         xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
         <Attribute xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
           NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
           Name="http://macedir.org/entity-category-support">
           <AttributeValue
             >http://example.org/category/dog/basic</AttributeValue>
           <AttributeValue
             >http://example.org/category/dog/advanced</AttributeValue>
           <AttributeValue>urn:oid:1.3.6.1.4.1.21829</AttributeValue>
         </Attribute>
       </mdattr:EntityAttributes>
     </md:Extensions>
     ...
   </md:EntityDescriptor>

5. IANA Considerations 📋

This document has no IANA actions. Nothing to do for IANA here, bestie 🎀

6. Security Considerations 🔐

The presence of the entity category attribute within an entity's entity attributes represents a series of claims (one for each attribute value) that the entity is a member of the named categories. Before accepting and acting on such claims, any relying party needs to establish, at a level of assurance sufficient for the intended use, a chain of trust concluding that the claim is justified. Okay this section is SERIOUS 😭 Before a relying party trusts a category claim and acts on it, it has to build a chain of trust that's strong enough for what it's about to do 🔥

Some of the elements in such a chain of trust might include:

• The integrity of the metadata delivered to the relying party, for example, as assured by a digital signature.
• If the entity category attribute is carried within a signed assertion, the assertion itself must be evaluated.
• The policies and procedures of the immediate source of the metadata, in particular, any procedures the immediate source has with regard to aggregation of metadata from other sources.
• The policies and procedures implemented by agents along the publication path from the original metadata registrar. This may be determined by examination of the published procedures of each agent in turn or may be simplified if the entity metadata includes publication path metadata in mdrpi:PublicationPath elements as described in Section 2.3.1 of [SAML2MetadataRPI].
• The policies and procedures implemented by the original metadata registrar. The registrar's identity may be known implicitly or may be determined from the entity metadata if it includes an mdrpi:RegistrationInfo element and corresponding @registrationAuthority as described in Section 2.1.1 of [SAML2MetadataRPI].
• The definition of the category itself, in particular, any statements it makes about whether membership of the category may be self-asserted or may only be asserted by particular authorities.

Although entity category support attribute values will often be defined as self-asserted claims by the containing entity, the provenance of the metadata remains relevant to a relying party's decision to accept a claim of support as legitimate, and the specific definition of a support claim will influence the assurance required to act on it. Even when the entity says it about itself, where the metadata came from still matters, and the exact support definition decides how much assurance you need 💀

The conclusion that a claim of category membership or support is justified and should be acted upon may require a determination of the origin of the claim. This may not be necessary if the immediate source of the metadata is trusted to such an extent that the trust calculation is essentially delegated to it. So you might need to figure out where the claim started, or you might not if the source you got it from is trusted enough to do that math for you 🫶

In many cases, a claim will be included in an entity's metadata by the original metadata registrar on behalf of the entity's owner, and the mdrpi:RegistrationInfo element's @registrationAuthority is available to carry the registrar's identity. However, any agent that is part of the chain of custody between the original registrar and the final relying party may have added, removed, or transformed claims according to local policy. For example, an agent charged with redistributing metadata may remove claims it regards as untrustworthy or add others that were not already present if they have value to its intended audience. Often the registrar adds the claim for the owner, and @registrationAuthority tells you who the registrar was. BUT every agent in the middle could have changed things along the way, like dropping or adding claims 👀

7. References 📚

7.1. Normative References 💖

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [SAML2MetadataAttr]
              Cantor, S., Ed., "SAML V2.0 Metadata Extension for Entity
              Attributes Version 1.0", August 2009,
              <http://docs.oasis-open.org/security/saml/Post2.0/
              sstc-metadata-attr-cs-01.pdf>.

   [SAML2MetadataRPI]
              La Joie, C., Ed., "SAML V2.0 Metadata Extensions for
              Registration and Publication Information Version 1.0",
              April 2012, <http://docs.oasis-open.org/
              security/saml/Post2.0/saml-metadata-rpi/v1.0/cs01/
              saml-metadata-rpi-v1.0-cs01.pdf>.

7.2. Informative References ✨

   [REFEDS]   "Research and Education FEDerations (REFEDS) Group",
              <http://www.refeds.org/>.

   [REFEDS.agreement]
              Research and Education Federations, "REFEDS Participant's
              Agreement",
              <https://refeds.org/about/refeds-participants-agreement>.

   [RFC4844]  Daigle, L., Ed. and Internet Architecture Board, "The RFC
              Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844,
              July 2007, <https://www.rfc-editor.org/info/rfc4844>.

   [SAML2IDAssuranceProfile]
              Morgan, RL., Ed., Madsen, P., Ed., and S. Cantor, Ed.,
              "SAML V2.0 Identity Assurance Profiles Version 1.0",
              November 2010, <http://docs.oasis-open.org/security/saml/
              Post2.0/sstc-saml-assurance-profile-cs-01.pdf>.

Acknowledgements 🫶

This work has been a collaborative effort within the REFEDS and MACE-Dir communities. Special thanks to the following individuals (in no particular order):

• RL 'Bob' Morgan
• Ken Klingenstein
• Keith Hazelton
• Steven Olshansky
• Mikael Linden
• Nicole Harris
• Tom Scavo

Authors' Addresses 💌

Ian A. Young (editor) Independent

Email: ian@iay.org.uk

Leif Johansson SUNET

Email: leifj@sunet.se

Scott Cantor Shibboleth Consortium

Email: cantor.2@osu.edu