4. Restart Apache ( \> `systemctl restart httpd`)
5. Go to the target page in a browser.
6. Get sent to an OpenAthens sign-in page.
7. Sign in and get sent back to the attributes page.
---
language: "en"
---
# Applications
Applications represent your online content, products or services. Examples of applications include:
* An academic database
* A publishing imprint
* A website holding a collection of resources
Applications can be of two types:
* OpenID Connect applications, built on [OpenAthens Keystone](https://docs.openathens.net/providers/openathens-keystone.md)
* SAML applications, built on existing SAML entity metadata generated by third-party software such as Shibboleth. By adding these applications to your dashboard, you can manage your existing SAML entities in the OpenAthens Federation
The **Applications** page displays a list of your current applications along with key details about each one.
You can group or sort the applications by a range of criteria.
You will see only applications that you have permission to access.
## Application details
Each application is shown as a "card", giving the following information:
### OpenID Connect applications
* Name of the application
* entityID
* Application ID
* The type of application (for Keystone customers only, whose dashboard supports both types)
* If this application is the primary one for its [Keystone connection](https://docs.openathens.net/providers/keystone-connections.md)
* If the application is orphaned (not linked to a current Keystone connection)
* Connection status and to what the application is connected: the OpenAthens Federation, other federations, and/or 1:1 (bilateral) connections
* If [access to administer the application](https://docs.openathens.net/providers/manage-admin-access-to-an-application.md) is restricted to specific users
### SAML applications
* Name of the application
* entityID
* The type of application (for Keystone customers only, whose dashboard supports both types)
* If the application is published
* Connection status for the OpenAthens Federation
* If [access to administer the application](https://docs.openathens.net/providers/manage-admin-access-to-an-application.md) is restricted to specific users
### Examples
OpenID Connect application, primary, with restricted admin access
SAML application, published
## Group applications
As well as viewing applications as an alphabetical list, you can group them by type and connection.
From **Group by**, select how you want to view the list:
* **Ungrouped**: View all applications as an alphabetical list (the default)
* **Keystone connection** : View all OpenID Connect applications, grouped by the [connection](https://docs.openathens.net/providers/keystone-connections.md) that they use, followed by SAML applications
Once you make your selection, the display updates automatically.
## Sort applications
You can sort the list of applications either alphabetically by name (the default) or alphabetically by entityID.
To change the sort order, choose your preferred option from the **Sort by** menu. The list updates automatically.
## Application functions
* [Add an application](https://docs.openathens.net/providers/add-an-application.md)
* [Edit an application](https://docs.openathens.net/providers/edit-an-application.md)
* [Manage admin access to an application](https://docs.openathens.net/providers/manage-admin-access-to-an-application.md)
* [Delete an application](https://docs.openathens.net/providers/delete-an-application.md)
* [Run a statistics report on an application](https://docs.openathens.net/providers/custom-report.md)
### Next
* [Back to overview](https://docs.openathens.net/providers/service-provider-dashboard-reference-guide.md)
* [On to Keystone connections](https://docs.openathens.net/providers/keystone-connections.md)
---
language: "en"
---
# Best practices
This section covers best practice when implementing support for federated access in general and specifically in the OpenAthens Federation.
## How users arrive at your website
There are two scenarios that need to be considered:
* When a user arrives at your site from anywhere (such as from a Google search).
* When a user arrives at your site from a curated link such as their organization's portal or reading list.
In both scenarios the end result should be the same: that the user has been authenticated by their Identity Provider (IdP), the Service Provider (SP) has confirmed their authorization and a local session has been set up on the user's behalf.
For the first scenario you will need to implement a discovery service (sometimes called a WAYF for Where Are You From) in which users will be able to choose their organization from a list so you can send them to their institutional login page with a SAML request. This list will ideally be accessed via a type-ahead rather than a drop-down as literally thousands of IdPs can appear. You can write your own, but using a central discovery service such as OpenAthens Wayfinder is encouraged for consistency (See: [Using your own discovery service](https://docs.openathens.net/providers/using-your-own-discovery-service-with-openathens-k.md) and [Embedding OpenAthens Wayfinder](https://docs.openathens.net/providers/embedding-openathens-wayfinder.md).)
For the second scenario where users follow a curated link, wayfless URLs should be supported if possible - i.e. links that include the IdPs entityID and avoid additional discovery; e.g. `https://sp.example.com?entity=
&target=.` This kind of URL is incredibly popular with IdPs who wish to simplify user access. These links should use federation entityIDs rather than your own customer IDs for compatibility with other systems.
Where users follow a login link on your site they should, wherever possible, take the user where they would reasonably expect to go - e.g:
* if they click a general login link on a page, the user should end up back at the same page with whatever additional content now available
* If the login happens as part of the flow from an abstract to full text, then they should be returned to the full text
## Terminology
There has been much discussion on what terminology should be used on login pages; a common theme is that users should not see technical terms such as Shibboleth (or OpenAthens) on login pages. We endorse the approach summarized by [REFEDS](https://refeds.org/), the TERENA group which looks at the needs of existing and emerging e-identity federations operating in the field of education and research. For examples and more detailed ideas about industry best practice on creating a familiar login experience for users, see the [ESPReSSO: Establishing Suggested Practices Regarding Single Sign-On](http://www.niso.org/workrooms/sso) project report. The most important parts can be briefly summarized as:
* The login button or link should be in the top right of the page
* In the login dialog, use a term such as "Institutional login" to describe this kind of access rather than naming a technology
* If you are in multiple federations, the user signing in shouldn't need to know about it
This does not mean you cannot accommodate requests from your customers for special treatment.
## Authorization
A common method to authorize users is based on the organization they are from, and this can be implemented by making use of the organization identifier (scope). You should not use entityID for authorization as it prevents you providing different levels of subscription across large organizations or consortia. It is also possible to perform more granular authorizations based on attributes such as role or entitlements.
### Authorization error messages
When a user is not authorized for access, an error message should tell them why. For example, "Your organization does not have access to this section" is better than "Error code 4 ref: o8ysiuyrt88str".
### Attributes
The exact attributes passed when an end-user accesses your resource depends on how the Identity Provider is configured. However, there are some standard attributes you can expect to receive.
Federations normally provide recommendations about what attributes should be passed or used for which purpose and you can expect IdPs in that federation to be able to pass them. However, they are likely to default to passing only the barest minimum unless you tell them which attributes you need. For details about standard and extended attributes in the OpenAthens federation, see: [Standard attributes in the OpenAthens federation](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
You may want to use some items of personal end-user data to enhance their experience, e.g. to avoid a separate registration process. The [GÉANT Data Protection Code of Conduct for Service Providers in EU/EEA](https://geant3plus.archive.geant.net/Documents/GEANT_DP_CoC_ver1.0.pdf) (.pdf) attempts to define behavioral rules for Service Providers that want to receive user attributes. It is our experience though that identity providers are very reluctant to release personal information, even without GDPR and similar legislation, so you should not expect it and must not require it.
### Deep linking
Deep linking (or article level linking) via authenticated links should be supported wherever possible as this is highly desirable to your customers. Your implementation should allow a target page variable to be passed to the authentication process for the user to be directed to after authorization and any customer identifiers included in these access URLs should be those used by the federation to allow links to be tokenized in a consistent way (e.g. use the subscribers' federation entityIDs rather than your own subscriber number). See: [WAYFless access and deep linking in the OpenAthens Federation](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-the-openathens.md).
### Unique identifiers
In order to ensure uniqueness of records, any data which you hold about users needs to be associated with a unique user identifier, ideally a pseudonymous one. The OpenAthens Federation uses the eduPersonTargetedID attribute which is usually suitable. This will in time be replaced by [pairwise-ID](https://docs.openathens.net/providers/about-pairwise-id.md).
### Logging out
Where a logout function exists, it should be clear to the end-user that they have been logged out of your service.
Do not send the user to their IdP's logout page.
### Expired sessions
When sessions expire, you should wherever possible allow them to restart their session at the same page.
---
language: "en"
---
# Common OpenID Connect claims
## What would I get by default from OpenAthens Keystone?
The preconfigured rules will take care of many SAML attributes and Keystone will output several claims from a standard OpenAthens login:
* `sub` - a non-persistent user identifier.
* `realmName` - the SAML entityID of the end-users' organization - e.g. `https://idp.hogwarts.sch.uk/openathens`
* `Issuer.errorURL` - where present will be a URL a user can be sent to when you can't let them in because of something at their end. See: [The errorURL attribute and what it is for](https://docs.openathens.net/providers/the-errorurl-attribute-and-what-it-is-for.md)
* `eduPersonScopedAffiliation` - a scoped role - e.g. `member@hogwarts.sch.uk`
* `derivedEduPersonAffiliation` - just the role bit extracted from the thing above - e.g. `member`
* `derivedEduPersonScope` - just the scope bit, etc - e.g. `hogwarts.sch.uk `
* One or both of these identifiers depending on the identity provider
* `eduPersonTargetedID` - a persistent user identifier, being depreciated in many federations
* `pairwiseID` - a persistent user identifier that is replacing `eduPersonTargetedID`
There may be more, depending on what the identity provider is sending, but these should always show up.
## Common OpenID Connect claims
These are the common claims that OIDC typically uses. Most of them are not sent to you via Keystone by default because none of them have a direct equivalent in SAML that is *always* sent.
We include them here for anyone that has an existing OpenID Connect instance that is already talking to other providers, or are planning one, to help plan any attribute mappings.
The only one of these you can expect to always get from all providers is "sub".
| **OIDC claim** | **What it is** | **Example value** | **SAML equivalent (if any)** |
|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|--------------------------------------------------|
| sub | Subject. | iw8347598oqw7dp4857q9o87h5f8q437h59o87q94 | |
| name | End user's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end user's locale and preferences. | Professor Albus Percival Wulfric Brian Dumbledore | |
| given_name | Given name(s) or first name(s) of the end user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. | Albus | |
| family_name | Surname(s) or last name(s) of the end user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. | Dumbledore | |
| middle_name | Middle name(s) of the end user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used. | Percival Wulfric Brian | |
| nickname | Casual name of the end user that may or may not be the same as the given_name. For instance, a nickname value of Bob might be returned alongside a given_name value of Robert. | Alby | `urn:oid:1.3.6.1.4.1.5923.1.1.1.2` (rarely used) |
| preferred_username | Shorthand name by which the end user wishes to be referred to at the Relying Party, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. Unlikely to be unique | D-wiz | |
| profile | URL of the end user's profile page. | http://staff.hogwarts.sch.uk/headmaster | |
| picture | URL of the end user's profile picture. | http://staff.hogwarts.sch.uk/media/dumbledore_headshot.png | |
| website | URL of the end user's web page or blog. Might be that of their organization. | http://www.hogwarts.sch.uk | |
| email | End user's preferred email address. May be non-unique. | headmaster@hogwarts.sch.uk | |
| gender | End user's gender. Could be any string. | dude | |
| birthdate | End user's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. | 1881-04-12 | |
| zoneinfo | String from zoneinfo time zone database representing the end user's time zone. | Europe/London | |
| locale | End user's locale, represented as a BCP47 \[RFC5646\] language tag. This is typically an ISO 639-1 Alpha-2 language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash. | en-UK | |
| phone_number | End user's preferred telephone number. | +44 (0) 1464 96787 | |
| address | End user's preferred postal address. The value of the address member is a JSON \[RFC4627\] structure. | Hogwarts School of Witchcraft and Wizardry, UK | |
| updated_at | Time the End user's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z. | 867628800 | |
---
language: "en"
---
# Continued integration of Keystone
Now that you've got a basic OIDC / Keystone setup working it's time to take care of how you interact with your federation customers. In most cases the preconfigured rules are all you need, but Keystone can handle [more complicated things](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims.md) if you need it to.
## Decisions to make
We don't know how your site is set up, but are assuming you already have some way of authorizing access that results in a user having a session. We'll refer to this here as your authorization flow.
You will also need to consider how the data available from Keystone will match up with whatever your site references to decide if a valid subscription is in place - we'll refer to that here as your customer database. The recommended approach is to add support for the identifiers used in federations to your customer database as this has the minimum impact on your customers, and will make the addition of new federated customers easier for you in the long run.
The site identifiers in common use in federations are:
* EntityID - this usually looks like a URL on a domain owned by the site but there doesn't have to be a web page there - e.g: `https://idp.theirdomain.net/openathens`. This is relevant to authentication, but rarely to authorization.
* Scope - this is always an internet domain owned by the site - e.g. theirdomain.net. A site might use subdomains to separate organizational units - e.g. holbycity.theirdomain.net, sacredheart.theirdomain.net.
Of the two, Scope is the identifier to use for authorization decisions as it allows large organizations to have multiple subscriptions with you, or for the subscription to be specific to one organizational unit. It also allows for the possibility of different authentication points within the same organization, although in practice this is quite rare. Support for wildcards is recommended - e.g. \*.theirdomain.net. See also: [Entities with multiple scopes such as NHS England and consortia](https://docs.openathens.net/providers/entities-with-multiple-scopes-such-as-nhs-england-.md)
Next is user identifiers.
You will receive a claim called "sub", short for subject, but this is not persistent between sessions. If you want to track an individual between sessions for personalization or statistics then there's something with the unlikely name of `eduPersonTargetedID` that is persistent for a user between sessions (called targetedID for short).
## Decisions made, what do I turn on?
Assuming you're using Scope and targetedID, the preset rules will take care of things but they need to be turned on and this is done on the connection. The ones you want are **Common EduPerson** and **Affiliation and scope derived from eduPersonScopedAffiliation**.
What you also need to know is what claim names contain the data you need as it is these claims that OIDC is making available to your system:
| **Thing you might want** | **Claim name** |
|--------------------------|-------------------------|
| Scope | `derivedEduPersonScope` |
| EntityID | `realmName` |
| targetedID | `eduPersonTargetedID` |
Now all you have to do is match up the claims to your authorization flow and allow / deny access as appropriate.
You can also [set up your own rules](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims.md) if you want the data to be available under different claim names. There are also [several other SAML attributes](https://docs.openathens.net/providers/eduperson-attributes.md) that the standard rules will translate for you, but most will rarely have data.
### Is there more data I can get?
Apart from those three above, there are two other common attributes. The main one you can reasonably expect from sites is a **role** attribute which can identify things such as member, staff, student, alum, and a few other education based items. It will usually say member and be in a claim called `derivedEduPersonAffiliation`. E.g. If your site is aimed at the education market, and should be presented differently to staff and student, your customers will be able to say that under role so you can make the determination.
If you need to do finer grained authorization such as identifying a department you can use one called `eduPersonEntitlement` which can have any value you prearrange with sites.
Any of these could be multi-valued and would be passed to your OIDC instance as an unordered array - e.g. `{ "claimName" : [ "value1", "value2"] } `
### What about things like names and email addresses?
#### Personally identifiable information like that isn't supplied as standard and data protection regulations make sites very cautious about releasing it. Some may be willing where they see a justifiable use, but you should not expect it to be present and must not make it a condition of access.
### Next
[The remaining step will be to set up WAYFless and deep link access](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-openathens-key.md). After that you're ready for final tests and publication.
---
language: "en"
---
# Creating an OpenID Connect client with Spring Boot
This document provides a step-by-step guide to creating an OIDC client using Spring Boot and Java.
OpenAthens acts as an OIDC provider, which your application will communicate with. In this example, we will use the Spring Security framework as the OIDC client, however you can use any OIDC compatible client library or plugin.
* This is sample code and is not production ready
* Proper error handling is not implemented
* Authorization is not implemented. This example shows how to obtain the claims necessary to authorize visiting users
* You will need to configure your application.properties with the details for an application that you will create with the Service Provider dashboard - [https://sp.openathens.net](https://sp.openathens.net/)
## Step 1: Initialize the project
This example uses Spring Boot and its Initializr website. You do not need to use Spring Boot; you can use any language, framework, or OIDC client of your choice.
Similarly this has been tested with Java 17 \& 21 and Spring Boot 3.4.2. For other frameworks, versions and libraries, please refer to the documentation of your framework of choice.
Use Spring Initializr () to create a new Spring Boot project with the following dependencies, using Maven:
* Spring Web
* Spring Security
* OAuth2 Client
Make the following changes to the autogenerated project following your desired package structure:
* Add an empty Java file OAuth2SecurityConfig.java (step 2)
* Add an empty Java file ClaimsDebugController.java (step 3)
* Spring Boot should have created a file called `application.yml` or `application.properties` in resources.
This example uses the YAML style config, so you may need to rename the config file from ".properties" to ".yml".
## Step 2: Configure security
Add the following to OAuth2SecurityConfig.java. This security config tells Spring Security to protect every endpoint except '/' and to route unauthenticated requests via the configured OIDC provider.
Java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
@EnableWebSecurity
public class OAuth2SecurityConfig {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity httpSecurity, ClientRegistrationRepository clientRegistrationRepository) throws Exception {
httpSecurity.authorizeHttpRequests(requests ->
requests.requestMatchers("/")
.permitAll()
.anyRequest()
.authenticated())
.oauth2Login(Customizer.withDefaults());
return httpSecurity.build();
}
}
## Step 3: Create controllers
Add the following to ClaimsDebugController.java. This controller simply provides the user claims as a JSON response. In a production application, you would not do this, but rather use the claims obtained to establish whether the authenticated user belongs to a subscribing organization and should be authorized.
Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
@RestController
public class ClaimsDebugController {
private final ObjectMapper mapper;
@Autowired
public ClaimsDebugController(ObjectMapper mapper) {
this.mapper = mapper;
}
@GetMapping(value = "/claims", produces = "application/json")
public ResponseEntity get(@AuthenticationPrincipal OidcUser oidcUser) {
try {
return ResponseEntity.ok(mapper.writerWithDefaultPrettyPrinter().writeValueAsString(oidcUser.getClaims()));
} catch (JsonProcessingException e) {
throw new RuntimeException(e);
}
}
}
## Step 4: Create an application in the Service Provider Dashboard
1. Access the Service Provider dashboard: .
2. [Create a new OIDC application](https://docs.openathens.net/providers/quickstart-for-openathens-keystone.md).
3. In the configuration tab of the OIDC application you created, set the redirect URL to be . (This assumes you are running locally. Set the domain and port as appropriate.)
4. Keep this tab open for the next step, where you will need the client ID and secret.
## Step 5: Configure "application.yml" in your project
Replace the contents of the `application.yml` file with the below.
You **only**need to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET below with the necessary details obtained from the Service Provider dashboard to configure your OIDC client. You may need to rename the default config file from ".properties" to ".yml" though.
YAML
spring:
security:
oauth2:
client:
registration:
custom:
client-name: Example
client-id: YOUR_CLIENT_ID
client-secret: YOUR_CLIENT_SECRET
authorization-grant-type: authorization_code
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
scope: openid, profile
provider:
custom:
issuer-uri: https://connect.openathens.net
## Step 6: Run
(Still assuming you are running your application locally.)
Access and ensure that you are able to retrieve the user claims after signing in to your OpenAthens IdP with a test account.
---
language: "en"
---
# Custom report
The custom report (**Reports \> Custom report** ) enables you to see a more bespoke view of your data. You can set a custom date range and filter by specific organizations, applications or countries. You also have options to sort or break down the data. Because the custom report does not have a preset date range, it does not include the same comparison data as the [summary report](https://docs.openathens.net/providers/summary-report.md).
Like the summary report, the custom report can be downloaded as a file.
## Set date range
While the summary report has a preset choice of date ranges, the custom report allows you to select any date range from the period for which statistics are available.
The earliest date you can select is 1 August 2023, for OpenID Connect applications, or 1 January 2024 for SAML applications.
1. Click the **Date range** field. A pop-up calendar opens.
2. From the calendar, select the start date from which to view statistics. This date is loaded into the field.
3. From the calendar, select the end date from which to view statistics. This date is loaded into the field, forming a date range.
4. Press **Search**to refresh the report with your new date range.
Depending on the volume of traffic in your statistics, selecting a longer date range might cause the report to load slowly. Some reports may be too large to display in the browser, although you can still download them as a file.
## Apply filters
You can filter the report by application, organization or country.
1. Open your chosen filter to see the available options. The **Application** filter, for example, shows your published applications. If any of the options had no traffic during the selected date range, a note informs you of this so you can avoid adding that item to your report.
2. Tick each item to include in the report.
3. Press **Apply** to update the report with your selections.
4. To apply multiple filters, repeat for each filter.
### Run a report on a specific application
As well as selecting applications from the **Application** filter on this page, you can run a report on an individual application directly from the [applications list](https://docs.openathens.net/providers/applications.md).
1. Go to **Applications**.
2. Open the **Options**menu beside the application you want.
3. From the menu, select **View recent transfers report** . You are automatically taken to the **Custom report** page, where you will see a report of transfers to the selected application within the last 30 days. You can configure this report using the date range and filter options as normal.
## Set granularity of the report
After setting the date range, by default you see the total numbers across that time period. You can break the report down by increments of time, in order to see numbers for individual months or days.
From **Date granularity**, select from the following options:
* **Full range selected**. See the total numbers for all transfers from each organization across the date range.
* **By month**. Break down the report by month. For example, if your date range spans December to February, you will see the number of transfers from each organization in December, in January and in February.
* **By day**. Break down the report by day. For each organization in the report, you will see a list of the dates on which at least one transfer took place and the number of transfers that day.
## Sort data
From the **Sort by** panel, choose how you want to sort the data. The sort options depend on the selected **Date granularity**:
* **Full range selected** : sort by number of **transfers** and then by the name of the **organization**, or vice versa
* **By month** : sort by the name of the **organization** and then by **date**, or vice versa
* **By day** : sort by the name of the **organization** and then by **date**, or vice versa
The sort order is reversible. If, for example, you want to find out which organizations generate the least traffic, you can sort by number of transfers with the lowest first.
## View further detail
For each row in the report, click **Show breakdown** to see more information about the transfers that were logged.
The breakdown shows the applications to which transfers were made, and the institutional affiliation (for example, member, staff or student) of the users who made them.
Click **Hide breakdown** to return to the previous view.
### View all details
To expand the details of all rows, press **Expand all** at the top of the report. Press **Collapse all** to return to the default view.
## Download report
To download your custom report, press the **Download** button. The download is a flat CSV file that you can load into a spreadsheet or other software.
Columns in the file include:
* **Parent organization**. The top-level organization from which transfers came. For example, a university.
* **Organization** . If relevant, a sub-organization beneath the parent organization, such as a specific department in a university. Sub-organizations are identified by [scope](https://docs.openathens.net/providers/scope-matching.md). If a customer has no sub-organizations, the "organization" is effectively the same as the parent.
* **Org registration federation**. The federation (or other means of authentication) to which the organization belongs.
* **Org country**. The country in which the organization is based or is registered as an identity provider. Countries cannot be determined for 1:1 connections.
* **Org entity ID**. The unique entity ID that identifies the organization.
* **Org scope**. The scope (if any) that identifies a sub-organization.
* **Application name**. The application to which the transfer was made.
* **Application type**. Whether the application is an OpenID Connect application or a SAML application.
* **Application ID**. Client ID of the application.
* **Application entity ID**. Entity ID of the application.
* **Affiliation** . Role of the user who made the transfer, such as *Member* or *Student*.
* **Transfer date**: Date on which the activity took place.
* **Transfers**: Number of transfers meeting the specified criteria.
If you are interested in using an API to download reporting data, let us know through the feedback form on this page or by writing to [feedback@openathens.net](mailto:feedback@openathens.net).
---
language: "en"
---
# Delete an application
If you no longer need an application, you can delete it. Deleting an application cannot be undone.
When an application is deleted, historical data relating to the application is retained in [statistics reports](https://docs.openathens.net/providers/reports.md) and the [activity log](https://docs.openathens.net/providers/activity.md). However, access to this data is restricted. Only users with the [**Owner** role](https://docs.openathens.net/libraries/administrator-roles.md) can see data for deleted applications.
There are two ways to delete an application:
## From the list
1. In the **Applications** list, find the application you want to delete.
2. If the application is marked as the **Primary** one for its Keystone connection, we recommend [setting another application as primary](https://docs.openathens.net/providers/using-a-connection-for-multiple-oidc-applications.md) before you delete.
3. Click on the **Options**menu at the far right of the screen.
4. From the menu, select **Delete**.
5. A pop-up dialog appears, asking you to confirm the action. To proceed, tick **I understand the impact of deleting this application** and press **Yes, delete** .
## From the application details
1. From **Applications**, open the application you want to delete.
2. Press the **Delete application** button.
3. As before, a pop-up dialog asks you to confirm the action. To proceed, tick **I understand the impact of deleting this application** and press **Yes, delete**.
---
language: "en"
---
# Edit an application
Select from the applications list to edit an application. Keystone and external applications have slightly different options.
*Keystone example*
*External example*
## Details tab
### Status
When you are ready to go live in the OpenAthens federation you can set this to live. It always appears for external applications, but will not appear for Keystone applications until the OpenAthens federation is added to the [connection](https://docs.openathens.net/providers/keystone-connections.md).
What will happen then is...
* The logo and access URL fields become mandatory
* Use of https for endpoints is enforced
* On save you will see a preview of how your resource will appear to your customers
* Our service desk will be alerted to [run some tests](https://docs.openathens.net/providers/getting-an-application-production-ready.md) and approve your appearance in the OpenAthens federation.
### Description
A description of your product or service. It appears below the application name when seen by customers. See also: [What makes a good resource description?](https://docs.openathens.net/providers/what-makes-a-good-resource-description.md)
### Logo
This must be a jpg, png or gif of at least 128 x 128px and less than 10MB. Ideally square with a transparent background.
### Banner
Only used by the [Wayfinder discovery service](https://docs.openathens.net/providers/openathens-wayfinder.md). This must be a jpg, png or gif of at least 400 x 50px, and less than 10MB. Ideally with a transparent background.
### Information URL
This is not required, but if you want to you can add a link to a description or sales page where potential subscribers can find out how to purchase access.
### Access URL
The general access URL will be retired in the future but at the moment it is still necessary.
It is configurable by the library customer so the thing that will best suit them is to form a link using the format from the linking tab (see below) using https://idp.eduserv.org.uk/openathens as the entity and a suitable page as the target. This will work for people who edit it and for people who do not.
If this is not possible (e.g. your site is a single page app), it is acceptable to enter a general landing page as the access URL so long as the user can gain access from there.
## Linking tab
This is all about the OpenAthens Redirector. If you support both WAYFless access *and* deep linking (article level linking) then you are redirector compatible. The redirector provides our mutual customers with a consistent link format that they can use in place of a proxy mask in applications such as link resolvers and removes any need for them to use proxy servers to access your site.
What you enter here are tokenized access URLs and the internet domains that use them - e.g.
| **URL** | **Domains** |
|----------------------------------------------------------------------------|------------------------------------------------------------------------|
| `https://sp.example.com/access?entityID={entity}&destinationPage={target}` | `example.com` `example.co.uk` `example.net` `theversionforschools.com` |
Any target addresses using the listed domains will use the tokenized URL for access. There are two tokens:
* {entity} - the customer's entityID will be inserted here
* {target} - the page on which the customer wants the end user to end up
If you have any difficulty with these, our service desk will be happy to help.
There is no facility to insert non-federation identifiers for customers as tokens.
## Tabs for specific types of application
### SAML endpoints (External applications only - e.g. Shibboleth)
This will list the endpoints specified in your metadata and provide an option to edit or remove them using the dots menu. You can also add more SAML endpoints should you need to (e.g. for development boxes or load balanced services). If necessary you can manually set the index value. Changes can take [up to 6 hours](https://docs.openathens.net/providers/how-long-it-takes-to-go-live.md) to be reflected in the federation metadata.
^Keystone applications have a similar option on their connection.^
### \ entity tab (External applications only - e.g. Shibboleth)
This will display the metadata as it will appear in the federation once published.
*** ** * ** ***
## Configuration tab (Keystone only)
### How to configure your web application
This link brings up the basic implementation steps. It is the same information that was displayed when you created the application record and is available in several flavors.
#### Client ID
This is the ID used to configure your OpenID Connect instance when you add OpenAthens as a provider.
#### Client secret
This is the secret used to secure your OpenID Connect instance when you add OpenAthens as a provider.
#### Application URL
The root of your application without a trailing slash, e.g: `https://login.example.com`.
#### Redirect URL
This is where your OpenID Connect instance expects us to return the user after authentication, e.g: `https://login.example.com/oidc/redirect`.
#### Login URL
This is the link that would initiate a user login in your OIDC application - i.e. the OIDC handler that is invoked when you hit the login button. It is required to support WAYFless access and is not the same thing as the Access URL (details tab).
#### Connection
Keystone supports the sharing of connections so that multiple apps can use the same SAML connection in a federation.
## Discovery tab (Keystone only)
### Wayfinder
[OpenAthens Wayfinder](https://docs.openathens.net/providers/openathens-wayfinder.md) is the default and recommended organization discovery option.
Authorized domains: these are only used if you add the Wayfinder embed script to your site. You can leave them blank otherwise. See [Embedding OpenAthens Wayfinder](https://docs.openathens.net/providers/embedding-openathens-wayfinder.md) for details on how to configure your site to use embedded Wayfinder.
SeamlessAccess integration: enables SeamlessAccess integration with OpenAthens Wayfinder. You will need to [add the SeamlessAccess button to your web application](https://docs.openathens.net/providers/integrating-the-seamlessaccess-button.md) before enabling this functionality.
### Other central discovery service
Enter the URL of your chosen discovery service. It must support the SAML DS protocol.
### Single identity provider
Specify a single entityID to use for all logins. Ideal for single site applications such as VLEs and during testing.
## Attributes tab (all applications)
This is where you can specify the attributes that your application expects identity providers (IdPs) to release. These attributes are categorized as either required or optional and must be from the list of [standard eduPerson attributes](https://docs.openathens.net/providers/eduperson-attributes.md). Attributes added here will appear in your application metadata.
In line with federation [best practices](https://docs.openathens.net/providers/best-practices.md), you should not set attributes containing personally identifiable information as "required". Typical required attributes are eduPersonTargetedID (unique to the user) and eduPersonScopedAffiliation (provides role@organization information).
Keystone apps: [entity categories](https://docs.openathens.net/providers/keystone-connections.md) and [privacy policy](https://docs.openathens.net/providers/keystone-connections.md) links you have specified on your connection will display here for convenience.
External applications such as Shibboleth: the entity categories and privacy policies displayed in this tab are taken from the metadata when you upload it.
## IdP support tab (all applications)
Here you can add any support email addresses and specify your preferred activation method for the application. This is to make it easier for your customers and your support people when customers want to enable access.
For Keystone applications, any email addresses added here will also be added to the application metadata.
### Preferred activation method
The preferred activation method is how you want your OpenAthens customers to contact you about enabling access. The idea is to minimize back and forth between our mutual customer and your support team by making sure they send the information you need to where it needs to go. You can choose one of four options:
* **Email**
Specify the email address to write to. You can include parameters if you wish, e.g. ?subject=
Add any other details in the boxes below. There's a check box for when a customer's subscription ID is important to specify.
* **Portal**
Specify the web address of the portal, including the protocol (e.g. https) and some basic instructions.
* **Webform**
Specify the web address of the form, including the protocol (e.g. https).
* **Other**
Any process not covered by the other three.
---
language: "en"
---
# eduPerson attributes
A list of the eduPerson attributes that might be encountered in federations around the world. The highlighted ones are generally common to all. The others are... unlikely to come up outside of a local context. The **Claim** column is relevant only if you are [using the eduPerson mapping rule in OpenAthens Keystone](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims.md).
There is a button above the table to expand it.
| **SAML attribute** | **What is it?** | **Typical value where relevant** | **Claim (assumes use of** [**the preconfigured rulesets**](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims.md)**)** | **Corresponding attribute releasable by OpenAthens** |
|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.1` | Not generally used in the OpenAthens federation. The role part of "scopedAffiliation" of the user. | `member` | ^eduPersonAffiliation^ | Role |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.2` | Not generally used in the OpenAthens federation. A persons nickname or preferred form of address. | `bob` | ^eduPersonNickname^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.3` | Not used in the OpenAthens federation. Little reason to use in any federation. The DN of the directory entry of the user's organization. | `DN=directory, CN=organization, CN=org` | ^eduPersonOrgDN^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.4` | Not used in the OpenAthens federation. Little reason to use in any federation. The DN of the directory entry of the user's organization unit. | `OU=campus, DN=directory, CN=organization, CN=org` | ^eduPersonOrgUnitDN^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.5` | Not generally used in the OpenAthens federation. Little reason to use in any federation. A version of eduPersonAffiliation limited to a single value. | `organization.org` | ^eduPersonPrimaryAffiliation^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.6` | Not generally used in the OpenAthens federation. The UPN of the user. Resembles an email address but should not be expected to be one. | `string@organization.org` | ^eduPersonPrincipalName^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.7` | **The "Entitlement" value for a user. This one is** ***technically*** **in common usage, but few service providers ask for it.** **Is used to do more granular groupings than roles - e.g. if a library service could not afford to buy access for all 20,000 students, but could for the 150 geology staff and students, they could pass you an entitlement value for just the geologists, and you can make a sale.** **You define the value that you want them to pass for the group of users.** | ^geology^ | ^eduPersonEntitlement^ | Entitlement |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.8` | Not used in the OpenAthens federation. Little reason to use in any federation. Essentially the same as eduPersonOrgUnitDN and just as useful. | | ^eduPersonPrimaryOrgUnitDN^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.9` | **The "scopedAffiliation" of the user. A two part identifier consisting of a role and a federation_scope. This attribute may be multi-valued so if using any part of this for authorization the condition should be inclusive rather than exclusive. This is generally released by default for any user in any federation.** **Role values are defined by the federation. Most federations are academic, so roles are typically one or more of:** ***member, staff, student, faculty, alum, library-walk-in, affiliate, employee*** **.** **The federation scope is the organization identifier and can identify sub-organizations too - e.g. a group of hospitals might have a root federation scope of** `eng.nhs.uk`**, but an individual hospital might have the scope of** `holbycity.eng.nhs.uk`**. This facilitates activities such as selling access to the whole group by authorizing on** `*.eng.nhs.uk`**, or supplying specific OUs in the group.** **It is best to base authorization on the claim(s) in this attribute.** | `member@organization.org` `staff@organization.org` | ^eduPersonScopedAffiliation^ | Role (scoped) |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.10` | **The "targetedID" of the user. An opaque user ID that is provided by default for any OpenAthens federation user, and is in general use in all major federations.** **It is persistent for a user so long as federation entityIDs do not change.** **It is being depreciated in favour of** [**Pairwise-ID**](https://docs.openathens.net/providers/about-pairwise-id.md) | `3d6qquvckr9vcauasrp3g13rur` | ^eduPersonTargetedID^ | Targeted ID |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.11` | Not generally used in the OpenAthens federation, though is becoming more standard and might be required by some service providers. Asserts that the organisation's identity provider complies with specific trust and quality standards. See [REFEDS Assurance Framework version 2.0](https://refeds.org/wp-content/uploads/2023/12/RAF-2.0-Final-version.pdf) (.pdf). (An alternative method is to use entity categories. See: [REFEDS: Entity categories](https://wiki.refeds.org/display/ENT/Entity-Categories+Home).) | `https://refeds.org/assurance` | ^eduPersonAssurance^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.12` | Not used in the OpenAthens federation. Multi-valued set of previous eduPersonPrincipalNames the user may have had. | ^something@organization.org^ ^another@organization.org^ | ^eduPersonPrincipalNamePrior^ | |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.13` | Not generally used in the OpenAthens federation. A persistent user identifier expected to be unique within a federation. Very unlikely to ever come up. | ^oifh845oi8sd85o87a4hi8ai4ai8ah.federation^ | ^eduPersonUniqueId^ | Unique ID |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.14` | Could be used in the OpenAthens federation. ORCID iDs are persistent digital identifiers for individual researchers. Their primary purpose is to unambiguously and definitively link them with their scholarly work products. ORCID iDs are assigned, managed and maintained by the [ORCID organization](http://orcid.org/) | ^http://orcid.org/1234-5678-1234-5678^ | ^eduPersonOrcid^ | |
| `urn:oasis:names:tc:SAML:attribute:pairwise-id` | **A unique identifier designed to replace eduPersonTargetedID.** **Will be increasingly used in all federations. See:**[**About Pairwise-ID**](https://docs.openathens.net/providers/about-pairwise-id.md) | ^OWI3YCR14MOJA8OGKJEN5TGWN=@organization.org^ | ^pairwiseID^ | Pairwise ID |
---
language: "en"
---
# Embedding OpenAthens Wayfinder
[Wayfinder](https://docs.openathens.net/providers/openathens-wayfinder.md) can be embedded into your site if you are using OpenAthens [Keystone](https://docs.openathens.net/providers/openathens-keystone.md). Which is kinda cool.
## Get the code from the service provider dashboard
1. Sign in to the service provider dashboard ([https://sp.openathens.net](https://sp.openathens.net/)).
2. Go to **Applications \> select your OpenID Connect application \> Discovery tab**.
3. Scroll to the discovery method section and select the radio button for Wayfinder.
4. In the **Authorized domains** field, add the internet domain(s) where you will be using Wayfinder (e.g. `*.yourdomain.com`).
5. Click the link **How to add Wayfinder to your web application**. A pop-up opens, showing JavaScript code.
6. Copy the JavaScript.
The code is tied to the specific Keystone application since Wayfinder needs to know where to return the user. If you need to support multiple apps from a common login page you will need to find a way to insert the relevant oaAppId (colored red in the interface).
## Add the code to your website
1. Paste the JavaScript into the \ of the page (or site if necessary).
2. The code can be invoked by two methods:
1. If you want Wayfinder to appear as an overlay, use the `wayfinder-login` selector in the trigger - e.g:
`Institutional login`
2. If you want Wayfinder to appear embedded in a div, use the `wayfinder` selector, e.g:
`Loading...
`
You should not set a height on the div or search results may overflow the available space.
If neither selector is found on the page, no error is displayed to the user but one is sent to the console. If both are on the page then the `wayfinder` selector will be used (embedded).
### Which should I choose?
It's up to you of course, but we would suggest that where your login function is in a small area of a regular page then the overlay is probably the better choice as searching for organizations can produce several answers. If your login function is on a dedicated page then the div version may fit in better with the UX and style. Both will allow you to customize the labels - see the advanced options section below.
When testing, try some terms that will produce many results (such as University) and use the show more results button.
## Federations
The OpenAthens federation will be updated automatically. If you are in other federations, they will have to update your metadata to include valid discovery return URLs before Wayfinder can work for you:
XML
## Advanced operations
Some advanced information for anyone who needs a little more control.
See the information
### Logic flow
### _wayfinder.options
These allow some changes of behavior. Add them to the end of the script block you got from the dashboard, for example:
#### **Example**
The options currently available are:
| **N** | **Type** | **Notes** |
|-------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| trigger | String | If you do not wish to use the default CSS selector name you can specify an alternative target or trigger (not both). |
| target | String | If you do not wish to use the default CSS selector name you can specify an alternative target or trigger (not both). |
| enableGeolocation | Boolean | If omitted, or has any value other than true, geolocation hints are disabled. |
| rememberCrossSite | Boolean | If omitted, or has any value other than false, selected organizations are remembered for and from selections at other sites |
| ui | Object | | **N** | **Type** | **Default text (en, en-GB)** | **Notes** | |-----------------------------------|----------|-------------------------------------|--------------------------------------------------------------------------| | titleText | String | Find your institution | When undiscovered / no remembered organization | | summaryText | String | Your university, company or library | When undiscovered / no remembered organization | | placeholderText | String | Institution name or email... | When undiscovered / no remembered organization Appears in the search box | | previousSearchUITitleText | String | Search for your institution | Where there are remembered organizations | | previousSearchUISummaryText | String | Institutions you've selected before | Where there are remembered organizations | | previousSearchUISearchAgainText | String | Search for another institution | Where there are remembered organizations | | previousSearchUIDeleteResultsText | String | Delete institution | Where there are remembered organizations Appears in a button | If omitted or of zero length the default is used. If your text includes quote marks or apostrophes they will need to be escaped. The default text will use any relevant localizations we have uploaded. |
| buttonOptions | Object | | **N** | **Type** | **Default setting** | **Options** | |-------|----------|---------------------|-------------| | size | String | medium | small | |
More options may become available in the future.
#### About Geolocation
Geolocation can help users select the correct organization when none are shown, but means the browser will ask for permission when it hits any page with the Wayfinder JavaScript in the head. If Wayfinder will appear on multiple pages we recommend leaving this function disabled.
#### About rememberCrossSite
The default and recommended mode is to allow the organization selection a user made elsewhere using Wayfinder to be reflected in your instance (and also the organization selection made in your instance available elsewhere). This provides the best user experience, however you can turn it off with this option if you need to limit it to just remembering choices on your site - e.g. if the users commonly need to use a different IdP to access your site.
#### Customizing the appearance
Retaining the default appearance of the embedded Wayfinder is encouraged as this provides a consistent user experience across sites (one of its goals). If you must change the appearance (such as when the colors clash with your brand), then you can override the styles for some key classes in your CSS. Here is an example:
##### Overlay button
The overlay version is invoked by a button which has three possible appearances and uses the `.wayfinder-button` class. The third one is for when Wayfinder remembers a user's previous selection, and has a `.active` class. Let's use three shades of blue in our example:
###### **Overriding the color of the embedded Wayfinder button**
CSS
.wayfinder-button {
background-color: #007bff !important;
}
.wayfinder-button:hover,.wayfinder-button.active:hover {
background-color: #007ba8 !important;
}
.wayfinder-button.active {
background-color: #0014ff !important;
}
(The `!important` bit is to ensure you override the default appearance.)
---
language: "en"
---
# Enabling federations
The connection for your application (accessed from **Keystone settings \> Keystone connections** or through a link in the application's Details tab) is where you configure the federations of which Keystone is aware.
At the bottom of the page are all the federations you can add - toggle the switches on or off and save to make the data available to Keystone. This does not add you to those federations - that is a function of the federation operators - see: [How to join other federations](https://docs.openathens.net/providers/how-to-join-other-federations.md).
The OpenAthens section covers the OpenAthens Federation. The [1:1 connections section](https://docs.openathens.net/providers/entities-that-are-not-in-a-federation.md) is for manually adding individual IdPs that are not in a common federation. The rest are common federations around the world.
There are some information and status icons that can appear. In each case, hovering over them will reveal more detail.
There is a simple error check that will flag differences in the local and remote metadata. The check is very simplistic and things like formatting can occasionally produce false positives.
---
language: "en"
---
# Enabling OpenAthens Wayfinder
Wayfinder uses the SAML DS protocol. As long as your service provider 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 offer support only 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](https://docs.openathens.net/providers/openathens-wayfinder-for-non-members.md)
## OpenAthens Keystone
1. Sign in to the Service Provider dashboard ([https://sp.openathens.net](https://sp.openathens.net/)).
2. Go to **Applications \> select the relevant application \> Discovery tab**.
3. Scroll to the discovery method section and select the radio button for Wayfinder. If you joined after July 2024, this will already be enabled.
4. 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](https://docs.openathens.net/providers/embedding-openathens-wayfinder.md)
The OpenAthens Federation will be updated automatically. 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
See also:
* [Integration with SeamlessAccess](https://docs.openathens.net/providers/integrating-the-seamlessaccess-button.md)
### Shibboleth
To use hosted Wayfinder with Shibboleth, add or update the discovery response binding in your metadata in the \ section. E.g:
...
...
... then add the discovery service to your `shibboleth.xml` configuration file. It goes in the SSO section in place of any singular identity provider (IdP) definition:
SAML2 SAML1
### SimpleSAML.php
To use hosted Wayfinder with SimpleSAME.php, set the options in `authentication.php` and then restart the service:
* `'discoURL'` `=> '`[https://wayfinder.openathens.net](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 service provider dashboard:
1. Once you are logged in to the [service provider dashboard](https://sp.openathens.net/), go to **Applications**and select your external application.
2. Go to the **SAML endpoints** tab and click the **Add endpoint**button.
3. Select **Discovery return URL** , enter the value and click **Done**.
4. You can now see your new endpoint in the list. 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 `` 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, download a federation's metadata and see if your entity appears. If it's there, check that it includes a `` section that specifies Wayfinder. The [REFEDS metadata explorer tool](https://met.refeds.org/) is also an option, but may be a day or so behind.
#### 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](https://docs.openathens.net/providers/testing-openathens-wayfinder.md) turned on, you will also see entities that are marked in the metadata as hidden.
* Federations -
* Keystone users: The federation toggles on your Keystone connection in the Service Provider 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](https://docs.openathens.net/providers/how-to-join-other-federations.md), 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. Time zones and weekends play a part in how long it could take
* If an institution has sub-organizations with [unique identifiers](https://docs.openathens.net/libraries/about-unique-identifiers.md), the sub-organizations will appear as separate entities in Wayfinder
* [Debug mode](https://docs.openathens.net/providers/testing-openathens-wayfinder.md) - this will, when enabled on your browser, tell Wayfinder to include entities that have a hide from wayf entity category on them.
---
language: "en"
---
# 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** .
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.
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:
\
**X509 certificate**: appears twice in the metadata in a \ 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](https://docs.openathens.net/providers/error-messages-in-openathens-keystone.md) 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](https://docs.openathens.net/support/openathens-service-desk-and-support.md).
It can take up to six hours for changes to propagate fully.
---
language: "en"
---
# Entities with multiple scopes such as NHS England and other consortia domains
IdPs can have several organizational units, especially if they are large or multinational. In these large organizations, the different units may need to access different resources, or where the same resource is accessed they may need different subscription levels. We call these types of IdP a consortia domain.
In a federation, the scope is used to identify organizations, and it is also used to differentiate organizational units (or sub-organizations) when necessary. In the OpenAthens federation this is done by adding an additional identifier in front of the domain scope - e.g:
| **Where** | **Scope is** |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| Organizational units will **not** need to be differentiated | `customer.com` |
| Organizational units will need to be differentiated (an identifier is included for the domain organization) | `identifier1.customer.com` |
| An organizational unit within the consortia needs to be uniquely identified - e.g. an NHS Trust, or a multinational corporation's national office (uses a scope with a different identifier) | `identifier2.customer.com` |
| An organizational unit within the consortia does not need to be uniquely identified - e.g. a GP surgery within an NHS Trust, or a branch office. (uses the same scope as its parent organization) | `identifier1.customer.com` |
The identifier used is their OpenAthens organization number. You can see a good example of this in the NHS England [organization list](https://login.openathens.net/org-list).
## How this applies to authorization
Where a customer is a consortia domain and if they are purchasing on behalf of the whole domain, they would supply their scope as `*.customer.com`. Individual organizational units would supply their discrete scope if they were purchasing different content.
If you sell or plan to sell to this kind of consortia, your authorization process will need to be flexible enough to match on a wildcarded scope as well as discrete scopes.
Examples:
* The NHS England wildcarded scope would be `*.eng.nhs.uk`.
* NHS England trust specific scopes would look like `1345345.eng.nhs.uk, 9853784.eng.nhs.uk, 1047384.eng.nhs.uk... etc`.
## How this benefits you and your users
Because the targeted IDs used in federated access management are generated based on entity IDs, this means that where a user moves around their consortia domain, the identifier you see for them stays the same so can be used for personalization, but the scope that is passed for them can change which means they see the content appropriate to whichever part of the consortia they currently belong to.
Using NHS England as an example again, this might be when a doctor finishes their rotation and moves to another hospital or practice.
See also: [OpenAthens federation metadata extensions](https://docs.openathens.net/providers/openathens-federation-metadata-extensions.md)
---
language: "en"
---
# Error messages in OpenAthens Keystone
The following error messages might be produced by parts of the Keystone service and they are usually only seen during development. Any other error messages shouldn't be from Keystone itself - our service desk will be happy to help you diagnose them.
| Message | On domain | Caused by | Means |
|---------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Unable to login this time, Please contact Service Desk | [**connect**.openathens.net](http://connect.openathens.net/) | A SAML authentication failure | The SAML response could not be processed. Very unlikely to come up unless and until you connect to other federations. |
| OpenId application not found with id $applicationId | [**connect**.openathens.net](http://connect.openathens.net/) | Application not found | The application your configuration references isn't there. Most likely caused by a typo when you copied over in the Client ID, but could also be caused by deleting the application record. |
| Could not find acs with saml2 post binding | [**connect**.openathens.net](http://connect.openathens.net/) | ACS not found for the specified connection | No Association Consumer Service bindings were found. Most likely caused by editing the bindings or deleting the connection. |
| Connection $ConnName is not associated with a federation | [**connect**.openathens.net](http://connect.openathens.net/) | Connection is not associated with a federation | You do not have any SAML federations connected. |
| Invalid rule type specifed | [**connect**.openathens.net](http://connect.openathens.net/) | Invalid rules | Most likely caused by obscure parts of a regex (uses Java regex) or there could be something in a javascript rule that prevents it running at all. |
| Entity $entityID not found | [**connect**.openathens.net](http://connect.openathens.net/) | Could not find IDP entity | The SAML Identity Provider is not in any of the SAML federations you have connected. |
| Could not contact mds service Could not fetch connection $connectionId from CSP Could not fetch rules for connection $connectionId from CSP | [**connect**.openathens.net](http://connect.openathens.net/) | Internal server error | Something unexpected is happening at our end. Be a pal and let us know. |
| Missing redirection URI Application is not associated with a connection Invalid client id | [**connect**.openathens.net](http://connect.openathens.net/) | Bad request | Something unexpected is happening with your OIDC client, e.g. it might be OpenID rather than OpenID Connect |
| Unable to process response for debug | [**login**.openathens.net](http://login.openathens.net/) | Authentication exception contacting the ACS | The SP's Association Consumer Service is not playing along. May have been caused by editing your endpoint configuration. |
| Failed to contact admin API | [**login**.openathens.net](http://login.openathens.net/) | The authentication point could not contact the OpenAthens back end to authenticate the user | Something unexpected is happening at our end. Be a pal and let us know. |
---
language: "en"
---
# Extended attributes in the OpenAthens Federation
As well as the standard attributes, OpenAthens IdPs are capable of sending the following additional attributes for things like personalization. The attribute names are:
* **forenames**
* The first name of the account holder as recorded on the system.
* **surname**
* The last name of the account holder as recorded on the system.
* **emailAddress**
* The email address recorded on the account.
While you can make use of these attributes if present you should neither expect nor require them because local data protection laws, policies, user objections or other restraints may prevent an IdP from releasing these to you. Consequently you must not use them for authorization.
## **Example of these attributes within a SAML assertion**
XML
...
Picard
Jean Luc
jeanluc.picard@starfleet.mil
...
Our customers can release additional attributes under almost any name that is mutually agreed, but as this kind of 1:1 agreement can get incredibly complex for all parties in a federated context it is best to use standard attributes.
---
language: "en"
---
# Federation metadata
The OpenAthens Federation Metadata is published at:
## ETag support
If your application supports it, you can check the [ETag](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag) and avoid re-fetching unchanged metadata.
## EntityAttributes
Optional and may not appear for all entities. We use the macedir.org specification.
### Hide from discovery:
http://macedir.org/entity-category
`md:EntityDescriptor > md:Extensions > md:EntityAttributes > saml:Attribute#http://macedir.org/entity-category`
* `http://refeds.org/category/hide-from-discovery`
### Entity categories
http://macedir.org/entity-category-support
`md:EntityDescriptor > md:Extensions > md:EntityAttributes > saml:Attribute#http://macedir.org/entity-category-support`
* ` http://refeds.org/category/research-and-scholarship `
* ` http://www.geant.net/uri/dataprotection-code-of-conduct/v1 `
## Extensions
Extensions are usually unique to a federation and names can be different. These are ours:
`md:EntityDescriptor > md:IDPSSODescriptor > md:Extensions > mdui:UIInfo`
* `mdui:DisplayName`
* `mdui:Description`
* `mdui:Logo`
Logos, where present, may have small and/or large versions. Extensions can be unique to a federation.
---
language: "en"
---
# Getting a SAML application production ready
This page covers the tests your application needs to pass before publication in the OpenAthens Federation. The goal is not to tick boxes, but to make sure that our mutual customers get the best experience from us both. This includes being able to link seamlessly to your content from other applications. This can include content discovery services and user portals.
You should review our [best practices](https://docs.openathens.net/providers/best-practices.md) and [technical recommendations](https://docs.openathens.net/providers/technical-recommendations.md) first.
## Pre-checks to perform before submitting to OpenAthens for publication
### Organization discovery (WAYF, or Where are you from)
* There must be a method of signing in on the website via federated access. This should be labeled "institutional login".
1. Should be available on the homepage
2. Should be available on content pages
3. Should not mention specific software or technology e.g. Shibboleth/OpenAthens.
4. Should not ask user to select the federation or region their organization is from.
5. If using your own organization discovery service, it should allow organization name search alongside any other methods such as email address.
### Authentication / authorization check
* Can you log in to your application using your test OpenAthens credentials ([Configuring your OpenAthens IdP for testing](https://docs.openathens.net/providers/openathens-test-accounts.md))?
1. If successful
1. user should be able to tell that they are logged in, e.g. "Access provided by {organizationName}"
2. the login button should no longer be displayed, or be replaced by a login button (or equivalent)
2. If unsuccessful
1. user must be informed in some way that access has been denied, e.g. "You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator."
2. user should be guided towards who they should contact, e.g. "You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator."
* Can you grant/limit access to match your differing subscription/license terms, e.g. concurrent users, a specific department within an organization, or partner organizations such as overseas campuses?
### WAYFless linking
A method of bypassing the Where Are You From / organization discovery step by including an organization identifier in the URL. This identifier must be the organization's entityID.
* Must have a WAYFless link syntax that contains the identity provider's entityID, such as `https://auth.example.com/wayfless?entity={entityID}`
* e.g. `https://auth.example.com/wayfless?entity=https://idp.example.edu/entity`
* When not already logged in to OpenAthens, you should see that you are redirected to your test OpenAthens identity provider (IdP) for authentication
* after logging in, you are returned to the homepage as a recognized subscriber
### Deep-linking
* Directly from a deeper page within your application (i.e. not your homepage), go through the organization discovery process and sign in via your test IdP. You should be returned to the specific page where you started the login process.
* Via a WAYFless link. Example syntax: `https://auth.example.com/wayfless?entity={entityID}&target={contentURL}`
* e.g. `https://auth.example.com/wayfless?entity=https://idp.example.edu/entity&target=https://example.com/some/webpage`
### Personalization
* If you provide personalization, e.g. bookshelves, favorites, watch lists, CPD (Continual Professional Development) credits, any such "profiles" should be linked to the unique user identifier(s) you support via single sign-on.
* You should allow some flexibility on what attributes you need for the user identifier. While federation customers will be able to send targetedID, they are changing to Pairwise-ID. If you intend to support 1:1 connections, the customer might not be able to send either.
* We recommend building support for at least urn:oid:1.3.6.1.4.1.5923.1.1.1.10 (eduPersonTargetedID), and urn:oasis:names:tc:SAML:attribute:pairwise-id (Pairwise-ID) as a minimum for federation users.
* Profile provisioning - you should consider the provisioning options you support and whether they may be configurable per organization. Things to consider:
* Personally Identifiable Information (PII) should not be required
* Auto-provisioning of new profiles
* Whether a user needs to self-register
* registering should be optional
* not registering should still allow access to content
* continuing without registering personally identifiable information should still allow personalization
* If you provide a registration form, or require PII, some organizations may request you to disable this for all of their users
### Logout functionality
* If you provide a logout function, it must not automatically log the user out of their single sign-on system. It may offer the user the choice to do so.
## Preparation before submitting to OpenAthens for testing and publication
### Enable access to our test organizations
To run our tests, we will need access to one or more parts of your application. This could be an individual product, package or area - basically enough access to test your application and compare the experiences when trying to access content we do and do not have access to.
Access will need to be enabled in two areas:
1. Trust will need to be established between your SAML SP and our SAML IdP:
1. If your service provider is registered within the UK Access Management Federation, trust will already be established with our test IdP. If not, your service provider will need to consume our metadata found here:
2. If you have added the OpenAthens federation metadata, you will need to temporarily remove it to avoid a clash of endpoints
2. Within your application: You will need to enable access within your subscription / entitlement / access control system etc. The details for our test identity provider are as follows:
| **Organization name** | **Entity ID** | **Scope** |
|----------------------------------------------|--------------------------------------------|------------------------------|
| University of OpenAthens | `https://idp.ps.openathens.net/openathens` | `ps.openathens.net` |
| University of OpenAthens - Specialist School | `https://idp.ps.openathens.net/openathens` | `72265896.ps.openathens.net` |
No other test organizations should have access enabled, and users should, therefore, be refused and presented with a helpful message indicating that they do not have access. These other test organizations will have the same entityID but a different scope.
The application must be able to accept multiple `eduPersonScopedAffiliation` attributes, e.g. `member@ps.openathens.net` and `staff@ps.openathens.net`.
You can remove this authorization once you are live.
## Review customer-facing resource information shown to OpenAthens customers
Check all the information for your application within the Service Provider dashboard is production ready.
### Details tab
* The *name* , *description* , *logo* , and *banner* should all be approved by your marketing or product management team. See: [What makes a good resource description](https://docs.openathens.net/providers/what-makes-a-good-resource-description.md)
* You should have a general *access URL* that will authenticate users via OpenAthens. See: [Access URLs](https://docs.openathens.net/providers/access-urls.md)
### Linking tab
* Add all relevant WAYFless/deep-linking syntaxes and the associated *service domains* for generating customer-specific login links to your application. See: [WAYFless access and deep linking in the OpenAthens federation](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-the-openathens.md)
### SAML endpoints
* Make sure your ACS URLs are correct
### Attributes
* You have added all [required and optional attribute information](https://docs.openathens.net/providers/edit-an-application.md)
### IdP support
* You have included details on your preferred method of contact for enabling access to your product
### SAML entity
* Ensure your EntityID contains a domain name that you own or have permission to use and reflects what you want to see in production, i.e. do not reference environments.
## Submit a publication request
* If you have an implementation ticket with OpenAthens, update it to request that we test and publish your application within the OpenAthens Federation
* If you do not yet have an implementation ticket, please raise one via [support.openathens.net](https://support.openathens.net/jsm/openathens/customer/portal/4)[...](https://support.openathens.net/) and request that we test and publish your application within the OpenAthens Federation
If testing runs smoothly, this shouldn't take long, but it's not the only consideration. You should allow time for:
* Mitigation, if testing finds any problems
* Customer communication - See: [Launching to our mutual customers](https://docs.openathens.net/providers/launching-to-our-mutual-customers.md)
* Customers making required updates at their end
If your go-live date is aspirational, let us know what you're hoping for as soon as you can.
If your go-live date is fixed, we suggest being ready for testing about four weeks ahead.
---
language: "en"
---
# Getting an application production ready
After you [create an application](https://docs.openathens.net/providers/add-an-application.md), there are several steps to perform before it is ready to publish in the OpenAthens Federation (where relevant) and in the [resource catalog](https://docs.openathens.net/libraries/catalogue.md). Once published, the application is available to end users.
## Overview of the testing and publication process
### You:
* Ensure that you provide a standard way for users to log in through federated access
* Test that WAYFless linking works
* Test that deep links to content work
* Test features for personalizing the user experience, if any
* Test logging out
* Check that all required information about the application has been completed in the service provider dashboard. (For OpenID Connect applications, only data about the **primary** application for a Keystone connection will be included in the OpenAthens Federation metadata and resource catalog)
* Tell us your preferred schedule for going live
* Provide access for OpenAthens to perform tests at our end
* When ready, ask us to test and publish your application
* Publicize the newly available resource to customers and institutions (we can help with this)
### We:
* Perform our own set of tests
* Inform you of any problems so that they can be fixed before launch
* Publish the application
* If required, [let our mutual customers know that your application is now available to use](https://docs.openathens.net/providers/launching-to-our-mutual-customers.md)
A [Keystone connection](https://docs.openathens.net/providers/keystone-connections.md) (representing a single SAML entity) can have multiple applications (which can represent different resources). If a connection has multiple applications, one application is designated as **primary**. Only this application is shown in the OpenAthens Federation metadata and in the resource catalog.
When configuring applications, ensure that those you want end users to access are marked as **primary**. If you have multiple applications that you want to be visible to users, give each one a separate connection.
## Details
The precise checks to perform depend on the type of application. For full details, see the following pages:
* [Getting production ready with Keystone](https://docs.openathens.net/providers/getting-production-ready-with-keystone.md), for OpenID Connect applications
* [Getting a SAML application production ready](https://docs.openathens.net/providers/getting-a-saml-application-production-ready.md) , for SAML applications
---
language: "en"
---
# Getting production ready with Keystone
This page covers the tests your application needs to pass before publication in the OpenAthens Federation. The goal is not to tick boxes, but to make sure that our mutual customers get the best experience from us both. This includes being able to link seamlessly to your content from other applications. This can include content discovery services and user portals.
You should review our [best practices](https://docs.openathens.net/providers/best-practices.md) and [technical recommendations](https://docs.openathens.net/providers/technical-recommendations.md) first.
## Pre-checks to perform before submitting to OpenAthens for publication
### Organization discovery (WAYF, or Where are you from)
* There must be a method of signing in on the website via federated access. This should be labeled "institutional login".
1. Should be available on the homepage
2. Should be available on content pages
3. Should not mention specific software or technology, e.g. Shibboleth/OpenAthens.
4. Should not ask user to select the federation or region their organization is from.
5. If using your own organization discovery service, it should allow organization name search alongside any other methods such as email address.
Examples:
#### Authentication / authorization check
* Can you sign in to your application using your test OpenAthens credentials ([Configuring your OpenAthens IdP for testing](https://docs.openathens.net/providers/openathens-test-accounts.md))?
1. If successful
1. user should be able to tell that they are signed in, e.g. "Access provided by {organizationName}"
2. the login button should no longer be displayed, or is replaced by a logout button (or equivalent)
2. If unsuccessful
1. user must be informed in some way that access has been denied, e.g. "You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator."
2. user should be guided towards who they should contact, e.g. "You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator."
* Can you grant/limit access to match your differing subscription/license terms, e.g. concurrent users, a specific department within an organization, partner organizations such as overseas campuses?
#### WAYFless linking
A method of bypassing the Where Are You From / organization discovery step by including an organization identifier in the URL. This identifier must be the organization's entityID.
* Must have a WAYFless link syntax that contains the identity provider's entityID, such as `https://auth.example.com/wayfless?entity={entityID}`
* e.g. `https://auth.example.com/wayfless?entity=https://idp.example.edu/entity`
* When not already logged in to OpenAthens you should see that you are redirected to your test OpenAthens identity provider (IdP) for authentication
* after signing in, you are returned to the homepage as a recognized subscriber
#### Deep-linking
* Directly from a deeper page within your application (i.e. not your homepage), go through the organization discovery process and sign in via your test IdP. You should be returned to the specific page where you started the login process.
* Via a WAYFless link. Example syntax: `https://auth.example.com/wayfless?entity={entityID}&target={contentURL}`
e.g. `https://auth.example.com/wayfless?entity=https://idp.example.edu/entity&target=https://example.com/some/webpage`
#### Personalization
* If you provide personalization, e.g. bookshelves, favorites, watch lists, or CPD (Continual Professional Development) credits, any such "profiles" should be linked to the unique user identifier(s) you support via single sign-on.
* You should allow some flexibility on what attributes you need for the user identifier. While federation customers will be able to send targetedID, they are changing to Pairwise-ID. If you intend to support 1:1 connections, the customer might not be able to send either.
* We recommend building support for at least urn:oid:1.3.6.1.4.1.5923.1.1.1.10 (eduPersonTargetedID), and urn:oasis:names:tc:SAML:attribute:pairwise-id (Pairwise-ID) as a minimum for federation users.
* Profile provisioning - you should consider the provisioning options you support and whether they may be configurable per organization. Things to consider:
* Personally Identifiable Information (PII) should not be required
* Auto-provisioning of new profiles
* Whether a user needs to self-register
* registering should be optional
* not registering should still allow access to content
* continuing without registering personally identifiable information should still allow personalization
* If you provide a registration form, or require PII, some organizations may request you to disable this for all of their users
#### Logout functionality
* If you provide a logout function, it must not automatically log the user out of their single sign-on system. It may offer the user the choice to do so.
## Preparation before submitting to OpenAthens for testing and publication
### Enable access to our test organizations
In order for us to run our tests we will need access to one or more parts of your application. This could be an individual product, package or area - basically enough access to test your application and compare the experiences when trying to access content we do and do not have access to.
Access will need to be enabled in two areas:
1. Within your Keystone connection - turn on the switch for OpenAthens test identity providers.
1. Leave the switch for live identity providers off.
2. Save the connection.
2. Within your application: You will need to enable access within your subscription / entitlement / access control system etc. The details for our test identity provider are as follows:
| **Organization name** | **Entity ID** | **Scope** |
|----------------------------------------------|--------------------------------------------|------------------------------|
| University of OpenAthens | `https://idp.ps.openathens.net/openathens` | `ps.openathens.net` |
| University of OpenAthens - Specialist School | `https://idp.ps.openathens.net/openathens` | `72265896.ps.openathens.net` |
No other test organizations should have access enabled, and users should, therefore, be refused and presented with a helpful message indicating that they do not have access. These other test organizations will have the same entityID but a different scope.
The application must be able to accept multiple `eduPersonScopedAffiliation` attributes, e.g. `member@ps.openathens.net` and `staff@ps.openathens.net`.
You can remove this authorization once you are live.
## Review customer-facing resource information shown to OpenAthens customers
Check all the information for your application within the Service Provider dashboard is production ready.
### Details tab
* The *name* , *description* , *logo* , and *banner* should all be approved by your marketing or product management team. See: [What makes a good resource description](https://docs.openathens.net/providers/what-makes-a-good-resource-description.md)
* You should have a general *access URL* that will authenticate users via OpenAthens. See: [Access URLs](https://docs.openathens.net/providers/access-urls.md)
### Linking tab
* Add all relevant WAYFless/Deep-linking syntaxes and the associated *service domains* for generating customer-specific login links to your application. See: [WAYFless access and deep linking in OpenAthens Keystone](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-openathens-key.md)
### Discovery
* An organization discovery service has been configured to allow users to sign in to your application when navigating directly to your site, e.g. from a search engine
### Attributes
* You have added all [required and optional attribute information](https://docs.openathens.net/providers/edit-an-application.md)
### IdP support
* You have included details on your preferred method of contact for enabling access to your product
### Check that your Keystone connection in the Service Provider dashboard is production ready
#### SAML Connector
* Ensure your EntityID contains a domain name that you own or have permission to use and reflects what you want to see in production, i.e. do not reference environments
* Ensure you have added your appropriate [privacy policy](https://docs.openathens.net/providers/keystone-connections.md) link(s)
## Submit a publication request
* If you have an implementation ticket with OpenAthens, update it to request that we test and publish your application within the OpenAthens Federation
* If you do not yet have an implementation ticket, please raise one via [support.openathens.net](https://support.openathens.net/jsm/openathens/customer/portal/4)[...](https://support.openathens.net/) and request that we test and publish your application within the OpenAthens Federation
If testing runs smoothly, this shouldn't take long, but it's not the only consideration. You should allow time for:
* Mitigation, if testing finds any problems
* Customer communication - See: [Launching to our mutual customers](https://docs.openathens.net/providers/launching-to-our-mutual-customers.md)
* Customers making required updates at their end
If your go-live date is aspirational, let us know what you're hoping for as soon as you can.
If your go-live date is fixed, we suggest being ready for testing about four weeks ahead.
---
language: "en"
---
# Glossary
## Affiliation
A user's role in their organization, taken from a list of preset terms. Affiliations include *member* , *staff* , *student* and *alum* . See also [scope](https://docs.openathens.net/providers/glossary.md#Scope).
## Application
An application represents a resource, product or service, such as an online journal. There are two types of applications. OpenID Connect applications are generated by the OpenAthens Keystone software. External or SAML applications use third-party SAML software.
## Attribute
A piece of information about an object, usually a user, supplied by an identity provider.
* [Standard attributes in the OpenAthens federation](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
* [Extended attributes in the OpenAthens federation](https://docs.openathens.net/providers/extended-attributes-in-the-openathens-federation.md)
## Authentication \& authorization
Authentication is the checking of user credentials, which in a federated context is done by the identity provider. Authorization is whether or not they can access a thing which is decided by the service provider based on the user's scope and attributes.
## Connection
The complement to a Keystone application is the connection. This is where you select rules and which federation's metadata to use.
## Deep linking
Setting up your site so that a link can send the user directly to the signed-in version of a page.
## Discovery
The way a user accessing an SP identifies to that SP which IdP they are from. Ideally a type-ahead search but sometimes just a list, this is sometimes referred to by the Shibboleth term "WAYF" (Where Are You From). Our [Wayfinder](https://docs.openathens.net/providers/openathens-wayfinder.md) option is a good and simple way of adding this to your product.
## EntityID
The unique identifier of a SAML entity. The entityID usually takes the form of a secure URI, e.g:
`https://idp.eduserv.org.uk/openathens`
## Identity Provider (IdP)
The organization that issues identities to its users, e.g. a library.
## Metadata
Information about entities. Each IdP or SP entity will have its own metadata that describe it in terms of signatures, certificates, sign-in addresses and what they support. There will also be a federation maintained central metadata which aggregates all the individual entities' metadata.
This aggregated metadata is cached by entities for quick reference. The OpenAthens federation metadata has eTag support to help with this.
## OpenAthens Keystone
A simpler way to interact with SAML federations around the world by leveraging OpenID Connect.
* [OpenAthens Keystone](https://docs.openathens.net/providers/openathens-keystone.md)
* [OIDC to SAML terminology translation](https://docs.openathens.net/providers/oidc-to-saml-terminology-translation.md)
## OpenAthens Redirector
When a resource supports both deep linking and WAYFless access, our redirector can be used by identity providers as a simple way to form access links.
* [Redirector information](https://docs.openathens.net/providers/access-urls.md)
## OpenAthens SP
An old OpenAthens software, since replaced by [Keystone](https://docs.openathens.net/providers/openathens-keystone.md).
## Parent organization and sub-organization
The entity that authenticates a user's identity when the user tries to access your content, products or services.
OpenAthens IdPs can have a hierarchy of organizational units (OUs) if needed. For some organizations, the "parent" is the only identity provider. Other organizations are divided into sub-organizations for subscription licensing purposes. Sub-organizations can have their own scope (see below), and when they do they are shown separately in statistics reports.
## SAML
Security Assertion Markup Language. The standard upon which most federations work.
* [New to SAML and federation](https://docs.openathens.net/providers/about-federation-and-federated-access-management.md)
## Scope
In federations, scope is used as in "belonging to" or "purview of" an organization. It is an identifier of an organization or an organizational unit (OU) within a larger organization. It is usually expressed as a domain and TLD owned by the organization; an OU or sub-organization's scope would include a subdomain if it needed to be identified as different, for example if parent organization and sub-organization had different subscription levels. In the OpenAthens federation, the sub-domain part is usually a number. E.g:
`domain.com`
`3032162.domain.com`
The scope is supplied as part of the scopedAffiliation attribute (see below).
## scopedAffiliation
The friendly name for `urn:oid:1.3.6.1.4.1.5923.1.1.1.9`. A user's role, such as member, staff, student.
* [Standard attributes in the OpenAthens federation](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
## Service provider (SP)
The resource provider that authorizes entry based on the scope and attributes of the user attempting access.
## Shibboleth
An open source SP software developed originally by Internet2 and supported by the community. Service Providers can use it in the OpenAthens federation if they like.
## targetedID
The friendly name for `urn:oid:1.3.6.1.4.1.5923.1.1.1.10`. It is a pseudonymous identifier for an individual user that is consistent every time the user visits an SP but different for each separate SP.
* [Standard attributes in the OpenAthens federation](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
## Transfer
The unit by which we monitor statistics. A transfer occurs when a user tries to access a service provider's content, product or service, is successfully authenticated by their own organization, and is then sent back to the service provider for authorization. It is logged whether or not the service provider subsequently grants access to the user.
## WAYFless URL
An access URL that includes the entityID of a user's IdP so that the user does not have to pass through discovery to identify their home organization to a service provider.
---
language: "en"
---
# Granular authorization
As well as the ability for [organizational units to have different scopes](https://docs.openathens.net/providers/entities-with-multiple-scopes-such-as-nhs-england-.md), a surprising amount of granularity of access is possible via the attributes passed from an IdP to an SP.
A common example would be a university or college using the **role**attribute to identify which users were students, and which were staff or perhaps alumni. This would allow the SP to show content appropriate to those types of user. A user may present multiple values for the role attribute so an "is allowed if role is X" approach is usually more appropriate than an "is not allowed if role is Y" one.
You can go further though. Let us suppose that a university library cannot afford to purchase access to a set of physics journals for all 80,000 members of the library. Rather than lose a sale, an SP might choose to sell them a license for only the 1000-strong physics department, so long as the IdP could pass an attribute that identified the users as physicists. This would typically be handled by a standard attribute (entitlement - `urn:oid:1.3.6.1.4.1.5923.1.1.1.7`) and the SP would simply ask the subscriber to pass an agreed entitlement value of, say, "physics" for just those relevant users. The SP would look for this attribute and value and only show the physics content to users that had it.
This kind of granularity has always been possible for IdPs in the OpenAthens federation.
## Can IdPs send SPs anything else?
In addition to the [standard attributes](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md), there are [some extended attributes](https://docs.openathens.net/providers/extended-attributes-in-the-openathens-federation.md) that, while not suitable for authorization, could be used for any function that the SP and IdP agreed were useful and allowable, such as personalization.
---
language: "en"
---
# How long it takes to go live
When you make changes via the dashboard on a service that is already live, they will take the following times to become active:
* Changes to your configuration such as names, descriptions, links and endpoints
* The OpenAthens Federation metadata refreshes four times per day so updates should take no more than six hours to go live. Confirm at
* The resource catalog used by identity providers in the OpenAthens Federation refreshes three times per day, so can take up to eight hours to reflect the change. This includes:
* Names, descriptions and logos
* Redirector and access URLs
* The redirector can take up to 16 hours to reflect a change depending on how the caches stack, but usually takes less than eight hours.
* For Keystone applications, changes to [1:1 connections](https://docs.openathens.net/providers/keystone-connections.md) (i.e. outside of any connected federation) should take no more than six hours to be updated in the metadata.
* These IdPs are only added to the metadata within your domain context - confirm at where CUSTOMER_DOMAIN is the scope displayed in your OpenAthens admin area (Go to: and select **Connections** from the **Management**menu)
* For other federations
* You will need to inform those federations of any changes. They will advise how long it will be before they are live.
* IdPs in other federations will usually re-cache their copy of the federation metadata daily. There may be a period where they are using your old metadata.
## OpenAthens Keystone rules
Keystone picks up changes to rules within a few seconds
## OpenAthens Wayfinder
Changes should usually take effect within five minutes of the metadata updating (e.g. entity categories, federation membership).
## External applications
External applications should have a refresh schedule and are likely to have some way to clear a cache which should be covered by their documentation.
## First live publish
When you [move from development to live](https://docs.openathens.net/providers/getting-production-ready-with-keystone.md) status, the publish button triggers a manual approval process where our service desk will run some checks before confirming the publication. Once approved, the timings above will apply to any future changes.
The publish button appears only in relation to the OpenAthens Federation.
---
language: "en"
---
# How to add the OpenAthens Federation to common SP software
If you are already using or are planning on using other SP software within the OpenAthens Federation, you will need to make it aware of the OpenAthens Federation metadata. Since terminology can sometimes vary, this page will show the federation specific settings for some common SAML SP software.
This page can only be a guide - for up-to-date installation help you should refer to the documentation and provider of whichever software you are using.
[First create the application record in the OpenAthens Federation](https://docs.openathens.net/providers/add-an-application.md#AnyotherSP).
## Shibboleth
Update your `shibboleth2.xml` file with a metadata provider:
Where `oafed-certificate.pem` is the x509 certificate from our metadata, saved in the same folder as your `shibboleth2.xml` file.
### **OA fed metadata x509 certificate**
-----BEGIN CERTIFICATE-----
MIIDKTCCAhECFGlXdwTZbTqmWpnDe/SVSc84LjdRMA0GCSqGSIb3DQEBCwUAMFEx
CzAJBgNVBAYTAkdCMQ0wCwYDVQQKDARKSVNDMRMwEQYDVQQLDApPcGVuQXRoZW5z
MR4wHAYDVQQDDBVPcGVuQXRoZW5zIEZlZGVyYXRpb24wHhcNMjIwMTA3MTE1NTQ3
WhcNMzIwMTA1MTE1NTQ3WjBRMQswCQYDVQQGEwJHQjENMAsGA1UECgwESklTQzET
MBEGA1UECwwKT3BlbkF0aGVuczEeMBwGA1UEAwwVT3BlbkF0aGVucyBGZWRlcmF0
aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5HdGbZWikuncyVrn
Soiqhbw7jIiI62DYz9sCndRrydlnwOB3jeNO6176dAVrd8cw25SbO+NFH3PZwELK
SzfzqcTYHHyDdvWQ2zN/+w04UanxoDCCdWeQqA+Oo2yTSoZmYoIOiQ+bWUQb0DSC
dNpHyesS4DUdZonDTnPMjAm1Ulh5n5ek78GTeY/BfCWY5SM+m9AQuTU5AePDnaEv
4QNLkdplSMO3nYYTxmfTCK578MUaoCxEWYPAv0j4VsvVBeApOTJ+ICYv9AZbsHlW
uMYQwbzHn5RlnSYtESkgrHN1vR1WAqtgOIKjrLYS+hhYmaAwQ2yBSvob4UgZOok0
967e3wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBENtVCTUIox/nNOfcbmVz7XBrG
5JRe2uQqfRqljNXviYrTYSvUks+KjeaXOGgetpb2aUR3VtemXtwwisRHaFH6D2H5
OdZseMt3HQ32xwpqrEYDArBRmTrIevG31DzPq06HHC6VIBKQ5oT3+GH7FvavLiCt
jfggHYoX5YY8VGHqiGM/72+Ru0nOBz3iKWbuFBmnN/iWyC/7BSC8lEN85+stSIYS
FaQOqOpS+zcx45ytBpCyEqEYQNVBXV8HO0HrV4rL4+eEV4ttHAEuYLZRzsN+WVhX
4ezOWZhjU36DFJBPHJoUvKj/5pEXlFVbzZc2VXU8RRrZVvFa1Dy2Ht/IUbX7
-----END CERTIFICATE-----
### SimpleSAMLphp
You will need a signing certificate. Create one in the `cert` directory:
cd cert
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
Refer to it in your `authsources.php` file:
'default-sp' => array(
'saml:SP',
'privatekey' => 'saml.pem',
'certificate' => 'saml.crt',
),
Enable the metadata and cron modules:
touch modules/metarefresh/enable
cp modules/metarefresh/config-templates/*.php config/
touch modules/cron/enable
cp modules/cron/config-templates/*.php config/
Create a directory to cache the metadata:
mkdir metadata/openathens
chmod go+rw metadata/openathens
Edit `config/metadatarefresh.php`:
array(
'uk' => array(
'cron' => array('hourly'),
'sources' => array(
array(
'src' => 'https://fed.openathens.net/oafed/metadata',
'validateFingerprint' => '49:EC:EB:FE:CA:2F:F8:A7:74:48:2D:EB:81:9A:5A:0A:B4:02:ED:91',
),
),
'expireAfter' => 60*60*24*1, // Maximum 1 days cache time.
'outputDir' => 'metadata/openathens/',
'outputFormat' => 'serialize',
),
),
);
Finally set the cache to be a metadata source in `config.php`:
'metadata.sources' => array(
array('type' => 'flatfile'),
array('type' => 'serialize', 'directory' => 'metadata/openathens'),
),
You will also need to upload your SP metadata in the service provider dashboard when you register your app. Get it from the federation tab on the simpleSAMLphp front page. If you encounter metadata loading issues you may need to increase the memory_limit and max_execution_time in your php configuration file.
---
language: "en"
---
# How to interact with OpenAthens IdPs
If you are in other federations, then the best way to think about IdPs in the OpenAthens Federation is... just like any other IdP in any of those other SAML federations. They will interact with you in the same way and as long as you are complying with the standards you should not need to make any changes to your implementation to support them or join our federation. You should not need to do anything special specifically for them.
There are some small differences that you may find it useful to be aware of, but nothing that will change the basic tenet and all are beneficial to you:
* All OpenAthens IdPs:
* use the same software in the same, standards compliant, way thanks to the shared platform.
* support SAML 2 and encryption.
* can easily release role and entitlement attributes if that is useful to your service (e.g. where staff and student would have access to different content, or a subscription had to be limited to a department).
* See: [Standard attributes in the OpenAthens Federation](/providers/standard-attributes-in-the-openathens-federation.md)
* can release non-standard attributes where appropriate.
* See: [Extended attributes in the OpenAthens Federation](/providers/extended-attributes-in-the-openathens-federation.md)
The IdPs can have several ways of signing into OpenAthens such as LDAP, ADFS or OpenAthens accounts (some even use a combination) but none of that affects the interaction between their SAML IdP (us) and the SAML SP (you).
Like any IdPs they will be keen to use WAYFLess URLs with your service and (where possible) also use article level links. OpenAthens Federation enhances those two capabilities where present by providing a way to use them behind a consistent link format that simplifies setup and works with link resolvers without the need to resort to proxy servers.
## See also:
* [Access URLs](https://docs.openathens.net/providers/access-urls.md)
* [Best practices](https://docs.openathens.net/providers/best-practices.md)
* [WAYFless access and deep linking in the OpenAthens Federation](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-the-openathens.md)
---
language: "en"
---
# How to join other federations
OpenAthens Keystone will make the configuration of SAML and the OpenAthens Federation easy, but you will still need to become part of any other access management federation where you want to interact with your customers - e.g. universities and colleges who are only in their own national federations.
Since all the other federations are national research and education network (NREN) based, a good first step is to join one that is part of eduGAIN as this can help with many of the technical aspects.
## eduGAIN
eduGAIN is a collaboration between many of the national research and education federations to share metadata which means that you only have to join one of their member federations to appear in the others. Member federations can pick and choose, and some are more inclusive than others so it's not guaranteed you'd appear in all of them. The member agreements of each federation are far from universal though, so whilst the technical aspect of joining a federation is easier, you will often still need to become a member of the federation(s) your customers are in - e.g. for all parties to be bound by the same trust framework - even if they are not the "registration authority".
These sources will tell you more:
* [eduGAIN website](https://edugain.org/)
* [GÉANT: How to join eduGAIN as a service provider](https://wiki.geant.org/display/eduGAIN/How+to+Join+eduGAIN+as+Service+Provider)
They recommend joining the federation in your home country as that will make communication during the joining process much easier.
A useful way of seeing which federations have you (or your customers) in their metadata is to use the [REFEDS metadata explorer](https://met.refeds.org/).
## Methods
The exact method of joining a federation can vary, but those variables are generally about how you apply and what information they want - e.g. some will want a formal letter on headed paper, some may want proof that you own the internet domain in your entityID, most will perform some form of procedure to confirm you are who you say you are and some will just not tell you how to register entities until you are a signed up member. This page covers the technical information you would need to supply them to register your entity, and translates some of the terminology they are likely to use.
### Terminology
| **Term** | **Means** | **Notes** |
|----------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Entity | The SAML service provider | |
| EntityID | An identifier for the entity that is unique within a federation | Read this from the connection record in the Service Provider dashboard. |
| Display name | What you want your service to appear as in their metadata | The published metadata uses the connection name you have set in the Service Provider dashboard. While you will usually want this to match, it doesn't have to. |
| Metadata | An XML document that describes the entity | May not be necessary if you and they are both in eduGAIN |
| Metadata address, Automatically generated metadata | Where we have published your SAML metadata | See next table |
| Federation metadata | An aggregated set of all the entities' metadata in a federation | Once you have registered your entity in a federation, you would appear in that federations metadata. If that federation is part of eduGAIN the data can then propagate to other member federations - depending on how often they update their metadata this could take several days. |
### If / when they ask for...
| **If they ask for...** | **Say...** | **Notes** |
|------------------------------------|----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Metadata address or file | | The address where your metadata can be accessed. The metadata they're asking for can be copied from the admin site ("SAML Connector" under **Keystone settings \> Keystone connections \> choose a connection** ). There should not be a *requirement* for it to be linkable but they often prefer it. Get the link or download it from the "SAML Connector" details. Choose the version with inline or hosted logos as per their requirements. If you've already joined an eduGAIN federation and appear in that aggregate, you can tell them that instead. You can check via the refeds link mentioned earlier. |
| Software | OpenAthens Keystone | If you want you can describe it as generic SAML, but the endpoints will give it away. |
| Requested attributes | `urn:oid:1.3.6.1.4.1.5923.1.1.1.9` and `urn:oid:1.3.6.1.4.1.5923.1.1.1.10` | These are the targetedID and scoped affiliation values discussed elsewhere which between them will usually be able to tell you everything you need for authorization. This is probably all that you need to tell them, but depending on your application you may want to specify more. |
| SAML versions supported | `SAML 2` | |
| Certificate thumbprint | Read from your connection record in the Service Provider dashboard | If they ask for this it is to confirm that the certificate in the metadata you sent them is correct. Hit the dots next to the certificate to view it. |
| Encryption or Signing certificates | Copy from your connection record in the Service Provider dashboard | They are more likely to ask for the fingerprint (above), but if they want this in a separate email from your metadata, view your metadata in the connection details (as above) and copy the x509 certificate from there. Top / tail it with begin and end tags as below: -----BEGIN CERTIFICATE----- qd87h5o8a7a475... the certificate data, etc -----END CERTIFICATE----- |
See also:
* [Keystone connections](https://docs.openathens.net/providers/keystone-connections.md)
---
language: "en"
---
# How to suggest improvements or new features
We are always on the lookout for ways to make our products better for our customers and if you want to let us know any ways in which existing functions can be better, or about new features and functions you would like to see, we'd love to hear them. The best way to do that is to add them to the [OpenAthens Ideas Portal](https://openathens.ideas.aha.io/).
Sign in with your email address to share your thoughts or vote for the ideas you think are worthwhile. Please use your work email so we know you're real.
To help us make the best use of your ideas, what we need to know is:
## For enhancements or changes to existing features
* Which feature could be better
* How you think it could be better
* The problem that an improvement would solve
E.g: I think the bulk upload function would benefit from being able to upload different account types because we regularly have to create dozens of new Access accounts for temporary, onsite users.
## For new features or functions
* What new thing you would like the product to be able to do
* Why you would like it to be able to do that
* The situation or problem it would solve and who would benefit
E.g. I would like to be able to select accounts from a search results and edit the same field (whole and partial) for all selected accounts via the interface so that I don't need to download and re-upload files because that is a complicated process.
## What happens to enhancement and feature requests
Before they are visible to all, a moderator will check it's understandable and relevant. It will usually then be open for all to view, comment and vote on.
Our team of UX designers and product managers periodically review the suggestions and assesses things. They may post questions or get in touch more directly to find out more to make sure the problem to be solved is fully understood.
### Do they all get accepted into the backlog?
Some ideas will not be possible to take forward and when that happens they will be identified in the portal and a reason given. The more you can say about the problem that needs solving though, the better we can consider other potential solutions that may help.
It is the underlying problem that we aim to address and many factors are considered. This means that action taken may not exactly match your suggested solution but could address several seemingly unrelated items instead.
### Are some more likely to get done than others?
The things that go to the top of the list are the ones with the clearest benefits, which often means the best description(s) of the problem. Popularity ensures we look deeper into things where the benefit may not be so obvious to us
## Data protection bit
By posting in the OpenAthens Ideas Portal, you consent to Jisc collecting your name and email in order to contact you for further feedback to help improve our products and services.
Your ideas and comments will be publicly visible in the portal with your name anonymised.
This portal is provided by Aha! and may be processed in the US. Your contact details will be processed by Jisc in the UK.
You can unsubscribe at any time. You can also revoke consent from the checkbox in your user profile on the ideas portal.
* [OpenAthens privacy policy](https://www.openathens.net/privacy/)
* [Aha! privacy polic](https://www.aha.io/legal/privacy_policy)y
---
language: "en"
---
# Integrate OpenAthens Keystone
Our service desk will be happy to help at any stage.
## Preparation
* Make sure you can access the service provider dashboard at [sp.openathens.net](https://sp.openathens.net/).
* Create a test account at [admin.openathens.net](https://admin.openathens.net/) (same credentials as the service provider dashboard)
* See [OpenAthens test accounts](https://docs.openathens.net/providers/openathens-test-accounts.md) for more advanced test account options
## Install an OpenID Connect plug-in or framework
1. If you do not already have an OIDC plug-in or framework installed, find one for your platform that has agreeable documentation and install it. This must support "OpenID Connect" specifically, rather just OpenID (which is older and will not work with OpenAthens).
2. Configure your site to use the plug-in or framework and add the option to your login page alongside any other login methods you have. For help with that you will need to consult the documentation of your chosen plug-in and platform. See also: [OpenID Connect examples](https://docs.openathens.net/providers/openid-connect-examples.md)
## Configure the basic application in the OpenAthens service provider dashboard
1. Access the service provider dashboard at [https://sp.openathens.net](https://sp.openathens.net/)
2. Go to **Applications**
3. [Add a new application](https://docs.openathens.net/providers/add-an-application.md), choosing **OpenID Connect relying party** from the options
4. Fill in the form
1. All the fields on the first page can be changed later if necessary, but must be valid to proceed.
2. Select a **new connection** unless you are migrating from one OIDC app to another
5. Click the **Create application** button
6. This will create the record and display the details you need to configure your OIDC plugin
For a more detailed view of these steps, see: [Adding a new OIDC application to the publisher dashboard step by step](https://docs.openathens.net/providers/adding-a-new-oidc-application-to-the-service-provider-dashboard-step-by-step.md)
## Configure your OpenID Connect plugin or framework for OpenAthens
1. Access the configuration of your plugin or framework and update the settings to connect to OpenAthens.
2. (a) and (b) below are always needed. Some or all all of the others *may* need to be specified. There can also be some small variation in terms:
1. Client ID \& Client secret or key - copy both from the dashboard (**Applications \> choose an application \> Configuration tab**)
2. Provider URI - `https://connect.openathens.net`
3. Login or Authorization endpoint - `https://connect.openathens.net/oidc/auth`
4. Token (validation) endpoint - `https://connect.openathens.net/oidc/token`
5. User Info endpoint - `https://connect.openathens.net/oidc/userinfo`
6. JWKS / Key URI - `https://connect.openathens.net/oidc/jwks`
7. Identity key / claim / attribute - this should usually be set as 'sub' (as in subject)
3. Your plug-in or framework will probably support automatic configuration in the background, but if you need to specify the address manually (or check any of the content) it is [https://connect.openathens.net/**.**well-known/openid-configuration](https://connect.openathens.net/.well-known/openid-configuration) (the dot before well-known is necessary).
## Test
You're not finished, but at this point you can start the "works at all" tests as invoking your OIDC login will send you to your own OpenAthens login point where you can sign in with a test account. If it's working you should receive a few claims.
The most likely problem to come up at this stage is an invalid redirect URL error, fixed by updating the return URL in the service provider dashboard to match the address of the error, less any parameters (**Applications \> choose an application \> Configuration tab**).
## Next
Once you have it working in this basic way, it's time to look at the integration with your existing authorization flow and how to deal with the data that your customers in the federation will be sending. This is covered in the [continued integration of Keystone](https://docs.openathens.net/providers/continued-integration-of-keystone.md) page.
---
language: "en"
---
# Integrating OpenAthens Keystone with Amazon Cognito
## Create the OpenAthens application record
First set up a basic application record in the OpenAthens Service Provider Dashboard as per [Quickstart for OpenAthens Keystone](https://docs.openathens.net/providers/quickstart-for-openathens-keystone.md). You'll need to enter a placeholder for the redirect URI to get it set up - you'll update that later with value from Amazon Cognito.
Hop into the connection that was created and turn on the rule called **Shortened OIDC subject (52 characters)** and save.
Return to the application configuration tab as you'll need the client ID and client secret in the next step.
## In the Amazon Cognito dashboard
### Step 1: Set up your application
1. User pools \> Create user pool
2. Select the Application type (we'll go with Traditional web application for the purposes of these instructions)
3. Provide a name (this will be for internal use only)
4. Select options for "Options for sign-in identifiers" (we'll select Email)
5. "Return URL" should be set to your Relaying Party default URL
6. Create user directory
7. From Amazon Cognito \> User pools \> User pool ({your user pool ID})
copy the last section of the ARN value from beneath the "User pool information" section and substitute the value into the Redirect URL placeholder in the Keystone configuration, modified slightly as follows:
ARN:
arn:aws:cognito-idp:++**eu-north-1**++ :286652833501:userpool/++**eu-north-1_R4APU6vRe**++
Redirect URI placeholder:
https://{afterSlashLowerCaseWithoutTheUnderscore}.auth.{region}.amazoncognito.com/oauth2/idpresponse
Example Redirect URI:
https://++**eu-north-1r4apu6vre**++ .auth.**eu-north-1**.amazoncognito.com/oauth2/idpresponse
8. Update the placeholder redirect URI application record in Keystone with the Redirect URI above and save it. Don't forget to remove the underscore and make it lower case.
### Step 2: Setup resources for your application (App client)
1. From the Overview page, in the left-hand menu select **App clients** beneath Applications.
2. Click on the App client name you entered in the previous step and copy the Client ID and Client secret from the "App client information" section - you'll need to update your OpenID Connect client with these values. You'll also need to add the issuerUri to your OpenID Connect client. This value can be obtained from the example code provided beneath the "Quick setup guide" section for your App client.
### Step 3: Add custom attributes to the User pool
1. Add the following custom attributes beneath Authentication \> Sign-up \> Add custom attributes:
Name: targetedID
Type: String
not Mutable
Name: scopedAffiliation
Type: String
not Mutable
Amazon Cognito automatically prepends the word "custom" to all custom attribute names. We'll need to map these custom attributes to OpenID Connect attributes after we set up the Identity Provider.
### Step 4: Create the Identity Provider
1. **Authentication Social and external providers \> Add identity provider \> OpenID Connect (OIDC)**
2. Provide a name (The name which will be displayed to users when the login method is enabled)
3. The Client ID \& Client Secret from the OpenAthens Keystone record
4. Leave **Authorized scopes** as: openid
5. Leave **attribute request method** as: GET
6. Select **Manual input** for **Retrieve OIDC endpoints** and populate the endpoints obtained from:
7. Ensure the following mapping are set:
custom:targetedID -\> urn:oid:1.3.6.1.4.1.5923.1.1.1.10
custom:scopedAffiliation -\> urn:oid:1.3.6.1.4.1.5923.1.1.1.9
(The mapping for "sub -\> username" won't be visible here but that mapping will be added automatically once the Identity Provider has been added. This is a default unique user identifier within each user pool).
### Step 5: Add the Identity Provider to the App client
1. **App clients \> {App client name}**
2. "Login pages" tab \> Edit
3. Beneath "Identity providers" click the drop-down and select the name of the App client you added in Step 4
4. Save changes.
The Amazon Cognito integration should now be complete and ready for testing.
---
language: "en"
---
# Integrating OpenAthens Keystone with Auth0
## Set up an application in OpenAthens
1. Create an application in the OpenAthens Service Provider dashboard. See:
1. [Quickstart for OpenAthens Keystone](https://docs.openathens.net/providers/quickstart-for-openathens-keystone.md)
2. [Add an application](https://docs.openathens.net/providers/add-an-application.md)
2. In the **Redirect URL** field, enter a placeholder URL for now. You will update this field later, after configuring Auth0. Fill in the other fields as required.
3. Save the application.
4. Go to **Keystone settings \> Keystone connections** and select the [connection](https://docs.openathens.net/libraries/connections.md) for your new application.
5. In the **Rules** section of your connection details, turn on **Shortened OIDC subject (52 characters)** . (You might need to click **Show all** to see this rule.)
6. Save your changes.
## Configure Auth0
Log in to your Auth0 dashboard and configure the required settings, as described in the [Auth0 documentation](https://auth0.com/docs).
You can find the ClientID and Client Secret in the OpenAthens Service Provider dashboard (**Applications \> \[select your application\] \> Configuration tab**).
## Update the redirect URL
Back in the Service Provider dashboard, update the **Redirect URL** of your application with the correct URL from Auth0.
You can now test authentication.
---
language: "en"
---
# Integrating OpenAthens Keystone with Okta
## Create the OpenAthens application record
First, set up a basic application record in the OpenAthens service provider dashboard as per [Quickstart for OpenAthens Keystone](https://docs.openathens.net/providers/quickstart-for-openathens-keystone.md). You'll need to enter a placeholder for the redirect URI to get it set up - you'll update that later with a value Okta will generate.
Hop into the connection that was created. Turn on the rule called *Common EduPerson* and save.
Return to the application configuration tab as you'll need the client ID and client Secret in the next step.
## Within the Okta dashboard
### Step 1: Create an Identity Provider
1. **Security \> Identity Providers \> Add identity provider \> OpenID Connect IdP**
2. The name which will be displayed to users when the login method is enabled
3. The Client ID \& Client Secret from the OpenAthens Keystone record
4. Endpoints obtained from: including the Userinfo endpoint
5. Turn on **Enable automatic linking**
6. Enable **Update attributes for existing users**
7. Once the Identity Providers is created, view the newly created Identity Provider and copy the redirect URI from the Summary section
8. Update the placeholder redirect URI application record in Keystone with the Redirect URI from the Summary section
### Step 2: Create mappings for the Identity Provider
1. **Identity Providers \> select your newly created identity provider \> Actions \> Edit Profile and Mappings**
2. Add the following string attributes:
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9
Variable name: eduPersonScopedAffiliation
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10
Variable name: eduPersonTargetedID
### Step 3: Set up routing rules
1. **Identity Providers \> Routing rules**
2. **Add Routing Rule**
3. Give the rule a name
4. Ensure the "THEN" section includes your newly created identity provider and click **Create rule** . If asked to activate the rule, select to **Activate**.
### Step 4. Create an application
1. **Applications \> Applications \> Create App Integration**
2. For Sign-in method choose **OIDC -- OpenID Connect**
3. For Application type choose **Web Application**
4. Sign-in redirect URIs should be your Relaying Party default redirect URI
5. Ensure **Allow everyone in your organization to access** is selected
6. Take note of the ClientID and Client Secret as this will need to be added to your OpenID Connect Client configuration.
### Step 5. Complete the mappings
#### User (default)
1. **Profile Editor \> Select User (default) profile**
2. Add the following string attributes:
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9
Variable name: eduPersonScopedAffiliation
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10
Variable name: eduPersonTargetedID
#### Application
1. **Profile Editor \> Select the relevant "Application" profile**
2. Add the following string attributes:
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9
Variable name: eduPersonScopedAffiliation
Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10
Variable name: eduPersonTargetedID
3. **Profile Editor \> Select the relevant "Application" profile \> Mappings**
4. Ensure the following mappings are set for Okta User to {your Application name} (ensuring the mapping arrows are green):
user.eduPersonTargetedID -\> eduPersonTargetedID
user.eduPersonScopedAffiliation -\> eduPersonScopedAffiliation
#### Identity Provider
1. **Profile Editor \> Select "Mappings" for the Identity Provider**
2. Ensure the following mappings are mapped for {your Identity provider name} to Okta User:
String.append(appuser.eduPersonTargetedID, "@null.com") -\> login
String.append(appuser.eduPersonTargetedID, "@null.com") -\> firstName (this is just an example mapping, we're recycling the email mapping below for convenience)
String.append(appuser.eduPersonTargetedID, "@null.com") -\> lastName (this is just an example mapping, we're recycling the email mapping below for convenience)
String.append(appuser.eduPersonTargetedID, "@null.com") -\> email (this is because Okta requires an email attribute and OpenAthens Identity Providers do not release an email address attribute as standard. This should be mapped to the relevant email address attribute where available)
appuser.eduPersonTargetedID -\> eduPersonTargetedID
appuser.eduPersonScopedAffiliation -\> eduPersonScopedAffiliation
### Step 6. Update the IdP username for the Identity Provider created in step 1
1. **Identity Providers \> select your created identity provider \> Actions \> Configure Identity Provider**
2. Edit the General settings and ensure IdP username is set to: idpuser.eduPersonTargetedID
The Okta integration should now be complete and ready for testing.
---
language: "en"
---
# Integrating the SeamlessAccess button
SeamlessAccess is a service designed to provide a simple and more streamlined experience for end users when accessing online resources. This page provides information on integrating the button element of the SeamlessAccess service with OpenAthens Keystone and Wayfinder.
For more information about the SeamlessAccess service see:
* Mission statement -
* SeamlessAccess technical documentation -
* SeamlessAccess button code -
## Enabling integration of the SeamlessAccess button
These instructions are for the standard version of their button. An advanced version that may offer you more options is available but it is significantly more complicated.
1. Add the SeamlessAccess button code to your website per their instructions (see link above)
2. Modify the login button code to replace the loginInitiatorURL with your deep linking syntax, or if your site cannot support deep linking, your wayfless URL - see: [WAYFless access and deep linking in OpenAthens Keystone](https://docs.openathens.net/providers/wayfless-access-and-deep-linking-in-openathens-key.md) if you do not already have these set up. This is the URL that will be followed when the button is clicked.
XML
3. The button will provide the entityID as a parameter called `entityID`, but it must be passed to us as a parameter called `entity`. You will need to handle this in your code.
4. Activate SeamlessAccess integration in your application's [discovery tab](https://docs.openathens.net/providers/edit-an-application.md#Discovery) (first select Wayfinder)
The people at SeamlessAccess provide a testing page that may help:
## Anything to watch out for?
You should ensure that data from the button is only used when the button is clicked, so that users following a WAYFless link do not have that entityID overwritten (users can have multiple affiliations).
The button will never be aware of 1:1 connections you have set up via Keystone, only customers in federations. This may affect your decision to use it, as may the impact of browsers disabling 3rd party cookies and storage.
## Troubleshooting
### The button is not displayed correctly
Your content security policy may be affecting it - see:
### Deep linking is not working with the SeamlessAccess button
E.g. the user ends up on a different page than expected. Check that the target parameter is not being changed or renamed.
### IdP entity not found error message when accessing with a remembered IdP
OpenAthens is receiving an entityID that we do not recognize. Either:
* The IdP in question is not a member of any SAML federation that your application is registered in
* Check you are sending the entity parameter as `entity`, not `entityID`
---
language: "en"
---
# Javascript editor test inputs
A selection of test inputs to use with the Javascript editor.
There is information at the bottom of the page about changing the attribute names and values to suit your exact testing needs.
## Default test rule
This one is included in a blank Javascript rule when it is created and features a wide selection of attributes as examples, some of which have different federation namespaces (deprecated old attributes from the old Athens service in this case) and some you would not expect to see in general use. In the order they appear in the example, they are:
| **SAML attribute** | **Example value(s)** | **Notes** |
|----------------------------------------------------------------------------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.9` | `member@idp.example.org.uk` `staff@idp.example.org.uk` | Released by default. A multi-valued attribute containing both the role and federation scope of a user. The federation scope is the organization identifier that should be used in a SAML federation. |
| `urn:mace:example.org.uk:athens:attribute-def:federation:1.0:identifier` | `urn:mace:example.org.uk:athens:federation:uk` | Deprecated - do not use on a live service |
| `urn:mace:example.org.uk:athens:attribute-def:person:1.0:username` | `example.username` | Deprecated - do not use on a live service |
| `urn:mace:example.org.uk:athens:attribute-def:organisation:1.0:identifier` | `12345678` | Deprecated - do not use on a live service |
| `forenames` | `John` | Not released by default |
| `surname` | `Doe` | Not released by default |
| `http://example.org.uk/federation/attributes/1.0/organisationid` | `idp.example.org` | Deprecated - do not use on a live service |
| `organisationNum` | `12345678` | Deprecated - do not use on a live service |
| `username` | `aa` | Not released by default |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.7` | `https://auth.example.com/terms-and-conditions` | Released by default (if configured by an IdP for a service provider) The "entitlement" attribute. Could say anything. Used for greater granularity - e.g. identifying medical students at a regular university. |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.10` | `egFw5UJnXPMFObZHwjHayLib7` | Released by default. This one is the "targetedID" and is a persistent and opaque user ID |
### **Standard test rule**
XML
https://idp.example.org.uk
https://idp.example.org.uk
rGiG4OHayheCmsayLib7gegFw5UJnXPMFObZHwjHu5UVynHI4LwfzqF1l6WBRawb5Iifn7DMTzRbzoGI
https://auth.example.com/
urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
member@idp.example.org.uk
staff@idp.example.org.uk
urn:mace:example.org.uk:athens:federation:uk
example.username
1234567
John
Doe
idp.example.org.uk
1234567
jd@idp.example.org.uk
https://auth.example.com/terms-and-conditions
egFw5UJnXPMFObZHwjHayLib7
## Basic federation attributes with multi-valued role
This one features just the bare minimum you are likely to get from a typical federation IdP in any federation around the world.
| **SAML attribute** | **Example value(s)** | **Notes** |
|-------------------------------------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.9` | `member@idp.example.org.uk` `staff@idp.example.org.uk` | Released by default. A multi-valued attribute containing both the role and federation scope of a user. The federation scope is the organization identifier that should be used in a SAML federation. |
| `urn:oid:1.3.6.1.4.1.5923.1.1.1.10` | `egFw5UJnXPMFObZHwjHayLib7` | Released by default. This one is the "targetedID" and is a persistent and opaque user ID |
### **Example SAML statement with minimum attributes**
XML
https://idp.example.org.uk
https://idp.example.org.uk
rGiG4OHayheCmsayLib7gegFw5UJnXPMFObZHwjHu5UVynHI4LwfzqF1l6WBRawb5Iifn7DMTzRbzoGI
https://auth.example.com/
urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
member@idp.example.org.uk
staff@idp.example.org.uk
egFw5UJnXPMFObZHwjHayLib7
## How to edit an attribute statement for testing
Without having to understand SAML, here is what you need to know to edit the attribute names and values to suit your own tests.
1. Do not mess with anything outside of the attribute statement - the tester will reject invalid SAML. The attribute statement is within these two tags:
...
2. Each attribute will look something like this -
member@idp.example.org.uk
staff@idp.example.org.uk
You can ignore the NameFormat part for these. It is important, but for... other things; it does not matter for this as long as it is there (to keep the SAML valid). The important parts are the Attribute Name and value. As you can see the attribute name is in quotes, and attribute values are each tagged within the attribute. You must have at least one value and all but the user identifier can have multiple values.
You can either remove the unused attributes from your test input, or leave them in to check how your script handles additional input.
When a scripted rule is executed by the service there are various safeguards in place to protect the service. The ones you need to know about are:
* Execution time is capped and if this is reached the evaluation instance is dropped and the end user gets an error message.
* Any error during runtime drops the evaluation instance and the end user gets an error message
---
language: "en"
---
# Joining the OpenAthens Federation
## Business side
If you're not already in contact with us, [learn about joining the OpenAthens Federation](https://openathens.org/publishers/federation/) on our business website. Our friendly team will talk you through the options, what to expect and all the other bits and pieces to get you signed up and ready to have your tech people come here to these docs.
## Technical side
Once the business details are finished, you can register your application in the federation. What you ultimately do will depend on whether you are using our software or have an existing SAML service provider (SP) such as Shibboleth, but there are some common areas.
You should familiarize yourself with the:
1. [technical recommendations](https://docs.openathens.net/providers/technical-recommendations.md)
2. [best practices](https://docs.openathens.net/providers/best-practices.md)
3. [user authorization options](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
4. [test process](https://docs.openathens.net/providers/getting-an-application-production-ready.md)
If you're using OpenAthens software such as Keystone, federation things will be sorted out as part of that setup so the rest of this page will concentrate on the process for bringing an existing SAML SP such as Shibboleth (that might already be in other federations) to OpenAthens.
* How to [Integrate OpenAthens Keystone](https://docs.openathens.net/providers/integrate-openathens-keystone.md)
### Bringing your own SP to the OpenAthens Federation
Any software that is configured to support the [SAML V2.0 deployment profile for federation interoperability](https://kantarainitiative.github.io/SAMLprofiles/saml2int.html) should have no difficulty working within the OpenAthens Federation. That means things like Shibboleth and SimpleSAML are fine.
Assuming you've checked the technical recommendations and best practices linked above, the next step is to register your SP in the service provider dashboard:
#### Prepare:
* Make sure you have the credentials to access the service provider dashboard. These would have initially been provided to the business contact.
* You'll need the URL of your SP metadata or, if that's not public facing, a text file containing it.
#### Method:
1. Access the service provider dashboard at [sp.openathens.net](https://sp.openathens.net/).
2. Go to **Applications** and click **Create new application** . (See [Add an application](https://docs.openathens.net/providers/add-an-application.md).)
3. In the dialog box, choose **Existing SAML application**.
4. Upload your application's metadata either by specifying the URL or uploading the file. Any type of text file is fine as long as it has valid XML inside it.
5. You will be shown the details of the certificate presented by the metadata. Confirm that the metadata is trusted and should be imported, tick the box and then click the create button.
The application record is now created.
The next technical step is to add the OpenAthens Federation metadata to your SP. You may need to check your software's documentation on that, but we've written up how to do it in Shibboleth and Simple SAML: [How to add the OpenAthens Federation to common SP software](https://docs.openathens.net/providers/how-to-add-the-openathens-federation-to-common-sp-software.md).
Once that is done you just need to cover off any marketing things to do with names, descriptions and logos and you're ready to submit it for publication. See: [Getting production ready with Keystone](https://docs.openathens.net/providers/getting-production-ready-with-keystone.md) or [Getting a SAML application production ready](https://docs.openathens.net/providers/getting-a-saml-application-production-ready.md).
When you submit it for publication our service desk will run some checks to make sure it's all working and will be a good experience for our mutual customers. As this can lead to them getting back to you with requirements or recommendations, it's best to plan in time and resource.
---
language: "en"
---
# Keystone connections
The **Keystone connections** page configures how OpenAthens products like Keystone work in multiple federations. External applications such as Shibboleth don't have a separate connection here because their appearance in other federations isn't managed by us.
When you select a connection you can make the following adjustments:
## Application
The name of the application record(s) using this connection.
## Rules (OpenAthens Keystone only)
Allows you to toggle [rule sets](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims.md) on and off. Changes take place immediately after saving.
* Common EduPerson and Extended EduPerson - translates the attribute names commonly used in educational federations to OpenID Connect claims. See: [eduPerson attributes](https://docs.openathens.net/providers/eduperson-attributes.md)
* The one with a long name extracts some useful identifiers from the main eduPerson attribute used in federations
## SAML connector
### 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 this once you are live.
The dots menu gives you access to view the **entity metadata** so you can download it or copy the published address to send to federations you are joining, or direct 1:1 connections.
**The entity metadata** has two options for logos. Inline (default) stores logo and banner as base64 encoded png images in the metadata, while hosted presents the banner as a URL and drops the logo. The reason for the choice is that some federations you might want to join insist on logos being 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 dots menu gives you access to view the certificate details.
### Privacy policies
Allows you to add and remove links to your privacy policy in the metadata. You can specify one link per language.
This is a recommended action by most federations at the moment, and it is very likely to become a requirement.
Linking to your privacy policy is already a requirement if you are asserting the [GÉANT Data Protection Code of Conduct](https://geant3plus.archive.geant.net/Pages/uri/V1.html) entity category.
### OpenAthens Federation
#### Allow sign-in for live OpenAthens identity providers
This will signal inclusion in the OpenAthens federation once the application is [set as live on the application page](https://docs.openathens.net/providers/edit-an-application.md#status) and approved. It will then be visible to all OpenAthens IdPs.
### Other federations
This section is about other federations you might be in or become a member of. Enable them here and their metadata will be added to your configuration, however that is all. The switch does not register you in that federation and you will still need to take steps to appear there. See: [How to join other federations](https://docs.openathens.net/providers/how-to-join-other-federations.md)
### 1:1 connections
This is for those SAML IdPs that you want to connect to who are not in a common federation (it is up to you to determine the weight of numbers that will make it easier for you to join any given federation than configure IdPs separately). See: [Entities that are not in a federation](https://docs.openathens.net/providers/entities-that-are-not-in-a-federation.md)
See also:
* [Enabling federations](https://docs.openathens.net/providers/enabling-federations.md)
* [How to join other federations](https://docs.openathens.net/providers/how-to-join-other-federations.md)
* [Getting production ready with Keystone](https://docs.openathens.net/providers/getting-production-ready-with-keystone.md)
### Entity categories
This section allows you to indicate in your metadata which entity categories you support. Once saved, you'll be able to see changes immediately in the metadata view under the menu by the entityID, but it will take up to six hours for them to appear in the published OpenAthens federation metadata. You will need to tell any other federations you are registered in about the change (education federations that include you via eduGAIN will pick up the change from the update to the federation you are registered in).
Most entity categories signify compliance with a set of rules or behaviors, so it's best to leave these turned off until everything else is in place.
---
language: "en"
---
# Launching to our mutual customers
We can offer to help with communications both to alert customers to the availability of a new publisher / resource and any information that might be needed to ease a transition (e.g. if we're moving customers off a proxied version).
This could include direct emails to mutual customers, news items, and inclusion in the library customer newsletter. You can also join our Listserv to keep up with the community discussion.
* [Newsletter](https://www.openathens.net/communications/)
* [Listserv](https://www.openathens.net/listserv/)
Our team is happy to help with proofreading, initial launch communications and onboarding of existing mutual customers.
## Example news items
1. [MIT Press News: The MIT Press joins the OpenAthens Federation](https://mitpress.mit.edu/the-mit-press-joins-the-openathens-federation/)
2. [Ground News: Ground News collaborates with OpenAthens to help students negotiate a complex media environment](https://ground.news/blog/openathens)
## Emails
When contacting your customers directly, some things to consider are:
* Rather than treating it as a special occasion, consider including the same preferred method for getting them set up at your end that you specified under IdP support in the Service Provider dashboard. (See: [Edit an application](https://docs.openathens.net/providers/edit-an-application#Editanapplication-IdPSupporttab(Allapplications)IdPSupport)) e.g:
* "... by accessing the SSO tab in your subscription manager", or
* "... by emailing your customerID, entityID and scope to support@..."
* Libraries in the OpenAthens federation would benefit from knowing the resource display name so they can easily find you in their catalog - e.g:
* "... find us in your catalog as J.Jonah Jameson Journals"
* Let them know which attributes you need them to send so they can set up their end - this should match what's in the Attributes tab in the Service Provider dashboard - e.g.:
* "Either *urn:oid:1.3.6.1.4.1.5923.1.1.1.10* or *urn:oasis:name:tc:SAML:attribute:pairwise-id*
And *urn:oid:1.3.6.1.4.1.5923.1.1.1.9"*
## Other federations
If you're using Keystone, don't forget that you can use it in multiple federations and for direct 1:1 connections from customers who aren't in a federation.
See:
* [Enabling federations](https://docs.openathens.net/providers/enabling-federations.md)
* [How to join other federations](https://docs.openathens.net/providers/how-to-join-other-federations.md)
* [Entities that are not in a federation](https://docs.openathens.net/providers/entities-that-are-not-in-a-federation.md)
### OpenAthens logos
If you want to use our logo on your website or any publications, see [OpenAthens logos](https://www.openathens.net/resource-hub/logos/).
---
language: "en"
---
# Manage access to the dashboard
To manage OpenAthens administrator accounts which can be used to access the service provider dashboard, click **Accounts**in the side menu.
## Access levels
The default level of access is to all applications, functions and connections, but you can [limit their access to individual applications and connections as required](https://docs.openathens.net/providers/manage-admin-access-to-an-application.md).
### View accounts
The standard view is a list of your administrator accounts. This list includes any accounts you have created via the service provider dashboard, and any you have created directly under your login in the OpenAthens admin interface ([https://admin.openathens.net](https://admin.openathens.net/)).
### Add an account
To add a new account, click the **Create new account** button and fill in the form. The assigned user will be sent an email with a link to set a password.
### Remove an account
You can delete an account either by opening the details and clicking the trash icon, or by selecting delete from the dots menu next to an account in the list.
Both display a confirmation dialog before non-recoverably deleting the account.
### Add or remove a role
You can choose one of two roles for accounts in the Service Provider dashboard: Service Provider Administrator and Service Provider Report Viewer. The latter is only able to access reports and is intended for the non-technical user to see transfers. Keystone customers can see all federations they are active in.
Click on the user's name or use the dots menu to edit details.
As well as roles for the Service Provider dashboard, you can also see but not edit roles for the account administration area.
### If you cannot sign in for any reason
Contact our [service desk](https://docs.openathens.net/providers/service-desk-and-support.md).
### Related
Related documentation for the user-admin interface for additional management options:
* [About Organisations and Sub-organisations](https://docs.openathens.net/libraries/about-organisations-and-sub-organisations.md)
* [Administrator roles](https://docs.openathens.net/libraries/administrator-roles.md)
* [Email templates](https://docs.openathens.net/libraries/email-templates.md)
---
language: "en"
---
# Manage admin access to an application
By default, anyone with an [administrator account](https://docs.openathens.net/providers/manage-access-to-the-dashboard.md) can manage all applications and/or connections in the service provider dashboard. If this is undesirable - for example, if you have outsourced development to a technical partner, or have multiple teams responsible for different applications - you can grant access to people that you specify.
Users with the [Owner role](https://docs.openathens.net/libraries/administrator-roles.md) have access to manage any application. This access cannot be removed. Users with other admin roles can be granted or denied access on an application-by-application basis.
Access restrictions on an application also apply to any [Keystone connection](https://docs.openathens.net/providers/keystone-connections.md) associated with that application.
There are two ways to manage admin access to an application:
## From the list
1. Go to **Applications**.
2. Beside the application you want to configure, open the **Options** menu.
3. Select **Manage admin access**. You are taken to a screen that shows current admin access permissions.
4. If **All users** is currently set to **Allow** , switch it to **Deny**. This allows you to set access for individual users.
5. Set access for each user to **Allow** or **Deny** as appropriate. (Users who have the [**Owner** role](https://docs.openathens.net/libraries/administrator-roles.md) are always set to **Allow** . Other users are set to **Deny** by default.)
6. Press **Save changes**.
## From the application details
1. From **Applications**, open the application whose access you want to change.
2. Press the **Restrict access**button.
3. Follow the previous procedure from step 4.
---
language: "en"
---
# Mapping SAML attributes to OIDC claims
As you would imagine, a mapping process exists so that you can specify incoming and outgoing attribute names. These mappings are defined under the rules menu, and need to be switched on or off on the [connection](https://docs.openathens.net/providers/keystone-connections.md) used by the [application](https://docs.openathens.net/providers/applications.md). Where a connection is used by multiple applications, the rules will apply to all the applications.
See also: [Standard attributes in the OpenAthens federation](https://docs.openathens.net/providers/standard-attributes-in-the-openathens-federation.md)
## Default rules
Out of the box there are some useful rules that we have predefined for you:
* `Affiliation and scope derived from eduPersonScopedAffiliation`
* This one separates out scope and role from the single SAML attribute that contains both
* Scope is the recommended organization identifier in SAML
* It is not turned on by default, but is often useful
* A user might have several roles, but they will all have a common scope
* `All Attributes`
* Set on by default for new connections
* Maps all SAML attributes to claims with the same target name (e.g. urn:oid:1.3.6.1.4.1.5923.1.1.1.9 - see: [eduPerson attributes](https://docs.openathens.net/providers/eduperson-attributes.md))
* Multi-valued attributes are sent as arrays (unordered)
* `Common EduPerson`
* Set on by default for new connections
* This one maps the four most commonly used SAML attributes to friendly claim names (targetedID, pairwiseID, scopedAffiliation and entitlement)
* `Extended EduPerson`
* This one maps all the less common SAML attributes and will usually not be necessary
* `Normalized targetedID`
* This one adds together the IdP entityID, SP entityID to the end-user's targetedID and normalizes it.
* It should only be needed if you are migrating from Shibboleth and were using the longform version of targetedID so that you can maintain user IDs
* (Longform example: `https://idp.example.org/openathens!https://sp.example.org/oa/metadata!84e411ea-7daa-4a57-bbf6-b5cc52981b73)`
* `Shortened OIDC subject (52 characters)`
* Some OIDC relying parties have a limit on the length of the sub field, for example AWS Cognito. This rule creates a 52 character identifier which will be consistent for that user for you.
The rule for legacy OpenAthens is not necessary for new services and is included only to help publishers migrate old services to federation identifiers.
Many eduPerson attributes can be multi-valued - for example a user might have roles of "student" as well as "member" - so you should expect to receive unordered arrays - e.g. `{ "claimName" : [ "value1", "value2"] }`
## Additional rules
There are a couple of rule types you can use to extend the mapping capability. The simple mapping rules can modify both the name and value using regular expressions - some examples:
| **Type** | **Incoming** | **Outgoing** | **Notes** |
|----------|-------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Name | `emailAddress` | `email` | changes the attribute name `emailAddress` to the claim name `email` |
| Value | `@(.*)` | `$1` | Removes all but the domain part of a scopedAffiliation value or email address |
| Name | `((?:.(?!\/))+$)` | `mynamespace$1` | Strips everything before the final slash in a name and replaces it with mynamespace - e.g. changes `couldbeanything/somethingelse/role` to `mynamespace/role` |
## To create or edit a rule set
Create and manage rule sets from **Keystone settings \> Attribute mapping rules**.
To add a new one, click the **Create new ruleset** button at the top of the page:
## To create or edit a rule
Once you have your rule set, you can populate it with rules.
You can either add a new mapping, or edit, clone or delete an existing one via the dots menu next to each rule.
To edit a rule:
This example uses a regular expression to extract the internet domain from an email address after changing the name to emailDomain.
If you do not add anything to the either box in the value line, the value is unchanged.
In the unlikely event that the simple rules cannot give you the mappings you need, there is a JavaScript editor available for more complex situations. See: [Mapping SAML attributes to OIDC claims with JavaScript](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims-with-javasc.md)
### Anything to watch out for?
If a rule doesn't appear to be applied, first check that it is turned on for the relevant connection and that connection has been saved.
---
language: "en"
---
# Mapping SAML attributes to OIDC claims with Javascript
When the simple mapping and transform rules do not meet your requirements you can add a Javascript rule. This is a significantly more advanced operation though and an understanding of both scripting and SAML is... advantageous.
## Writing a scripted rule
### Considerations before you start
1. Scripted rules are designed such that they can produce multiple OIDC claims, and you should not expect to need more than one per OpenAthens Keystone connection
2. Execution time is limited to one second. After this time the script is stopped and the login attempt will fail before the user is passed to you
3. Any exceptions generated by your script will stop execution and the login attempt will fail before the user is passed to you
4. Input attributes from SAML can be multi-valued and are unordered
### Global objects
At the point of execution the script has access to 3 global objects
* [response](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims-with-javasc.md#MappingSAMLattributestoOIDCclaimswithJavascript-ResponseObject) - encapsulates the SAML response from the IdP.
* [output](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims-with-javasc.md#MappingSAMLattributestoOIDCclaimswithJavascript-OutputObject) - javascript object used to store OIDC claims.
* [logger](https://docs.openathens.net/providers/mapping-saml-attributes-to-oidc-claims-with-javasc.md#MappingSAMLattributestoOIDCclaimswithJavascript-LoggerObject) - lets you write a limited number of debug statements.
#### **Scripted ruleset example**
JavaScript
/**
* parameter entitlements
* List of users entitlements
* parameter roles
* List of users roles
* return The membership type: gold, silver, bronze or tin.
*/
function getMembershipType(entitlements, roles) {
logger.log("Entitlements: %s", entitlements);
if (entitlements.includes("https://auth.example.com/terms-and-conditions")) {
var rolesNoSuffix = removeScope(roles);
logger.log("User has entitlement");
logger.log("Roles without suffix: %s", rolesNoSuffix);
if (rolesNoSuffix.includes("staff")) {
logger.log("User is staff");
return "gold";
} else if (rolesNoSuffix.includes("student")) {
logger.log("User is student");
return "silver";
} else if (role.includes("member")) {
rolesNoSuffix.log("User is member");
return "bronze";
}
}
return "tin";
}
/**
* parameter roles
* List of users roles
* return
* List of users roles with the scope (suffix) removed if present.
* E.g staff@idp.domain.com -> staff.
*/
function removeScope(roles) {
return roles.map((value) => {
var matches = value.match(/^(.*)@.*$/);
if (matches) {
return matches[1];
} else {
return value;
}
});
}
//Execution starts here.
var xp = '//saml:SubjectLocality/@Address[1]';
//Should return a single valued array.
var nodes = response.evalXPath(xp);
if (nodes) {
logger.log("Found %d address attributes", nodes.length);
//Assign userIp to the output. Will be released as an OIDC claim
output.userIp = nodes[0].textContent;
} else {
logger.log("Could not get users IP address");
}
var entitlements = response.getAttributeValues("urn:oid:1.3.6.1.4.1.5923.1.1.1.7");
var roles = response.getAttributeValues("urn:oid:1.3.6.1.4.1.5923.1.1.1.9");
//Assign membershipType to the output. Will be released as an OIDC claim
output.membershipType = getMembershipType(entitlements, roles);
## Response
### Public methods
`response.getIssuer();`
*Return Value:*
*
* a `String` identifying the issuer of the SAML response.
`response.getAttributeValues(name);`
*Parameters:*
*
* `name`the name of the SAML Attribute**.**
*Return value:*
*
* a `String[]` containing all values associated with the given name.
The array will be `empty` if there is no Attribute in the response with the give name, or there are no values contained within the Attribute.
`response.getFirstAttributeValue(name);`
*Parameters:*
*
* `name`the name of the SAML Attribute**.**
*Return value:*
*
* A `string` containing the first value associated with the given name (the order is indeterminate).
`null` will be returned if there is no Attribute with the given name, or there are no values contained within the Attribute.
`response.evalXPath(exp);`
The following `xml namespaces` are pre-registered
| **Prefix** | **Namespace** |
|------------|---------------------------------------|
| **samlp** | urn:oasis:names:tc:SAML:2.0:protocol |
| **saml** | urn:oasis:names:tc:SAML:2.0:assertion |
Therefore any elements within these namespaces can be access via the prefix. E.g `//samlp:StatusCode/@Value.`
If you require access to anything not defined in these namespaces you need to register them in the xpath expression. E.g `//*[local-name()='ElemName' and namespace-uri()='http://ext.namespace.com']/@AttrName`
*Parameters:*
*
* **exp**the xpath expression which will be evaluated over the SAML response (xml)
*Return value:*
*
* An `Element[]`. The array will be empty if nothing was found for the given xpath expression.
## Logger
The logger is provided to enable script debugging and is limited to the last 100 messages.
### Public methods
`logger.log(obj1 [, obj2, ..., objN]);`
*Parameters:*
*
* A list of java script object you wish to inspect.
`logger.log(msg [, subst1, ..., substN]);`
*Parameters:*
*
* JavaScript objects with which to replace substitution strings within `msg`.
E.g `logger.log("SAML Issuer: %s", issuerString);`
## Output
A standard javascript `Object` which you can assign any arbitrary property and associated value (`String` or `String[]`).
E.g If you wish to assert a OIDC claim indicating `membershipType` you would do the following
JavaScript
//Recommended method.
output.membershipType = 'gold';
//Or not recommended method
output['membershipType'] = 'silver';
[Next Page](https://docs.openathens.net/llms-full.txt/1)