Embedded WAYF

The embedded WAYF feature allows a Service Provider administrator to easily embed the Discovery Service/WAYF into any web page by just copy and paste some HTML code. You find an example of the embedded WAYF below. 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.

Advantages

The embedded WAYF's advantages are:

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

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). In order to minimize the risk of this service being a single point of failure, SWITCH operates the central WAYF in a redundant way. This ensures that the service has a high availability but one nevertheless must be aware of this implication. On the other side, since the new WAYF has been put in operation (2005) there hasn't been any internally or externally monitored downtime.
  • To determine whether a user has an active Shibboleth session the embedded WAYF checks the existence of the Shibboleth session cookies. While this works well in most cases, this won't work if the embedded WAYF is used 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.

Known issues

In the past few months a few cases where discovered where the Embedded WAYF was not displayed at all:

  • 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.
  • The host where 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 therefore won't be displayed.
  • If the date on the user's computer is totally 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 uses a certificate, the JavaScript in such a case is not loaded by a web browser.
  • Some web browsers like Safari 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 anything from the host whose certificate could not be verified with such an OCSP request regardless of the fact that the certificate still is valid and was not revoked. The OCSP request for example could fail because the user denies the outgoing request when asked by a firewall.

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
  4. Adapt certain parameters in the configurator Javascript in order to change look, feel, the Identity Providers to show in the drop-down list as well as logout options. In particular you might set the option wayf_hide_categories = new Array("upcoming"); to hide temporary Identity Providers that are migrating to Shibboleth 2.x.

Force language to be used:
Per default, the (Embedded) WAYF will analyze 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 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.

Or another smaller example with more customizations