How to get the Organisation Display Name of an AAI User as “Free” Attribute

Have you ever wanted to show the organisation name of an authenticated AAI user in the web application protected by a Shibboleth Service Provider? For example on an event registration web page in order to see from which organisations users registered or – like in the screenshot below – to show the authenticated user himself with which – of potentially many – AAI account he has logged in?

LoggedInAAIUser

If so, you might first have consulted the AAI Attribute Specification that contains the definitions of all the AAI attributes that are supported in the SWITCHaai federation. There you would have searched for potential candidate attributes that contain the desired information from which organisation a user is from. You certainly would have found the swissEduPersonHomeOrganisation attribute and its international version the schachHomeOrganisation attribute. But both of them “only” contain the domain name of an organization (e.g. “unil.ch” or “uzh.ch”) because they are primarily used to perform access control (e.g. “require shib-attr homeOrganization switch.ch ethz.ch”). Displaying the domain name of a user’s organisation does the job but is not very human-readable. Who would know by heart that the domain name “hftm.ch” represents the “Höhere Fachschule für Technik Mittelland“?

There is a much better solution than using one of the above two attributes and what’s best: You don’t need to request an additional attribute for your service! You will just get the organisation name – as well as other data about the user’s organisation –  for “free”! From where would you get that information? Remember that all Identity and Service Providers in SWITCHaai need to know who else is part of the federation. To know the other federation participants, all AAI services automatically download the federation metadata file once per hour. The metadata file contains a description of all the other AAI organisations and services. This description not only includes the technical information (e.g. identifier, certificates, endpoint URLs) but it also contains non-technical information like a service or organisation name,  a description as well as contact information. This information is available for all entities in the SWITCHaai federation.

So, how would an AAI service then get the organisation name of an authentication user’s organisation? Well, this information just has to be read from the federation metadata. Conveniently, the Shibboleth Service Provider (since version 2.5) can read this information from metadata and provide it to web applications like any other AAI attribute. How this can be done is described on the Shibboleth Service Provider Attribute Extractor wiki page in detail.

The short version goes as follows; to show a user’s organisation display name, the following attribute extractor would have to be added to the shibboleth2.xml configuration:

<AttributeExtractor  type="Metadata" DisplayName="displayName"/>

Additionally, one has to add a metadata prefix to the ApplicationDefaults element.

<ApplicationDefaults metadataAttributePrefix="Meta-" ... >

These two changes in the shibboleth2.xml configuration file instruct the Shibboleth Service Provider to make the organisation’s display name (e.g. in my case “SWITCH”) of an authenticated user available to web applications. A web application that wants to read and use this attribute just has to read it from the web server environment like any other AAI attribute. For example a PHP application would read it from $_SERVER['Meta-displayName'].

When showing the organisation name of a user, one has to consider that its length varies. It can be very short (e.g. “SWITCH”) but it also can also be very long (e.g. “Institut de hautes études internationales et du développement“). This should be taken into account when designing the web page.

There is more good news! As you can imagine, metadata contains more information than just the display name of the organisation of an authenticated user. The Shibboleth Metadata Attribute Extractor can also show an organisation’s web page URL, information URL, privacy statement URL, support contact information and even the organisation logos. How this looks like, can be seen on the AAI Attribute Viewer or on the following screenshot:

MetadataAttributes

And finally, one last goodie: The above configuration changes don’t have to be applied manually. All you have to do to get the organisation display name and the other information for free, is to enable a checkbox when configuring your Service Provider. The Shibboleth Service Provider Configuration Guide for SWITCHaai will configure this automatically if you check the checkbox “Enable Metadata Attributes Support” in the setup section at the top of the guide as is shown in the screenshot below.

ShibbolethSPAdvancedConfiguration

Author: Lukas Hämmerle

I'm a member of the SWITCHaai team, the Swiss edu-ID team and task leader in the GÉANT project.

Comments are closed.