Entities that are not in a federation

Like most SAML SPs, OpenAthens Keystone can also interact with SAML identity providers outside of a federation context. With OpenAthens, this is done by adding their metadata to what is effectively a mini federation we create that is specific to your connections. To do this:

1. In the configuration menu, select 1:1 connections
   
   
   1. This can also be accessed via any connection in the 1:1 connections section
      
      
2. Click on the additional identity providers link
   
   
3. Add a new entity via the green button at the top. You can link to or upload their metadata - or use the ellipsis menu next to an existing entry to view or update metadata
   
   
4. Affirm the certificate is ok
   
   
5. If the metadata didn't include a suitable display name you can change it via the ellipsis menu after creation. More than 140 characters won't display well in Wayfinder and other organisation discovery tools.
   
   
6. On the connections page: if it is not already set, toggle the switch on the additional identity providers line to 'Allow'
   
   
7. Save the changes to the connection

That identity provider will then become available to all of your connections where 1:1 connections are enabled, and the applications that use those connections. Your addition will not cause that IdP to become available for any other publishers.

You will also need to provide the IdP with your metadata or in some cases named details... below

Providing metadata or details to the IdP

In most cases they'll want a metadata address or file. This can be taken from the same connections page - scroll up to the SAML connector section and use the ellipsis menu next to the entityID to access the metadata. You can choose wither logos are embedded or linked, and copy a link or the metadata as needed.

If the IdP needs specific items of data though:

entityID: on the connections page, also in the first line of your metadata

SSO endpoint: find this line in your metadata and copy the location part from your metadata:

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://connect.openathens.net/YOURDOMAIN/CONNECTION_ID/auth/rcv/saml2/post" index="1" isDefault="true"/>

X509 certificate: appears twice in the metadata in a <ds:X509Certificate> element.

Updating IdP certificates

The certificates for additional identity providers must be kept up to date to avoid access issues. When a certificate that belongs to one of your additional identity providers is due to expire:

1. Find the IdP in your list of additional identity providers
2. Update the metadata through the ellipsis menu 

Troubleshooting

Assuming you're in production, check which domain is serving any error message. 

• If it's *.openathens.net:
  • check you've uploaded their metadata
  • if it's your first 1:1 connection, check you've turned on the additional identity providers option on the connection page and saved it, and published the change
  • see the Keystone error message page 
• If it's the IdP end, ask them to check that they've added your metadata or details at their end 

Anything to watch out for?

There is a 1MB size limit on each metadata upload.  If you are trying to add a federation that doesn't appear to be available, contact our support team.

It can take up to six hours for the changes to propagate fully. From that point:

• OpenAthens Keystone is done
• OpenAthens Wayfinder will need up to 5 minutes more