Breadcrumbs

Keystone connections

The Keystone connections page configures how OpenAthens products like Keystone work in multiple federations. SAML applications such as Shibboleth don't have a separate connection here because their appearance in other federations isn't managed by us.

Main Keystone connections page. Intro text reads 'A Keystone connection contains the configuration details for managing federated and bilateral access to your OpenID Connect applications.' This is followed by more specific help text and then a list of existing connections, each shown with its basic details. Beside each connection is a drop-down list labeled 'Options'. There is also a drop-down menu labeled 'Sort by'.

Connection details

Existing Keystone connections are displayed in a list. Each connection is shown as a “card” including key details, such as the entityID of the connection, the number of applications linked to the connection, and the federations or 1:1 (bilateral) connections to which it provides access. There are also options to edit or delete the connection.

Example card for a connection called 'Philosophy Today connection'. The name of the connection is a link. The connection's entityID is in the form of a URL. The connection has two applications linked. It has the following connections enabled - 'OpenAthens Federation' and '1 to 1 Connections'. In the top right corner of the card is a drop-down menu labeled 'Options'.

Sort connections

You can sort the list of connections either alphabetically by name or alphabetically by entityID. Sorting by name is the default.

  1. Open the Sort by drop-down menu above the list of connections.

  2. Choose whether to sort by Name or by entityID.

    'Sort by' drop-down menu, open to show the options 'Name' (which is ticked) and 'entityID'.

The list automatically updates to show your chosen sort order.

Edit a connection

To configure a connection, click on its name in the list. You are taken to a page that shows the details of the connection.

Details tab of a connection called 'Philosophy Today connection'. The top part of this long page is visible, showing the sections 'Application' and 'Rules'. In the top right corner is a 'Save changes' button.

You can change the following settings:

Application

The application record(s) using this connection.

Rules (OpenAthens Keystone only)

Allows you to toggle rule sets on and off. Changes take place immediately after saving.

  • Common EduPerson and Extended EduPerson translate the attribute names commonly used in educational federations to OpenID Connect claims. See eduPerson attributes

  • Affiliation and scope derived from EduPersonScopedAffiliation extracts useful identifiers from the main eduPerson attribute used in federations 

SAML connector 

Section titled 'SAML Connector' in the Details tab of a connection. It includes several subheadings - 'Entity', followed by URL, 'Certificates', followed by certificate details, 'Security checks', followed by a setting called 'Scope matching' which can be toggled on or off, and 'Privacy policies', following which is a button marked 'Add a privacy policy'.

Entity

This is the entityID of your application and defaults to https://sp.{domain}/entity. If you change this, make sure to save changes and confirm the page has updated. You almost certainly will not want to change the entityID once you are live. 

The three-dots menu gives you access to view the entity metadata. You can download the metadata or copy the published address to send to federations you are joining or to direct 1:1 connections.

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'.

The entity metadata has two options for logos. Inline (the default) stores logo and banner as base64 encoded png images in the metadata. Hosted presents the banner as a URL and drops the logo. The reason for this choice is that some federations require logos to be hosted rather than embedded.

Certificate

This is your metadata certificate. The same certificate is used for signing and encryption. A federation might ask you to confirm its thumbprint when you register with them.

The three-dots menu gives you access to view the certificate details.

Section of the Details tab, showing the subheading 'Certificate' followed by brief details. 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 details'.

Privacy policies 

Allows you to add and remove links to your privacy policy in the metadata. You can specify one link per language.

Depending on your memberships, linking to a privacy policy may be recommended or required. It is required if you assert the GÉANT Data Protection Code of Conduct entity category.

  1. Press Add a privacy policy.

    Subsection of a connection's Details tab, headed 'Privacy policies'. A message reads, 'There are no privacy policies associated with this connection.' Following this is a button marked 'Add a privacy policy'.

  2. In Enter URL, type or paste the address of your privacy policy.

    Text field containing the prompt 'Enter URL', followed by a drop-down selector that currently reads 'English'. There is also a button labeled 'Add policy'.

  3. Select the language of the policy from the drop-down selector.

  4. Press Add policy.

OpenAthens Federation

Allow sign-in for live OpenAthens identity providers

This signals inclusion in the OpenAthens Federation once the application is set as live on the application page and approved. The application will then be visible to all OpenAthens IdPs.

Subsection of the Details tab headed 'OpenAthens Federation. It has two settings, 'Allow sign-in for OpenAthens Test identity providers' and 'Allow sign-in for live OpenAthens identity providers'. Beside each setting is a switch that can be set to 'On' or 'Off'.

Other federations

This section lists other federations you might join. If you switch a federation to On, its metadata will be added to your configuration. Setting the switch does not register you in that federation and you will still need to take steps to join. See Enabling federations and How to join other federations.

Subsection of the Details tab headed 'Other Federations'. It shows a list of three federations, in alphabetical order, followed by a 'Show all' button. Beside the name of each federation is a switch that can be toggled 'On' or 'Off'.

1:1 connections

In this section, manage your connections with SAML IdPs that are not in a common federation. (It is up to you to decide whether it is easier to join any given federation than to configure IdPs separately.). See Entities that are not in a federation.

Subsection of the Details tab headed '1 to 1 Connections'. It contains one setting, 'Allow sign-in for identity providers via 1 to 1 connections', which can be switched to 'On' or 'Off'.

See also

Entity categories 

This section allows you to indicate in your metadata which entity categories you support. After saving, you'll be able to see changes immediately in the internal metadata view, but it will take up to six hours for them to appear in the published OpenAthens Federation metadata. You will need to report the changes to any other federations in which you are registered. (Education federations that include you via eduGAIN will pick up the change from the federation in which you are registered.)

Since most entity categories signify compliance with a set of rules or behaviors, it's best to leave these turned off until everything else is in place.

Subsection of the Details tab headed 'Entity Categories'. It shows two settings, 'Research and Scholarship' and 'GEANT Data Protection Code of Conduct'. Each setting has a switch that can be set to 'On' or 'Off'.