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.
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.
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.
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):
A new install of IdP 4.x installs a conf/services.xml
file 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.xml
file, but you definitely want to take a look at the new conf/attributes/default-rules.xml
file, 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.
That is an indication that you had an existing IdP 3.x and attribute-resolver.xml
file, 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.xml
file, 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.xml
file:
<!--
<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.
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.xml
file. You might even want to do a “diff” between the latest distribution version of the services.xml
file 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.xml
file. 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.xml
file (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.xml
file.
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.