The Shibboleth Identity Provider (IdP) V4.x release introduced a new concept to the IdP, called the Attribute Registry. This new approach to managing how the IdP encodes (or decodes) attributes is described in this Shib IdP Wiki page. It also has a key role if you are using the Attribute Consent feature of the IdP to ask your users if they are ok with various attributes being released to a service. Following are some questions and answers about why this new concept was introduced and how it impacts your management of the Shib IdP.
What is the Attribute Registry?
At its heart, it is a set of mapping rules for how to encode (package up) attributes to be returned in a SAML, CAS, OIDC, etc. response, and how to decode (unwrap) attributes that are being returned to your IdP from another IdP. (The latter being needed if you use the new SAML authentication flow to defer user authentication to another SAML IdP such as Azure AD.) It also contains the “labeling information” (the display name and description) for listing an attribute in a consent page, including supporting having multiple language variations that can be displayed. There is a new configuration file in the conf/directory (attribute-registry.xml), and a whole new directory in the conf/directory, the conf/attributes/ directory.
One analogy that may or may not be helpful is to think of the Attribute Registry as the shipping and receiving center for your “SSO factory”. It does the packaging up of attributes to be shared with services just before those attributes are “shipped out”, and it does the “receiving/unwrapping” of incoming attributes that have been returned to the IdP from another IdP (e.g. in a SAML response from Azure AD.) And it also “packages up the display of attributes” in a consent dialogue.
For example, to push that analogy a bit further, if you configure your IdP to defer authentication to Azure AD, think of the SAML response coming back from Azure as a “truckload of attributes” that are delivered to the receiving dock of your “IdP factory”. The Attribute Registry provides the listing of “attribute packages” you are willing to receive, and how to unpack them into a form ready to be used by your IdP. Your “IdP factory” might then make changes to what it received, and add other attributes from local sources (e.g. LDAP directory). Then the Attribute Registry provides the information on how to package the attributes into a set of “attribute packages” to be shipped off to the SP/application that sent the user to your IdP in the first place.
Why was the Attribute Registry concept introduced?
It was introduced because the model to date – having attribute encoders etc. listed directly in the attribute-resolver.xml/ attribute-resolver.xml file – has limitations and could not effectively support the growing range of features that Shibboleth IdP v4 now supports. And it helps prevent the resolver file becoming even more complex than it already is. Another advantage of the registry model is that it makes it easy to provide “bundles of attribute encoding/decoding rules” (transcoding rules) for a variety of new use cases, like receiving Azure AD claims or returning OIDC claims.
How do I know if I’m using the Attribute Registry?
If you are running any version of IdP 4.x, then you are indeed using the Attribute Registry. How much you are using it, though, depends entirely on whether you upgraded your IdP from an existing 3.x version, or if you did a new install of IdP 4.x, By default, upgrades make minimal use of the Attribute Registry, while new installs use it heavily.
I used the recommended upgrade process to get from 3.x to 4.x, how is the Attribute Registry being used?
If you upgrade (as per recommendations) from an IdP 3.x version of the IdP, your use of the Registry is relatively limited. The Attribute Registry is there “in the background”, and by default, it is just processing the existing AttributeEncoder rules in your attribute-resolver.xml/ file. And having AttributeEncoder rules embedded in yourattribute-resolver.xml/ file remains a fully supported feature, it is not deprecated – you do not have to switch away from using that approach. One thing you do need to be aware of is that if you make use of the “reload” command line (CLI) options (the bin/reload-service command or its curl/URL equivalent), then when you make any changes to the attribute-resolver.xml/ file, you now need to reload two (2) different services – both the resolver and the registry – to be sure all your changes are now active. I always use the curl/URL option for CLI actions, rather than needing to specify arguments on the bin/ .sh or .bat commands, so the commands I’d use now after a change to the resolver are these (adjust the scheme and port number to match your deployment):
- curl -s -k 'https://localhost/idp/profile/admin/reload-service?id=shibboleth.AttributeResolverService'
- curl -s -k 'https://localhost/idp/profile/admin/reload-service?id=shibboleth.AttributeRegistryResources'
I have a new install of IdP 4.x, how is the Attribute Registry being used?
A new install of IdP 4.x installs a conf/services.xmlfile that contains the following which did not exist in IdP 3.x:
<!--
This is suitable for new installs but will usually produce duplicate Attribute
output if a legacy resolver file is used that contains AttributeEncoders.
-->
<util:list id ="shibboleth.AttributeRegistryResources">
<value>%{idp.home}/conf/attribute-registry.xml</value>
<value>%{idp.home}/conf/attributes/default-rules.xml</value>
<value>%{idp.home}/conf/attribute-resolver.xml</value>
</util:list>
It is unlikely you’d ever make changes to the conf/attribute-registry.xmlfile, but you definitely want to take a look at the new conf/attributes/default-rules.xmlfile, which contains the following:
<!-- Default Attribute transcoding rules. -->
<!--
Many if not most of these attributes are not suited or may even be actively discouraged
from use in federated protocols, but this is merely a set of well-known definitions, not
a recommended set to support or use.
-->
<import resource="inetOrgPerson.xml" />
<import resource="eduPerson.xml" />
<import resource="eduCourse.xml" />
<import resource="samlSubject.xml" />
Those imports bring in sets of transcoding (encoding/decoding rules) for various collections of standard attribute schemas. You should take a look at those individual files to get a better sense of what is in them. And you should not change those provided resources themselves if you need to add attributes. You should instead use those as models to add in either new similar .xml files, or use .properties files added to the conf/attributes/custom directory (see the README file in that directory.) See this Shib wiki page for more details on adding your own rules. Changes to any of the files in the conf/attributes directory can be made live by reloading the shibboleth.AttributeRegistryResource service. E.g.
- curl -s -k 'https://localhost/idp/profile/admin/reload-service?id=shibboleth.AttributeRegistryResources'
My SAML responses suddenly have duplicate attributes in them, why is that?
That is an indication that you had an existing IdP 3.x and attribute-resolver.xmlfile, but instead of following the recommendation to upgrade, you instead installed a fresh copy of IdP 4.x and migrated your config. You were not supposed to do that. And one of the myriad of reasons to have not done that is exactly this problem – duplicate attributes. The reason for the duplicates is that you still have a bunch of AttributeEncoders in the attribute-resolver.xmlfile, but you also now have the full set of default Attribute Registry resources configured, which contain a bunch of attribute encoding rules which will also encode many of the same attributes – resulting in duplicates in your SAML responses. One simple solution to that problem, so that you do not need to go and remove all the existing AttributeEncoders in the attribute-resolver.xml file, is to simply “comment out” all the existing imports in the conf/attributes/default-rules.xmlfile:
<!--
<import resource="inetOrgPerson.xml" />
<import resource="eduPerson.xml" />
<import resource="eduCourse.xml" />
<import resource="samlSubject.xml" />
-->
That will prevent the use of all those default sets of encoding rules. If you still want to use some of those encoding rule files, simply do not comment out the ones you still want to use.
How do I start using the Attribute Registry for new use cases if I did an upgrade?
Let’s say you want to use some new features of the IdP like deferring authentication off to another SAML IdP (like Azure AD), or you want to start using the OIDC protocol. There are nice bundles of a starting set of transcoding rules for such that you can find provided on the Shib wiki (azureClaims.xml, or oidc-claim-rules.xml, the latter which is added if you install the OIDC OP plugin). But if you upgraded to IdP 4.x, your conf/services.xml file does not have the "shibboleth.AttributeRegistryResources" section in it (as shown above in the New Install topic). To take advantage of these new transcoding rule files, you can add that section to your conf/services.xmlfile. You might even want to do a “diff” between the latest distribution version of the services.xmlfile and your current version of it (find the latest distribution version in the dist/conf/directory) to see if there are additional changes you want to make to your services.xmlfile. But unless you are also going to remove AttributeEncoders from your attribute-resolver.xml, you’ll want to comment out the use of at least some of those default import files in the conf/attributes/default-rules.xmlfile (again as shown in the topic above) to avoid getting duplicate attributes. Once you have done this, you can add new import statements to make these new transcoding rule files (e.g azureClaims.xml, oidc-claim-rules.xml) available to the IdP – simply follow the existing examples in that conf/attributes/default-rules.xmlfile.
Should I convert all my existing encoding rules (AttributeEncoders in the attribute-resolver.xml file) to the new transcoding rule model?
That’s entirely up to you and what you find most easy to manage going forward. There are no plans to deprecate the approach of embedding AttributeEncoders in the attribute-resolver.xml file, and I personally find it convenient in most cases to not only leave the existing ones there, but to even add more when and if I have occasion to define new attributes in the resolver. I’m used to that approach, and like having it all together in one place. But if I was using the Consent feature, I might be more inclined to move everything to the new registry transcoding model. And I most definitely find the new model to be great when using new features like SAML authentication (deferring authentication to Azure AD) and OIDC. (In fact, you have no choice but to use the new model for SAML authentication, because in that case you are decoding incoming attributes, and that cannot be done within the attribute-resolver itself. The key thing to understand and remember is that you can combine the approaches, it is not just one or the other. Use what works best for you and your Shib IdP deployment.
