Skip to main content
Skip table of contents

Entities that are not in a federation

Like most SAML service providers (SPs), OpenAthens Keystone can also interact with SAML identity providers (IdPs) outside a federation context. To connect with non-federated IdPs, you add their metadata to what is effectively a custom mini federation that we create.

  1. In the Service Provider dashboard, go to Keystone settings > 1:1 connections.

    1-to-1 connection page, showing a list of existing connections. There is also a button labeled 'Add an identity provider'.

  2. To add a new entity, click the Add an identity provider button. You can then link to or upload the metadata of the new entity. To edit the metadata of an existing entity, select Update metadata from the ellipsis menu.

    Page titled 'Add a SAML identity provider'. Advisory text reads, 'To add or update an entity you must supply a SAML metadata document for the identity provider you wish to add or update. You may do this by either providing a URL or uploading the metadata as a file.' Following this are two fields, a text field labeled 'Metadata URL' and a file upload fields labeled 'Metadata file'. There are also buttons labeled 'Next' and 'Cancel'.

  3. Affirm the certificate is OK.

  4. 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 organization discovery tools.

  5. Edit your Keystone connection (Keystone settings > Keystone connections > choose a connection) to enable the setting Allow sign-in for identity providers via 1:1 connections.

  6. Save the changes to the connection.

That identity provider will then become available to all of your Keystone 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.

Providing metadata or details to the IdP

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

If the IdP needs specific items of data:

entityID: find on the connection 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. Go to Keystone settings > 1:1 connections.

  2. Find the IdP in your list of additional identity providers.

  3. 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 the IdP’s metadata

    • if it's your first 1:1 connection, check you've turned on Allow sign-in for identity providers via 1:1 connections on the Keystone connection page, and saved and published the change

    • see the Keystone error message page 

  • If the error comes from the IdP’s domain, ask the IdP to check that they've correctly added your metadata or details

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 changes to propagate fully.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close