Enabling OpenAthens Wayfinder

Wayfinder uses the SAML DS protocol and as long as your SP software does too it's just a case of configuring it to use Wayfinder as the discovery service and updating federation metadata. This will work for hosted Wayfinder whether or not you are a member of the OpenAthens federation.

We can only offer support for OpenAthens federation members. If you are not a member of our federations, you are still welcome to use Wayfinder at no cost, see: OpenAthens Wayfinder for non-members

OpenAthens Keystone

Sign in to the publisher dashboard (https://sp.openathens.net)
Select the application in question and go to its discovery tab
Scroll to the discovery method section and select the radio button for Wayfinder. If you joined after July 2024 this will already be enabled.
Save changes

Keystone will start to use the hosted version of Wayfinder immediately. Keystone also has the option for you to embed Wayfinder into your site. See: Embedding OpenAthens Wayfinder

The OpenAthens federation will be updated automatically but if you are in any other federations they will have to update your metadata to include valid discovery return URLs before discovery will work:

XML

<idpdisc:DiscoveryResponse Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="http://connect.openathens.net/saml/2/auth" index="1"/>

Shibboleth

Add or update the discovery response binding in your metadata in the <Extensions> section- e.g:

CODE

<Extensions>
   ...
      <idpdisc:DiscoveryResponse xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="https://shibsp.yourdomain.com/Shibboleth.sso/DS" index="1"/>
   ...
</Extensions>

... then add the discovery service to your shibboleth.xml configuration file in the SSO section in place of any singular IdP definition:

CODE

 <SSO
     discoveryProtocol="SAMLDS" discoveryURL="https://wayfinder.openathens.net">
     SAML2 SAML1
 </SSO>

SimpleSAML.php

Set the options in authentication.php and then restart the service

'discoURL' => 'https://wayfinder.openathens.net'
'idp' => null

Update the federation(s)

OpenAthens federation

If you are not using Keystone in the OpenAthens federation you will need to add the discovery return URL to your SAML endpoints via the publisher dashboard:

Once you are logged in at sp.openathens.net, select your application

Go to the SAML endpoints tab and click the add endpoint button

Select discovery return URL, enter the value and click done

Click Save changes
It will take up to 15 minutes for the change to take effect

Other federations

For other federations, first check that your metadata now includes an <idpdisc:DiscoveryResponse> section and then ask the federations you have joined to update their metadata. How this is done can vary by federation, but you will usually have to tell them. If you appear in multiple federations via EduGAIN then updating just the federation you first registered with should usually be enough.

Troubleshooting

No entities appear in Wayfinder

You may not be live in any federations yet. To check that, you would download that federation's metadata and check that your entity appears. If it's there check that it includes a <idpdisc:DiscoveryResponse> section that specifies Wayfinder. The REFEDs metadata explorer tool is also an option but may be a day or so behind (https://met.refeds.org/)

Unexpected entities appear in Wayfinder

Wayfinder will surface all visible entities in each federation where your SP entity appears and has Wayfinder specified. If you have debug mode turned on you will also see entities that are marked in the metadata as hidden.

Federations -
- Keystone users: The federation toggles on your connection in the SP dashboard do not affect your appearance in other federations. They only affect which metadata is available to your application, not Wayfinder. The entities from those federations will appear once that federation includes your metadata (that includes Wayfinder)
- EduGAIN means that as well as only needing to join one Academic federation to appear in many, there can be a delay between updates to the metadata in the federation you registered in and the other federations that include it picking up the change. Timezones and weekends play a part in how long it could take
Debug mode - this will, when enabled on your browser, tell Wayfinder to include entities that have a hide from wayf entity category on them.