Entity Attributes

Entity Attributes?

Entity Attributes are an extension of SAML2 metadata. They allow to group IdPs, Attribute Authorities or SPs. Systems with common features, e.g. participation in a common project, can be labeled with Entity Attributes in metadata. Those names and values can then be used for filtering: For IdPs this allows unified attribute release to a specific group of SPs and/or the activation of SAML profiles based on Entity Attributes. SPs can use Entity Attributes to filter metadata and thus identify the IdPs they want to give access.

This Entity Attribute announces the Degree of Reliance of an Identity Provider.

dfn-aai-idp-metadata.xml
  <md:EntityDescriptor entityID="https://idp.scc.kit.edu/idp/shibboleth">
    <md:Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="https://www.aai.dfn.de" registrationInstant="2010-03-15T10:30:11Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.aai.dfn.de/en/join/</mdrpi:RegistrationPolicy>
        <mdrpi:RegistrationPolicy xml:lang="de">https://www.aai.dfn.de/teilnahme/</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <!-- ... -->
        <saml:Attribute Name="http://aai.dfn.de/loa/degree-of-reliance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>advanced</saml:AttributeValue>
        </saml:Attribute>
      </mdattr:EntityAttributes>
    </md:Extensions>

Sirtfi

This funny word is pronounced “certify”. It stands for “Security Incident Response Trust Framework for Federated Identity”. This Entity Attribute declares the commitment and ability of an IdP, AA, or SP operator to follow the rules of the Sirtfi Framework on how to act in case of security incidents. Please see the REFEDS website and our documentation on Sirtfi compliance in DFN-AAI (in German).

The Sirtfi Entity Attribute may only be used if the conditions put down in the framework are met. We check the following formal and technical criteria before unlocking the respective check box in the metadata administration tool:

  1. The metadata must contain a security contact. That address must not be a personal e-mail address of an individual.
  2. Sirtfi compliant institutions have to run the latest software version for their IdP or SP.
  3. The SSL configuration of the web server has to follow state-of-the-art best practice. We rely on the server test of ssllabs.com, grade A is required.
dfn-aai-edugain+sp-metadata.xml
  <md:EntityDescriptor entityID="https://cern.ch/login" xsi:schemaLocation="urn:oasis:names:tc:SAML:2.0:metadata saml-schema-metadata-2.0.xsd urn:mace:shibboleth:metadata:1.0 shibboleth-metadata-1.0.xsd http://www.w3.org/2000/09/xmldsig# xmldsig-core-schema.xsd">
    <md:Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="http://rr.aai.switch.ch/" registrationInstant="2014-07-29T13:17:52Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.switch.ch/aai/federation/switchaai/metadata-registration-practice-statement-20110711.txt</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <!-- ... -->
        <saml:Attribute Name="urn:oasis:names:tc:SAML:attribute:assurance-certification" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>https://refeds.org/sirtfi</saml:AttributeValue>
        </saml:Attribute>
        <!-- ... -->
      </mdattr:EntityAttributes>
    </md:Extensions>

Entity Categories

In the strict sense, an Entity Category is an Entity Attribute, too. Service Providers use Entity Categories to announce in metadata that they have certain demands or meet certain requirements. An SP can accounce any number of Entity Categories.

Identity Providers can announce their support of Entity Categories in metadata to tell SP operators that they release attributes based on an Entity Category. Please see https://wiki.refeds.org/display/ENT/Entity-Categories+Home for details.

Internationally, there are three Entity Categories in use. You can announce that your systems support them via the metadata administration tool. Note that you will only see the according check boxes once your system meets the technical requirements of the Entity Category.

The Entity Category GÉANT Data Protection Code of Conduct for Service Providers in EU/EEA is a declaration of a common commitment by Service Providers. They commit to dealing with end users' personal data that come in via SAML 2 according to the data protection guidelines in effect. Please see our separate page for background information.

The conditions that have to be met to use this EC are documented in the GÉANT Wiki. Our metadata administration tool checks whether you mdui:PrivacyStatementURL links to a document that explicitly references the Code of Conduct. In addition, the requested attributes must be announced in metadata.

IdPs wanting to release a list of attributes globally to Code of Conduct SPs should have an according filter policy configured.

Service Provider supporting research and scholarship interaction, collaboration or management may use the Entity Category Research and Scholarship. The conditions are listed with REFEDS. For you, the most important parts are the registration criteria (item no. 4) and the list of attributes (item no. 5).

The attribute filter policies for IdPs are documented here in our wiki.

We have not implemented the Entity Category Hide from Discovery in our metadata administration tool. IdPs thus cannot not it. However, SPs should be configured to support the EC (e.g. because of IdPs from other federations).

The following example shows an extract from SP metadata with three Entity Attributes: The SP commits to CoCo compliance, it offers a service for collaboration in research (or similar), and it belongs to the group of Clarin SPs.

dfn-aai-sp-metadata.xml
  <EntityDescriptor entityID="https://clarin.ids-mannheim.de/shibboleth">
    <Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="https://www.aai.dfn.de" registrationInstant="2013-10-24T13:14:25Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.aai.dfn.de/en/join/</mdrpi:RegistrationPolicy>
        <mdrpi:RegistrationPolicy xml:lang="de">https://www.aai.dfn.de/teilnahme/</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>http://www.geant.net/uri/dataprotection-code-of-conduct/v1</saml:AttributeValue>
          <saml:AttributeValue>http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
          <saml:AttributeValue>http://clarin.eu/category/clarin-member</saml:AttributeValue>
        </saml:Attribute>
      </mdattr:EntityAttributes>
    </Extensions>

The next example shows IdP metadata: The IdP releases attributes to CoCo compliant SPs, and it commits to the degree of reliance “Advanced”.

dfn-aai-metadata.xml
  <EntityDescriptor entityID="https://idp.hs-bremen.de/idp/shibboleth">
    <Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="https://www.aai.dfn.de" registrationInstant="2016-11-18T08:40:16Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.aai.dfn.de/en/join/</mdrpi:RegistrationPolicy>
        <mdrpi:RegistrationPolicy xml:lang="de">https://www.aai.dfn.de/teilnahme/</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <saml:Attribute Name="http://macedir.org/entity-category-support" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>http://www.geant.net/uri/dataprotection-code-of-conduct/v1</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="http://aai.dfn.de/loa/degree-of-reliance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>advanced</saml:AttributeValue>
        </saml:Attribute>
      </mdattr:EntityAttributes>
    </Extensions>

A custom Entity Category?

You can request the implementation of custom Entity Categories at hotline@aai.dfn.de.

In DFN-AAI, there are more Entity Categories used to express the affiliation to projects. We call them virtual subfederations for projects like bwIDM, Nds-AAI, or Virtuelle Hochschule Bayern. Here is a list of the implemented Entity Categories:

See the details here (in German).

This is the according metadata extract of an SP participating in bwIdM:

dfn-aai-sp-metadata.xml
  <EntityDescriptor entityID="https://bw-support.scc.kit.edu/secure">
    <Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="https://www.aai.dfn.de" registrationInstant="2013-05-29T12:16:37Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.aai.dfn.de/en/join/</mdrpi:RegistrationPolicy>
        <mdrpi:RegistrationPolicy xml:lang="de">https://www.aai.dfn.de/teilnahme/</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>http://aai.dfn.de/category/bwidm-member</saml:AttributeValue>
        </saml:Attribute>
      </mdattr:EntityAttributes>
    </Extensions>

The metadata of an IdP taking part in bwIdM and committing to the Degree of Reliance “Advanced” look like this:

dfn-aai-metadata.xml
  <EntityDescriptor entityID="https://mylogin.uni-freiburg.de/shibboleth">
    <Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="https://www.aai.dfn.de" registrationInstant="2009-05-26T08:35:10Z">
        <mdrpi:RegistrationPolicy xml:lang="en">https://www.aai.dfn.de/en/join/</mdrpi:RegistrationPolicy>
        <mdrpi:RegistrationPolicy xml:lang="de">https://www.aai.dfn.de/teilnahme/</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>http://aai.dfn.de/category/bwidm-member</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="http://aai.dfn.de/loa/degree-of-reliance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>advanced</saml:AttributeValue>
        </saml:Attribute>
      </mdattr:EntityAttributes>
    </Extensions>

This extract shows metadata of an IdP from eduGAIN (from the UK federation) where users can self-register.

dfn-aai-edugain+idp-metadata.xml
  <md:EntityDescriptor entityID="https://indiid.net/idp/shibboleth">
    <md:Extensions>
      <mdrpi:RegistrationInfo registrationAuthority="http://ukfederation.org.uk" registrationInstant="2014-11-07T16:35:40Z">
        <mdrpi:RegistrationPolicy xml:lang="en">http://ukfederation.org.uk/doc/mdrps-20130902</mdrpi:RegistrationPolicy>
      </mdrpi:RegistrationInfo>
      <mdattr:EntityAttributes>
        <saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue>http://aai.dfn.de/category/public-idp</saml:AttributeValue>
        </saml:Attribute>
        <!-- ... --->
      </mdattr:EntityAttributes>
    </md:Extensions>

This Shibboleth SP filters metadata to allow only IdPs from the bwIdM project:

shibboleth2.xml
<MetadataProvider type="XML"
     uri="http://www.aai.dfn.de/fileadmin/metadata/dfn-aai-metadata.xml"
     backingFilePath="dfn-aai-metadata.xml" reloadInterval="3600">
   <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" />
   <MetadataFilter type="Whitelist" matcher="EntityAttributes">
         <saml:Attribute Name="http://macedir.org/entity-category"
                   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue>http://aai.dfn.de/category/bwidm-member</saml:AttributeValue>
        </saml:Attribute>
   </MetadataFilter>
   <MetadataFilter type="EntityRoleWhiteList">
      <RetainedRole>md:IDPSSODescriptor</RetainedRole>
   </MetadataFilter>
</MetadataProvider>

This Shibboleth SP filters metadata to remove IdPs with self-registration:

shibboleth2.xml
<MetadataProvider type="XML"
     uri="http://www.aai.dfn.de/fileadmin/metadata/dfn-aai-edugain+idp-metadata.xml"
     backingFilePath="dfn-aai-edugain+idp-metadata.xml" reloadInterval="3600">
   <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" />
   <MetadataFilter type="Blacklist" matcher="EntityAttributes">
         <saml:Attribute Name="http://macedir.org/entity-category"
                   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue>http://aai.dfn.de/category/public-idp</saml:AttributeValue>
        </saml:Attribute>
   </MetadataFilter>
   <MetadataFilter type="EntityRoleWhiteList">
      <RetainedRole>md:IDPSSODescriptor</RetainedRole>
   </MetadataFilter>
</MetadataProvider>

This Shibboleth SP filters metadata to only work with IdPs committing to the Degree of Reliance “Advanced”:

shibboleth2.xml
<MetadataProvider type="XML"
     uri="http://www.aai.dfn.de/fileadmin/metadata/dfn-aai-idp-metadata.xml"
     backingFilePath="dfn-aai-idp-metadata.xml" reloadInterval="3600">
   <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai.pem" />
   <MetadataFilter type="Whitelist" matcher="EntityAttributes">
         <saml:Attribute Name="http://aai.dfn.de/loa/degree-of-reliance"
                   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue>advanced</saml:AttributeValue>
        </saml:Attribute>
   </MetadataFilter>
</MetadataProvider>

This IdP filter policy releases a list of attributes to bwIDM Service Providers:

attribute-filter.xml
<AttributeFilterPolicy id="BwIdm">
   <PolicyRequirementRule xsi:type="EntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://aai.dfn.de/category/bwidm-member" />
   <AttributeRule attributeID="bwidmOrgId" permitAny="true"/>
   <AttributeRule attributeID="mail" permitAny="true"/>
   <AttributeRule attributeID="givenName" permitAny="true"/>
   <AttributeRule attributeID="sn" permitAny="true"/>
   <AttributeRule attributeID="o" permitAny="true"/>
   <AttributeRule attributeID="uid" permitAny="true"/>
   <AttributeRule attributeID="eduPersonPrincipalName" permitAny="true"/>
   <AttributeRule attributeID="eduPersonScopedAffiliation" permitAny="true"/>
   <AttributeRule attributeID="eduPersonEntitlement">
      <PermitValueRule xsi:type="ValueRegex" regex="^http://bwidm\.de/entitlement/.*$" />
   </AttributeRule>
</AttributeFilterPolicy>

Find more examples on the page about Attribute Configuration (in German).

For further reading, please consult the Shibboleth Wiki:

  • Last modified: 7 weeks ago