User Interface Elements in SP Metadata
This page describes how an SP metadata administrator adds user interface elements to metadata. These elements are used by IdP implementations to enhance their user interfaces. See the section on software support for a complete list of supported applications.
Meeting Baseline Expectations
InCommon will phase in the Baseline Expectations program through much of calendar year 2018. Over time, this program will make some user interface elements mandatory (these are noted below). InCommon recommends adding all of these user elements to your metadata; in particular those that will become mandatory. For more information, see the Baseline Expectations wiki page.
Contents:
Updating SP Metadata
Log into the Federation Manager as usual. In the SA Dashboard, click the "Update" link next to the SP you wish to edit in the "Existing Service Providers" table. Scroll to "User Interface Elements and Requested Attributes" and click the (Edit) link. A web form to enter the new elements will appear.
Add and edit any needed UI elements. When you click "Save," an <mdui:UIInfo> extension element is inserted into your metadata. From that point forward, you manage these elements the same as you would any other metadata element.
User Interface Elements
All of the input fields below except Display Name are optional for SPs.
SP Display Name
The SP Display Name is a user friendly name for the service (not the organization). Typically, the value of the SP Display Name field will appear on login and error pages at the IdP, and also on the consent page. If the corresponding element <mdui:DisplayName> does not exist in metadata, some applications fall back on the <md:OrganizationDisplayName> element, which typically does not reflect the service but rather the organization that runs the service. Such an organization may in fact run multiple SP services, so the organization name is a poor choice to use on a user interface.
SP Display Name
Choose a user friendly name for your service. Do not use a host name, and above all, do not forget to supply a Display Name since some applications fall back on the SP's entityID, which is guaranteed to confuse the user.
According to the spec, the <mdui:DisplayName> element is an optional child element of the <mdui:UIInfo> extension element but InCommon SP operators are required to supply this information.
SP Description
A brief SP Description (140 characters or less) of the service may be provided. On computers that support a pointing device (such as a mouse, e.g.), the description will pop up when the user hovers over the SP Display Name.
The <mdui:Description> element is an optional child element of the <mdui:UIInfo> extension element but SP operators are encouraged to supply this information.
SP Information URL
The SP Information URL is used to create a link to a service information page. The content of this page should expand on the content of the SP Description field. The Information URL is often presented to the user on the IdP's login page or perhaps the consent page.
The <mdui:InformationURL> element is an optional child element of the <mdui:UIInfo> extension element but SP operators are encouraged to supply this information.
SP Privacy Statement URL
The SP Privacy Statement URL is used to create a link to a Privacy Statement targeted at end users. Like the Information URL, the Privacy Statement URL is often presented to the user on the IdP's login page or consent page.
The <mdui:PrivacyStatementURL> element is optional (it is a child element of the <mdui:UIInfo> extension element) but will become mandatory under Baseline Expectations. SP operators are strongly encouraged to supply this information.
Your Privacy Statement
The importance of a Privacy Statement can not be overstated. Users will be instructed to consult the SP's Privacy Statement, lack of which will cause some users to decline attribute release.
Your POP may already contain statements regarding privacy. One approach, therefore, is to refactor the relevant sections of your POP into a Privacy Statement targeted at the end user.
The Relation Between your POP and the Privacy Statement
Since you only have one POP, it necessarily applies to all of your SP deployments. In that sense, the granularity of the POP is not sufficient for those sites supporting multiple SPs. On the other hand, your Privacy Statement refers to a single SP deployment.
Note: A Privacy Statement may be shared across multiple SP deployments. Not all SPs have the same privacy requirements, however, so you should carefully consider the granularity that best fits your overall SP deployment.
SP Logo URL
The SP Logo URL is a service logo for building graphical user interfaces.
The <mdui:Logo> element is optional but will become mandatory under Baseline Expectations (it is a child element of the <mdui:UIInfo> extension element). There are applications that can leverage this element in metadata. A consent interface, for example, may use a visual cue (i.e., a logo) instead of or in addition to the SP Display Name.
SP operators are encouraged to provide an SP Logo URL that satisfies the following requirements:
- the SP Logo URL must be specified using an HTTPS URL
- the resource at the SP Logo URL must be a public image resource
- the host in the SP Logo URL must reside in a domain owned by the IdP
The first two are technical requirements whereas the latter is a policy requirement. These are the only strict requirements of a SP Logo URL in metadata.
Logo HTTPS URL
The server that serves the logo resource should be protected with an SSL/TLS certificate trusted by the browser (i.e., not a self-signed certificate), otherwise the logo may not appear on a dynamically generated web page.
The actual size of the logo may vary. You will be asked to enter the actual width and height of the logo (in pixels). A typical application expects a maximum height of 150 pixels, and if need be, will scale the logo proportionally based on the actual width and height entered into metadata.
Generally useful logos will have the following characteristics:
- the logo should have a transparent background
- the logo should have a landscape orientation (width > height)
- the logo should have a minimum width of 100 pixels
- the logo should have a minimum height of 75 pixels and a maximum height of 150 pixels (or the application will scale it proportionally)
Logos that meet the minimum width and height requirements can be scaled down by the application as needed. Logos that do not meet the minimum width and height requirements may be ignored by applications.
There is no consensus as to what constitutes an optimal aspect ratio. For some applications, an aspect ratio between 4:3 and 16:9 is considered optimal. Other applications will have a page layout such that an approximate 2.5 aspect ratio is optimal. A future version of the administrative interface will accept multiple logo URLs so that sites may provide a variety of logos.
Software Support
The InCommon Federation entity information pages display the values of all user interface elements in metadata. The information pages are refreshed daily, in parallel with InCommon metadata.
Shibboleth IdP 2.3 (and later) and uApprove 2.2 (and later) support the <mdui:UIInfo> element in SP metadata. If you know of other software applications that support <mdui:UIInfo>, please share this information with the community.