docs/RELEASE_NOTES_NEXT/Administration/OpenAthens_SignOn.adoc

   1 Configuring sign-on to OpenAthens
   2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   3 If your institution uses OpenAthens single sign-on, you can configure Evergreen
   4 to link with OpenAthens. This will let patrons connect to OpenAthens resources
   5 seamlessly once they have logged in to Evergreen. Patrons are automatically
   6 assigned an OpenAthens identity dynamically based on their Evergreen login,
   7 and do not need accounts created manually in OpenAthens.
   8
   9 Registering your Evergreen installation with the OpenAthens service
  10 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  11 Using your OpenAthens administrator account at https://admin.openathens.net/,
  12 complete the following steps:
  13
  14 . Register a local authentication connection for Evergreen:
  15   .. Go to *Management* -> *Connections*.
  16   .. Under *Local authentication* click *Add*.
  17   .. In the wizard that appears, select *Evergreen* as the local authentication
  18   system type (or *API* if Evergreen is not listed) and click *Configure*.
  19   .. For *Display name*, enter the name of your Evergreen portal that your
  20   patrons will be familiar with. They will need to be able to recognise and
  21   select this name from a list of sign-in options on OpenAthens.
  22   .. For *Callback URL* enter *https://<HOSTNAME>/eg/opac/sso/openathens* where
  23   <HOSTNAME> is the public hostname of your Evergreen installation, and click
  24   *Save*. (If you have installed Evergreen somewhere other than /eg, modify the
  25   URL accordingly.)
  26   .. On the details page that appears, take a copy of the *Connection ID* and
  27   *Connection URI* that have been generated. You will need these when
  28   configuring Evergreen.
  29 . Generate an API key:
  30   .. Go to *Management* -> *API keys* and click *Add*.
  31   .. For *Name*, enter 'Evergreen' or whatever name you use for your Evergreen
  32   portal internally, and click *Save*.
  33   .. Take a copy of the 36-character key that has been generated. You will need
  34   this when configuring Evergreen.
  35
  36 Full OpenAthens documentation for local authentication API connections is
  37 available at http://docs.openathens.net/display/public/MD/API+connector.
  38
  39 Configuring Evergreen
  40 +++++++++++++++++++++
  41 OpenAthens sign-on is configured in the staff client under *Local
  42 Administration* -> *OpenAthens Sign-on*. To make a connection, select *New
  43 Sign-on to OpenAthens*, and set the values as follows:
  44
  45 * *Owner* - the organisation within your library hierarchy that owns the
  46 connection to OpenAthens. If your whole consortium has signed up to OpenAthens
  47 as a single customer, then you would select the top-level. If only one
  48 regional library system or branch is the OpenAthens customer, select that.
  49 Whichever organisation you select, the OpenAthens connection will take effect
  50 for all libraries below it in your organisational hierarchy. A single
  51 OpenAthens sign-on configuration normally equates to a single *domain* in the
  52 OpenAthens service. If in doubt refer to your OpenAthens account manager or
  53 implementation partner.
  54 * *Active* - Enable this connection (enabled by default).
  55 * *API key* - the 36-character OpenAthens *API key* that was generated in step
  56   2 above.
  57 * *Connection ID* - the numerical *Connection ID* that was generated for the
  58   OpenAthens local authentication connection in step 1 above.
  59 * *Connection URI* - the *Connection URI* that was generated for the
  60   OpenAthens local authentication connection in step 1 above.
  61 * *Auto sign-on* - controls _when_ patrons are signed on to OpenAthens:
  62   ** *enabled* (recommended) - As soon as a patron logs in to Evergreen, they
  63   are signed in to OpenAthens. This happens via a quick redirect that the user
  64   should not notice.
  65   ** *disabled* - The patron is not signed in to OpenAthens to start with. When
  66   they first access an OpenAthens-protected resource, they will need to search
  67   for your institution at the OpenAthens log-in page and choose your Evergreen
  68   portal as the sign-in method (they will see the name you entered as the
  69   *Display name* in step 1 above). Evergreen will then prompt for log-in if
  70   they have not already logged in. After that, they are signed in to OpenAthens
  71   and OpenAthens redirects them to the resource.
  72 * *Auto sign-out* - controls whether the patron is signed out of OpenAthens
  73   when they log out of Evergreen. If *enabled* the patron will be sent to the
  74   OpenAthens sign-out page when they log out of Evergreen. You can optionally
  75   configure the OpenAthens service to send them back to your home page again
  76   after this; the setting can be found at https://admin.openathens.net/ under
  77   *Preferences* -> *Domain* -> *After sign out*.
  78 * *Unique identifier field* - controls which attribute of patron accounts is
  79   used as the unique identifier in OpenAthens. The supported values are 'id'
  80   and 'usrname', but you should leave this set to the default value of 'id'
  81   unless you have a reason to do otherwise. It is important that this attribute
  82   does not change during the lifetime of a patron account, otherwise they would
  83   lose any personalised settings they have saved on third party resources. It
  84   is also important that you do not re-use old patron accounts for new users,
  85   otherwise a new user could see personalised settings saved by an old user.
  86 * *Display name field* - controls which attribute of patron accounts is
  87   displayed in the OpenAthens portal at https://admin.openathens.net/. (This
  88   is where you can see which accounts have been used, and what use patrons are
  89   making of third party resources.) The supported values are 'id', 'usrname'
  90   and 'fullname'. Whichever you choose, OpenAthens will only use it within
  91   your portal view; it won't be released to third-party resources.
  92 * *Release X* - one setting for each of the attributes that it is possible to
  93   release to OpenAthens. Depending on your user privacy policy, you can
  94   configure any of these attributes to be released to OpenAthens as part of
  95   the sign-on process. None are enabled by default. OpenAthens in turn doesn't
  96   store or release any of these attributes to third party resources, unless
  97   you configure that separately in the OpenAthens portal. You have to
  98   configure this in two stages. Firstly, mapping Evergreen attributes to
  99   OpenAthens attributes, and secondly releasing OpenAthens attributes to third
 100   party resources. See the OpenAthens documenation pages at
 101   http://docs.openathens.net/display/public/MD/Attribute+mapping and
 102   http://docs.openathens.net/display/public/MD/Attribute+release. You will need
 103   to know the exact names of the attributes that are released. These are listed
 104   in the following table:
 105
 106 |===
 107 |Setting|Attribute released|Description
 108
 109 |Release prefix
 110 |prefix
 111 |the patron's prefix, overriden by the preferred prefix if that is set
 112
 113 |Release first name
 114 |first_given_name
 115 |the patron's first name, overriden by the preferred first name if that is set
 116
 117 |Release middle name
 118 |second_given_name
 119 |the patron's middle name, overriden by the preferred middle name if that is set
 120
 121 |Release surname
 122 |family_name
 123 |the patron's last name, overriden by the preferred last name if that is set
 124
 125 |Release suffix
 126 |suffix
 127 |the patron's suffix, overriden by the preferred suffix if that is set
 128
 129 |Release email
 130 |email
 131 |the patron's email address
 132
 133 |Release home library
 134 |home_ou
 135 |the _shortcode_ of the patron's home library (e.g. 'BR1' in the Concerto
 136 sample data set)
 137 |===
 138
 139 Network access
 140 ++++++++++++++
 141 As part of the sign-on process, Evergreen makes a connection to the OpenAthens
 142 service to transfer details of the user that is signing on. This data does not
 143 go via the user's browser, to avoid revealing the private API key and to avoid
 144 the risk of spoofing. You need to open up port 443 outbound in your firewall,
 145 from your Evergreen server to login.openathens.net.
 146
 147 Admin permissions
 148 +++++++++++++++++
 149 To delegate OpenAthens configuration to other staff users, assign the
 150 *ADMIN_OPENATHENS* permission.