How to 'WAYF' your web service

  1. Contact the WAYF Secretariat
  2. Price
  3. Sponsor statement (for commercial services)t
  4. Service provider contract
  5. Description of purpose
  6. Attribute Release Profile (‘ARP’)
  7. Internal web services
  8. Technical integration
  9. Little technical support
  10. Access control lies with the servicenot with WAYF

1. Contact the WAYF Secretariat

If you want to offer your users logging in through WAYF at a web service that you provide, please contact the WAYF Secretariat to get the connection process started.

2. Price

Connecting to WAYF is free of charge for service providers. However, a connection fee of 100 DKK, VAT excl., is charged a year for each service connected. Any expenses incurred by the technical integration of WAYF login with the service is also defrayed by the service provider.

3. Sponsor statement (for commercial services)

It is an important legal precondition to being allowed to connect a comercial service to WAYF that it is documented to the WAYF Secretariat that at least one of those institutions connected to WAYF wants to be able to offer its users access to the commercial service through WAYF. If the service provider is already connected to WAYF as an institution (e.g., a university), no explicit documentation of this kind is required. But otherwise, the service provider must see to it that a connected institution sends a "sponsor statement" to the WAYF Secretariat. There are no formal requirements on this statement; it may simply be a brief e-mail.

4. Service provider contract

Once the sponsor statement is in place, the service provider must enter in to a formal contract with WAYF on the connection. The WAYF Secretariat produces the document and forwards it for signing. In order to be able to draft the contract, WAYF will need the service provider to supply the following material:

  • the official name of the service;
  • the official name of the service provider;
  • the service provider's business registration number;
  • the service provider's logotype;
  • the full names(s) of those person(s) authorised to sign that will be signing the contract on the service provider's behalf.

The service provider is also obliged to name one organisational contact person and one technical contact — and forward: name, e-mail address, and phone number for each contact.

5. Description of purpose

The written contract features, as a special item, a very brief description of the purpose of the service. This description is established in a cooperation between the service provider and WAYF, and will be displayed to any user attempting to log into the service through WAYF. The description is intended to provide the user with a basis on which to consent to data about him, displayed at the same time, being transferred to the service from his institution. Furthermore, the description must fit into the template The purpose of the service is ____.

6. Attribute Release Profile/Policy (‘ARP’)

Whenever a user attempts to log into a web service through WAYF, WAYF transfers from his institution a certain amount of data about him to the service. It follows from personal data protection law that only the minimum of information may be transferred that is required for the service provider to be able to deliver his service to its intended consumers. The required amount of user information — the Attribute Release Profile for the service — is negotiated between the service provider and WAYF, and is written into the contract. The elements of user information — so-called attributes — that WAYF is able to deliver are enumerated here. Please note that WAYF is unable to guarantee the availability of any attribute not marked ‘MUST‘.

7. Internal services

When an institution provides a service for the exclusive use by its own users, we are dealing with an internal service; and such a service can be connected to WAYF without further ado. WAYF enforces, technically, that only users from the providing institution can access the service (though it remains the responsibility of the institution to make sure that only entitled users are granted access). Each institution can have an indefinite number of internal services connected to WAYF — and so use WAYF as an internal single sign-on system.

8. Technical integration

The technical integration consists of: implementing a SAML SP on the web service and then: exchanging metadata with WAYF.

The SAML SP is a service which is able to communicate with WAYF's server through the login protocol SAML2, and must comply with the SAML 2.0 Interoperability Deployment Profile. An array of different products are on in the market for implementing a SAML SP, both commercial (e.g., Microsoft's ADFS) and open-source (e.g., SimpleSAMLphp, Shibboleth, OIOSAML). Moreover, special SAML2 modules exist for a range of CMSs (e.g., WordPress, Drupal). A PHP minimum SAML2 SP implementation can be studied here. A collection of SAML2 tools for a number of different programming languages and CMSs is found here.

Please note that your server must support HTTPS. Furthermore, your SAML2 SP must be able to send login requests to WAYF by a HTTP GET, and be able to receive login responses from WAYF by a HTTP POST.

Once the web service has implemented the SAML2 interface, the service provider and WAYF must exchange metadata: essentially information on where their servers can find each other on the internet, and how exactly they may communicate with one another. Metadata about WAYF's servers are found here and must be consumed by the SAML2 SP of the service. Metadata about the latter must be entered into WAYF's metadata registry, mEdit.

In the standard version of WAYF, WAYF asks the user to select his login institution from a list. However, as a service provider you also have the option to have the user select his login institution directly at the service's own site. This is attractive if you want to limit the user's choice to including customer institutions only. An available technology, then, is scoping. WAYF's own institution list (‘discovery list’), however, can also be programmed to display just the institutions of relevance to your particular service.

Note: WAYF now offers an alternative, non-SAML interface for service providers: a JWT-based interface for login traffic. If your application environment doesn't have SAML2 support, out JWT interface could be the easy solution for you. See documentation here.

9. Little technical support

The WAYF Secretariat as a principle offers no technical support for the service provider's efforts to implement WAYF login at his web service. We support the SAML2 interface, but other than that, we do not relate to specific implemntations of SAML2 at the service provider's, including how to configure SAML2 software that we might mention on this site. If one is not capable of the integration oneself, a SAML2 knowledgable consultant must be hired.

10. Access control lies with the service — not with WAYF

It is important to remember that all access control is performed at the web service: Whenever WAYF's server sends a login response to the service, that per se does not imply that the user in question must be granted access to the service. Rather, the login response contains the information on the user agreed on in the contract; and it is the responsibility of the service provider to implement at filter that will check if the attribute values received entitle the user to access. It is a serious misunderstanding, and a potentially business critical one, if the service provider believes that merely receiving a login response at all from WAYF's server entitles the corresponding user to access. In like manner, the service provider is responsible for verifying that login responses received have actually been issued by WAYF — by testing the XML signature of the Assertion element of the response.