Additional configuration possible in the publisher dashboard

This comes in two halves - the application, which configured how your OIDC implementation talks to OpenAthens, and then the connection, which is the part that controls how you appear in SAML federations such as OpenAthens, InCommon, SWITCHaai and UK Access Management federation (accounts from your own domain can be set to work whether or not you go live in any federations).

Application

After you select your application from the list there are three tabs:

1. Details
   
   
   1. The description and logo will appear for OpenAthens federation IdPs and in Wayfinder. This becomes mandatory when you want to go live in the OpenAthens federation
      
      
   2. The access URL will also become mandatory when you want to go live in the OpenAthens federation. During development it can be anything, but for the live service it would need to work. The usual thing to put here is a wayfless URL using the generic entityID and a suitable target page (the library customer can modify this locally)... which are terms that might not make sense to you yet - see Access URLs when you're ready.
      
      

      

      
      
      
2. Linking
   
   
   1. This is where you define the format used to link to specific pages in your application via the login process - e.g. so a library information page could have a link to a specific article on your site. See: Access URLs
      
      
3. Configuration
   
   
   1. The settings controlling how your OIDC instance communicates with us:
      
      
      1. Client ID and secret should be copied to your OIDC configuration. They are both unique to your application and are used for secure communication with us. These would also have been displayed when you initially registered your OIDC app in the publisher dashboard
         
         
      2. Application URL is the root address of your application - e.g. https://www.myapplication.com.
         
         
      3. Redirect URL is where we should return the user afterwards. If you are unsure, enter the same root address - the address you want will become apparent later when you test and receive an invalid redirect url error. 
         
         
      4. Login URL is the URL which will initiate a user login in your OIDC application - i.e. the address that the login button points to, sometimes called the OIDC handler. This is required for WAYFless access and deep link support. It is not usually the same as the access URL.
         
         
      5. Connection offers you a choice of existing connections to use with this application. If you are unsure, leave it as is.
         
         
      6. Entity categories allow you to restrict the entities that appear in supported discovery services such as Wayfinder. If set, only entities that have all matching categories in their metadata will appear, so it's best to leave this blank until you are certain that all your customers will have the matching entity categories (at the time of writing they will not).
         
         
4. Discovery
    
   1. This is where you define how Keystone will discover a user's home organisation when they do not arrive via a wayfless link - e.g. if they've found your content via Bing or Google
       
      1. Wayfinder - enables OpenAthens Wayfinder in hosted or embedded mode. You only need to add authorised domains if you are using the embedded version - see: Enabling OpenAthens Wayfinder
         
         
      2. Other central discovery service - specify a SAML DS compatible organisation discovery service
         
         
      3. Single identity provider - Keystone will direct all users to this identity provider, usually in the situation where you are adding Keystone to an internal service such as a VLE or LMS, but a useful starting point for all implementations.

Connection

1. From the Connections page, select your connection. It will have the same name as you originally gave your application, and is also accessible from the application's details.
   
   
2. After the list of applications using this connection are the mapping rules
   
   
   1. The standard mappings will usually be sufficient to translate the standard SAML attributes that the Identity Providers in the federation are sending to standard OpenID Connect Claims. You should not need the 'Standard OpenAthens' mapping.
      
      
   2. If they are not quite what you expect - for example email addresses are almost never sent by default - there are options to map and transform attribute names and values then apply them to a connection. See: Mapping SAML attributes to OIDC claims
      
      
3. Next are the OpenAthens specific settings
   
   
   1. Enable access for your own OpenAthens accounts (Allow sign-in for your domain)
      
      
   2. Join the OpenAthens federation (Allow sign in by any OpenAthens domain - you still have control over who can access your application).
      
      
4. Finally there are several other federations from around the world you can select.
   
   
   1. Selecting them only makes them available to your connection, it does not add you to their metadata and you will still need to join them if you have customers there.