Breadcrumbs

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. We call these connections 1:1 or bilateral connections.

Add a 1:1 connection

  1. In the service provider dashboard, go to Keystone settings > 1:1 connections.

    1-to-1 connection page, showing a list of entities with existing connections. Beside the name of each entity is a drop-down menu labeled 'Options'. At the top of the page is general advisory text and additional help.There is also a button labeled 'Add a 1 to 1 connection'.

  2. To add a new entity, click the Add a 1:1 connection button.

    Page titled 'Add a SAML identity provider, step 1 of 3'. 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. Either:

    1. Type or paste the URL of the IdP’s metadata in the Metadata URL field, or

    2. Press Choose File and upload the metadata as an XML file.

  4. Press Next.

    Page titled 'Identity provider display name, step 2 of 3'. Following some intro text are two radio buttons, 'Display name from metadata', which shows the name 'Temporary Azure Relying Party., and 'Specify display name', which has an accompanying input field. Lastly, there are buttons marked 'Next', 'Back' and 'Cancel'.

  5. By default, the name of the new entity is taken automatically from the metadata. To give it a more descriptive name, select Specify display name and enter the new name in the input field. The name must be at least two characters long. We recommend making it no longer than 140 characters (names longer than this don't display well in Wayfinder and other organization discovery tools).

  6. Press Next.

    Page titled 'Confirm trusted source, step 3 of 3'. It shows details of the metadata certificate provided. Following these details is a check box labeled 'This metadata is trusted and should be imported as a SAML entity.' Lastly, there are buttons marked 'Upload', 'Back' and 'Cancel'

  7. The next page displays details of the metadata. Check they are correct. If you’re satisfied, tick This metadata is trusted and should be exported as a SAML entity.

  8. Press Upload to finish.

  9. Go to the Keystone connection belonging to the application to which you also want to allow access through 1:1. Enable the setting Allow sign-in for identity providers via 1:1 connections if it’s not already turned on.

  10. Save your changes to the Keystone connection.

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

You will also need to provide the IdP with your metadata or, in some cases, named details. See the following section.

Provide metadata or details to the IdP

In most cases, the IdP will want your metadata address or a metadata file. Take this from the relevant Keystone connection:

  1. Go to Keystone settings > Keystone connections.

  2. Open the connection linked to the application that you want to make available through 1:1.

  3. In the connection’s Details tab, scroll to the section SAML connector.

    Section titled 'SAML Connector' in the Details tab of a connection. It includes several subheadings - 'Entity', 'Certificates', 'Security checks' and 'Privacy policies'. Beside 'Entity' and 'Certificates' is a context menu marked with three vertical dots.

  4. From the three-dots menu next to the entityID, select View metadata. You can then copy the URL and/or details of the metadata as required.

    Section of the Details tab, showing the heading 'SAML Connector' followed by the subheading 'Entity'. Below 'Entity' is the entityID in the form of a URL. On the right side of the screen is a drop-down menu marked with three dots in a vertical line. This menu is open to show a single option, 'View metadata'.

If the IdP needs specific items of data:

  • entityID: find in the Details tab of the Keystone connection, also in the first line of your metadata

  • SSO endpoint: find this line in your metadata and copy the location part:<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

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

  • It can take up to six hours for changes to propagate fully

See also