docs/admin/authentication_proxy.adoc

   1 Authentication Proxy
   2 --------------------
   3
   4 indexterm:[authentication, proxy]
   5
   6 indexterm:[authentication, LDAP]
   7
   8 To support integration of Evergreen with organizational authentication systems, and to reduce the proliferation of user names and passwords, Evergreen offers a service called open-ils.auth_proxy. If you enable the service, open-ils.auth_proxy supports different authentication mechanisms that implement the authenticate method. You can define a chain of these authentication mechanisms to be tried in order within the *_<authenticators>_* element of the _opensrf.xml_ configuration file, with the option of falling back to the native mode that uses Evergreen’s internal method of password authentication.
   9
  10 This service only provides authentication. There is no support for automatic provisioning of accounts. To authenticate using any authentication system, the user account must first be defined in the Evergreen database. The user will be authenticated based on the Evergreen username and must match the user's ID on the authentication system.
  11
  12 In order to activate Authentication Proxy, the Evergreen system administrator will need to complete the following steps:
  13
  14 . Edit *_opensrf.xml_*.
  15 .. Set the *_open-ils.auth_proxy_* app settings *_enabled_* tag to *_true_*
  16 .. Add the *_authenticator_* to the list of authenticators or edit the existing example authenticator:
  17 +
  18 [source,xml]
  19 ----
  20
  21 <authenticator>
  22         <name>ldap</name>
  23         <module>OpenILS::Application::AuthProxy::LDAP_Auth</module>
  24         <hostname>name.domain.com</hostname>
  25         <basedn>ou=people,dc=domain,dc=com</basedn>
  26         <authid>cn=username,ou=specials,dc=domain,dc=com</authid>
  27         <id_attr>uid</id_attr>
  28         <password>my_ldap_password_for_authid_user</password>
  29         <login_types>
  30                 <type>staff</type>
  31                 <type>opac</type>
  32         </login_types>
  33         <org_units>
  34                 <unit>103</unit>
  35                 <unit>104</unit>
  36         </org_units>
  37 </authenticator>
  38 ----
  39 +
  40 * *_name_* : Used to identify each authenticator.
  41 * *_module_* : References to the perl module used by Evergreen to process the request.
  42 * *_hostname_* : Hostname of the authentication server.
  43 * *_basedn_* :  Location of the data on your authentication server used to authenticate users.
  44 * *_authid_* : Administrator ID information used to connect to the Authentication server.
  45 * *_id_attr_* : Field name in the authenticator matching the username in the Evergreen database.
  46 * *_password_* : Administrator password used to connect to the authentication server. Password for the *_authid_*.
  47 * *_login_types_* : Specifies which types of logins will use this authenticator. This might be useful if staff use a different LDAP directory than general users.
  48 * *_org_units_* : Specifies which org units will use the authenticator. This is useful in a consortium environment where libraries will use separate authentication systems.
  49 +
  50 . Restart Evergreen and Apache to activate configuration changes.
  51
  52 [TIP]
  53 ====================================================================
  54 If using proxy authentication with library employees that will click
  55 the _Change Operator_ feature in the client software, then add
  56 "Temporary" as a *_login_types_*.
  57 ====================================================================
  58
  59
  60 Using arbitrary LDAP usernames
  61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62
  63 Authentication Proxy supports LDAP-based login with a username that is
  64 different from your Evergreen username.
  65
  66 .Use case
  67 ****
  68
  69 This feature may be useful for libraries that use an LDAP server for
  70 single sign-on (SSO).  Let's say you are a post-secondary library using
  71 student or employee numbers as Evergreen usernames, but you want people
  72 to be able to login to Evergreen with their SSO credentials, which may
  73 be different from their student/employee number.  To support this,
  74 Authentication Proxy can be configured to accept your SSO username on login,
  75 use it to look up your student/employee number on the LDAP server, and
  76 log you in as the appropriate Evergreen user.
  77
  78 ****
  79
  80 To enable this feature, in the Authentication Proxy configuration for your LDAP server in
  81 `opensrf.xml`, set `bind_attr` to the LDAP field containing your LDAP
  82 username, and "id_attr" to the LDAP field containing your student or
  83 employee number (or whatever other value is used as your Evergreen
  84 username).  If `bind_attr` is not set, Evergreen will assume that your
  85 LDAP username and Evergreen username are the same.
  86
  87 Now, let's say your LDAP server is only an authoritative auth provider
  88 for Library A.  Nothing prevents the server from reporting that your
  89 student number is 000000, even if that Evergreen username is already in
  90 use by another patron at Library B.  We want to ensure that Authentication Proxy
  91 does not use Library A's LDAP server to log you in as the Library B
  92 patron.  For this reason, a new `restrict_by_home_ou` setting has been
  93 added to Authentication Proxy config.  When enabled, this setting restricts LDAP
  94 authentication to users belonging to a library served by that LDAP
  95 server (i.e. the user's home library must match the LDAP server's
  96 `org_units` setting in `opensrf.xml`).  Use of this setting is strongly
  97 recommended.
  98