The SURFconext WAYF

To have more control over the IdP Discovery, you can add your own WAYF (Where Are You From) selection page to your service provider (SP) or relying party (RP). 

First, be sure that your service is configured in SURFconext (Production or Test environment).

When deciding whether to show a WAYF to the user, SURFconext takes into account several factors:

  • The SP / RP that is initiating the login — this determines what IdPs a user is allowed to use
  • The IdP that was recently selected by the user—SURFconext stores the last selected IdP in a cookie, and when the user has logged into this idp in the last 5 minutes, the user is automatically directed to that IdP, if that choice is available.
  • The IdP or IdPs that are requested by the SP or RP during login

SURFconext only shows a WAYF when the user needs to make a choice about the IdP to use. SURFconext does not show a WAYF when the user has only one choice or when a previous login occured in the last 5 minutes, in that case the user is directed to the IdP without showing the WAYF. By providing your own WAYF you limit the IdPs that SURFconext allows the user to choose from. You can not add additional IdPs to SURFconext in this way.

Login hinting when using OpenID Connect

When you use OpenID Connect, you can create a custom WAYF in your RP using the login_hint query parameter when calling the authorize endpoint. You must set the IdP entityID as value for the login_hint parameter. The entityIDs of the connected institutions can be found in the published SURFconext IdPs Metadata.

Example OIDC call to the authorize endpoint with a login_hint  for the IdP with entityID "http://mock-idp"):

https://connect.test.surfconext.nl/oidc/authorize?login_hint=http%3A%2F%2Fmock-idp&scope=openid&response_type=code&redirect_uri=https%3A%2F%2Foidc-playground.test.surfconext.nl%2Fredirect&state=example&nonce=example&client_id=playground_client&response_mode=query

You can test using the login_hint parameter in the OIDC Playground.

Building your own or skipping the WAYF in SURFconext (SAML 2.0)

When integrating a SAML 2.0 Service Provider (SP) with SURFconext, you can control how users select their Identity Provider (IdP). Instead of using the default SURFconext WAYF, an SP can implement its own IdP selection mechanism. There are two supported approaches:

Option 1 – Import SURFconext IdP Metadata into your SP

You can configure your SP with the IdP metadata published by SURFconext.

How it works:

  • Download and import the SURFconext IdP metadata into your SP. For the test Environment, use this link. 

  • Your SP will be configured with multiple IdPs.

  • The SP presents its own IdP selection screen (WAYF).

  • After the user selects an IdP, the SP sends the Authentication Request directly to SURFconext, indicating the chosen IdP.

Important considerations:

  • Your SP must support multiple IdPs in its configuration.

  • Only one IdP can be selected per authentication request.

  • The IdP must be allowed for your SP in SURFconext.

  • The EntityIDs of available IdPs can be found in the SURFconext IdP metadata.

This approach is typically the simplest if your SAML software already supports multi-IdP configuration.

Option 2 – Use the IDPList element in the AuthnRequest (Scoping)

You can control which IdPs appear in the SURFconext WAYF by including a 'Scoping element' with an IDPList in your SAML AuthnRequest.

IDPList

The IDPList element defines the IdPs shown in the SURFconext WAYF. It contains one or more IDPEntry elements. Each IDPEntry must include the IdP’s EntityID in the ProviderID attribute. The EntityIDs of available IdPs can be found in the SURFconext IdP metadata.

Behavior

  • If IDPList contains multiple IdPs, the SURFconext WAYF will show only those IdPs.

  • If IDPList contains exactly one IdP, the WAYF will be skipped and the user will be redirected directly to that IdP (if the IdP is allowed for the SP).

  • If the specified IdP is not allowed for the SP, authentication will fail.

Important:
There is no guarantee that the user will ultimately be authenticated by one of the IdPs listed in the IDPList. The IdP that actually authenticated the user can be found in the "AuthnContext → AuthenticatingAuthority" inside the SAML Assertion returned by SURFconext.


Example of an XML using the IDPlist 
<samlp:AuthnRequest
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="_RANDOM_UNIQUE_ID"
Version="2.0"
IssueInstant="2026-03-03T12:00:00Z"
Destination="https://engine.surfconext.nl/authentication/idp/single-sign-on"
AssertionConsumerServiceURL="https://your-sp.example.org/acs"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">

<saml:Issuer>https://your-sp.example.org/metadata</saml:Issuer>

<samlp:NameIDPolicy
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
AllowCreate="true"/>

<samlp:Scoping>
<samlp:IDPList>
<samlp:IDPEntry ProviderID="https://idp.example.org/idp"/>
<samlp:IDPEntry ProviderID="https://idp2.example.org/idp"/>
</samlp:IDPList>
</samlp:Scoping>

</samlp:AuthnRequest>


See Authentication request: bindings, signing and options#IDPList for more information. You find the EnityIDs of the IdPs that you can use in the SURFconext IdPs metadata.

SURFconext IdPs Metadata

You can find the list of available IdP entityIDs in the SURFconext IdPs metadata:

The metadata also contains displayname, logo and other information about the IdP that you can use in your application to help the user make a selection.

The idps-metadata.xml  file contains all IdPs on the platform. You can also request a version that is scoped to your service provider, meaning that we generate a metadata file that only lists the IdPs that are connected to your SP, and will be updated automatically when this list changes. Request that from support@surfconext.nl, or create this file following the procedure below, under "Your service specific metadata".

Example of a metadata file with SAML 
<?xml version="1.0"?>
<md:EntitiesDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
ID="CORTO6d017189c6bcd01c19935006ce6b32e89e29b4a3">
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="#CORTO6d017189c6bcd01c19935006ce6b32e89e29b4a3">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>L8ANkHPH4msXsIUFptAMeNTuMzQ=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>...</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<md:EntityDescriptor validUntil="2012-05-31T22:00:00Z" entityID="https://test.test.nl">
<md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://engine.surfconext.nl/authentication/sp/consume-assertion/7f301d787aa6ea235a8b86434d39aa41"
index="1"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

<md:EntityDescriptor validUntil="2012-06-01T10:36:28Z" entityID="http://www.surf.nl/test">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:Extensions>
<mdui:DisplayName xml:lang="en">SURFnet BV - This IdP is for testing only</mdui:DisplayName>
<mdui:DisplayName xml:lang="nl">SURFnet BV - This IdP is for testing only</mdui:DisplayName>
<mdui:Description xml:lang="en">SURFnet BV - This IdP is for testing only</mdui:Description>
<mdui:Description xml:lang="nl">SURFnet BV - This IdP is for testing only</mdui:Description>
<mdui:Logo height="60" width="120">https://wayf.surf.nl/federate/surfnet/img/logo/surfnet.png
</mdui:Logo>
<mdui:Keywords xml:lang="en">SURFNET</mdui:Keywords>
<mdui:Keywords xml:lang="nl">SURFNET</mdui:Keywords>
</md:Extensions>
<md:KeyDescriptor xmlns:ds="http://www.w3.org/2000/09/xmldsig#" use="signing">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>...</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor xmlns:ds="http://www.w3.org/2000/09/xmldsig#" use="encryption">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>...</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="https://engine.surfconext.nl/authentication/idp/single-sign-on/dedd75c2157a751113666d7888b2f2cd"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

   <md:EntityDescriptor validUntil="2012-06-01T10:36:28Z" entityID="http://hartingcollege.nl/saml-idp">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
...
       </md:IDPSSODescriptor>
</md:EntityDescriptor>
...
</md:EntitiesDescriptor>

Shibboleth

When you use the Shibboleth SAML SP software (shibd), the following HTML code presents a link that will start an authentication to a specific IdP:

<ul class="IdPlist">
<li><a
href="https://SP.example.org/Shibboleth.sso/Login?target=dashboard.php&entityID=http://www.surf.nl/test
">SURFconext Login</a></li>
</ul>
  • The base URL is the URL of your Shibboleth Service Provider. 
  • 'target' contains the location to return to after the login was successful. 
  • entityID' is the EntityID of the IdP (as found in the SURFconext metadata).

 Just expand the list with more IdPs from the SURFconext metadata, and you have created your own WAYF selection page.

Your service specific metadata

We can create a metadata link for you that will give an up-to-date overview of IdPs connected to your service. Let's take https://the.entityid.of.yourservice.com as an example of an EntityID you need to generate this metadata. You can access the generated metadata as follows: 

  • https://metadata.surfconext.nl/sp/https%253A%252F%252Fthe.entityid.of.yourservice.com

Notice the markup. You can create this using the shell command:

  • echo $EntityID | sed -e 's#:#%253A#g' | sed -e 's#/#%252F#g'

Prepend result with  "https://metadata.surfconext.nl/sp/https" to the result. For our test environment use "https://metadata.test.surfconext.nl/sp/https"

If you want to make use of this, send us a mail with motivation to support@surfconext.nl.