Embedded Discovery Service/WAYF

The embedded Discovery Service/WAYF feature allows a Service Provider administrator to easily embed the Discovery Service/WAYF into any web page by copying and pasting some HTML code. Have a look at the bottom of this page to see two examples of the embedded WAYF and get an idea how it works.

Advantages

The embedded WAYF's advantages are:

  • Easy to integrate: Just copy and paste some HTML code.
  • Fully customizable: Change appearance, behaviour and list of Identity Providers.
  • Always up-to-date: If new Identity Provider join the federation or if IdPs change their name, this change is propagated automatically to all instances of the Embedded WAYF.
  • Improved ease-of-use: The user's Identity Provider is often preselected, even if the user has never been on a resource. This is possible if the user has already been on another site that uses the embedded WAYF or the central SWITCHaai WAYF.
  • True Single-Sign-On: Depending on whether users already have an AAI session on another service, users can automatically be logged in on a web page transparently.

To get a full overview about the customization options and features of the currently active Embedded WAYF for the SWITCHaai federation, please consult the sample Embedded WAYF HTML snippet.

Limitations

There are some limitations that one should be aware of as well:

  • The embedded WAYF Javascript is generated by the SWITCHaai central WAYF (wayf.switch.ch). Therefore, the availability of the Embedded WAYF heavily depends on the availability of the SWITCHaai WAYF service. In order to minimize the risk of being a single point of failure, SWITCH operates the central WAYF in a redundant way. This ensures that the service has a high availability.
  • To determine whether a user has an active Shibboleth session the embedded WAYF checks the existence of the Shibboleth session cookies or the Shibboleth session handler. While this works well in most cases, it won't work if the embedded WAYF is placed on a different host than the one where the Shibboleth Service Provider is installed. Furthermore, it can happen after several hours of inactivity that a user has no valid Shibboleth session anymore although there still is a Shibboleth session cookie that has not yet expired. In this case the embedded WAYF may still show that the user is logged in although this is not the case and the user actually has to reauthenticate.
  • It is not possible to embed the WAYF inside of a <form> element because the Embedded WAYF itself already will contain a form element.

Known issues

In the following cases the Embedded WAYF may not work properly:

  • If the user's web browser has disabled to accept/send cookies for third parties, the Home Organisation preselection might not work properly and the user has to manually select the Home Organisation. This is a minor issue and does not prevent users from loggin in.
  • The host wayf.switch.ch from which the Embedded WAYF JavaScript is loaded from uses a QuoVadis Extended Validation certificate. The QuoVadis root certificate that issued this host certificate is contained in all major web browser's CA truststores. If that root certificate however is manually removed by the user, the JavaScript cannot be loaded anymore from wayf.switch.ch. In this case the Embedded WAYF won't be displayed and the user will not be able to log in.
  • If the date on the user's computer is inaccurate (e.g. January 1 1970) because of an empty battery on a laptop, no certificates will be accepted by the web browser. Because wayf.switch.ch is protected with a QuoVadis EV certificate, the JavaScript in such a case is not loaded by a web browser. Therefore, the Embedded WAYF won't be displayed and the user will not be able to log in.
  • Some web browsers like certain Safari versions verify the extended validated certificate with an OCSP request to QuoVadis to make sure that the certificate has not been revoked. If that request fails, Safari won't load any content from the host whose certificate could not be verified with an OCSP request, regardless of the fact that the certificate still is valid and was not revoked. The OCSP request can fail for example because the user denies the outgoing request when asked by a firewall. In this case the Embedded WAYF won't be displayed and the user will not be able to log in
  • If the Embedded WAYF is used more than once on the same HTML page (including IFRAMES), it can happen that its behaviour and its appearance are not as intended. The reason is that multiple instances of the Embedded WAYF may have HTML elements with conflicting id values, which can cause problems. Therefore, it is recommended to have only one instance of the Embedded WAYF per HTML page.

How to Integrate the Embedded WAYF

  1. Go to https://rr.aai.switch.ch/gen_embedding_code.php
  2. Provide the entityId or the hostname of the resource that you want to create the embedding code for
  3. Copy and paste the generated code into any web page. If the web page is not on the same server as the Service Provider, certain features cannot work reliably.
  4. Adapt the essential settings in the configurator Javascript. Also adapt the recommended settings in order to change the appearance, the behaviour, the list of Identity Providers to show in the drop-down list as well as logout options.
  5. (Optionally) In the Shibboleth main configuration shibboleth2.xml change the URL of the SAMLDS SessionInitiator to point to the web page where you inserted the Embedded WAYF.

Language to be used:
By default, the Embedded WAYF analyzes the web browser's Accept-Languages headers in order to determine what locale shall be used for the texts that are displayed. However, it is also possible to force the WAYF to use a specific language by changing the WAYF's URL. Say you want to use German as default language. In this case you would change the WAYF URL path from /SWITCHaai/WAYF to /SWITCHaai/WAYF/de/. The same can be done for French (/fr), Italian (/it) and English (/en).

Examples of Embedded WAYF

Below you see two examples of Embedded WAYFs. As you can see, size and color as well as other options can be customized easily via the configurations JavaScript. If you click on login, you should be sent directly to the login page of the choosen Home Organization and after authentication back to the AAI Viewer.
This page also demonstrates that the embedded WAYF doesn't necessarily have to be integrated in a page on the same host as the Service Provider it refers to.

Also have a look at the source code of this page and inspect the section between EMBEDDED-WAYF-START and EMBEDDED-WAYF-END in order to understand the basic principle.
An alternative to the embedded WAYF that could be used for the non-JavaScript browsers are the static login links or the Shibboleth Embedded Discovery Service, which works similarily like the Embedded WAYF and does not rely on a central service.

A further, smaller example with more customizations