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.
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.
There are some limitations that one should be aware of as well:
- 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.
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.
- 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
- Go to https://rr.aai.switch.ch/gen_embedding_code.php
- Provide the entityId or the hostname of the resource that you want to create the embedding code for
- 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.
- (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
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.
A further, smaller example with more customizations