Authentication Methods

Local User Database

define("AUTH_METHOD", "local"); // Defined in core/config/settings.inc.php

1. The user visits your Elentra installation and enters their username and password.

2. Elentra submits the authentication request to the Elentra API. The authentication process queries the elentra_auth.user_data database table for the username and password provided by the user, then ensures a valid elentra_auth.user_access database table record exists.

3. If a valid record is found, authentication was successful, otherwise an error is returned.

LDAP / Active Directory

Significant changes were introduced to the LDAP configuration in Elentra ME 1.15.0. Please ensure that you update your settings files appropriately.

define("AUTH_METHOD", "ldap"); // Defined in core/config/settings.inc.php

1. To use LDAP you must first enable it by configuring the LDAP_* constants in settings.inc.php. Also, you must ensure that ldap is present in the AUTH_METHOD constant.

2. The user visits your Elentra installation and enters their username and password.

3. Elentra's index.php submits the authentication request to the Elentra API, which attempts the bind to the LDAP server (defined by the LDAP_HOST constant).

4. If a service account is used, the authentication server queries the directory to obtain the account information for the provided username. Providing a record is found, the authentication server then attempts to re-bind to the LDAP server using the resulting user_dn and the password entered by the user. The constant LDAP_BIND_REQUIRES_DN controls whether this user_dn is fully qualified.

5. If a service account is not used, the authentication server attempts to bind to the LDAP server using the username and password provided by the user.

6. If the authentication server was successfully able to bind to the LDAP server, which means the username and password provided by the user was correct, it then queries the elentra_auth.user_data database table's number field (defined by the LDAP_LOCAL_USER_QUERY_FIELD constant) for the UniCaPKey identifier (defined by the LDAP_USER_QUERY_FIELD constant) returned by the directory for that account.

7. If a valid record is found, authentication was successful, otherwise an error is returned.

Single Sign-On

define("AUTH_METHOD", "sso"); // Defined in `core/config/settings.inc.php`

Elentra supports SSO authentication with either CAS or Shibboleth, which can be provided in addition to the local and ldap methods above. The implementation allows for the possibility to have either SSO as an option, or to eliminate the local/LDAP login and force SSO to be used. The setting of AUTH_METHOD will determine how this works.

If AUTH_METHOD chains "sso" with "ldap" or "local", Elentra will present a local login screen, with a link to select SSO or a form to provide local or LDAP credentials.

If AUTH_METHOD contains only "sso", the only valid way to authenticate is SSO, so the local login screen will be bypassed completely. On startup of Elentra, you will immediately re-direct to the SSO authority if you are not already logged in.

Shibboleth

Shibboleth consists of Identity Provider (IDP) and Service Provider (SP) components, where the IDP performs the authentication and the SP acts as the interface to the application. In a typical configuration, the IDP would provide SSO services for a range of different websites at the same organization. The Shibboleth Website provides a good overview of the concepts and architecture.

The steps for integrating Elentra with Shibboleth authentication would be:

1. Install the Shibboleth Service Provider component on the Elentra web server.

2. Configure the metadata and user attributes in both the Service Provider and Identity Provider.

3. Configure Elentra SSO settings to match the Service Provider configuration.

Full Shibboleth installation instructions can be found on the Shibboleth Single Sign-on page under the Application Server setup.

The Service Provider can be configured in either an Active or Passive mode. In Active mode, the Apache webserver configuration determines which pages within Elentra are protected and the system will automatically prompt for SSO authentication before displaying the pages. This method is possible for Elentra, but you will have to very carefully configure the apache web server to allow non-secure access to things like RSS feeds.

If the Service Provider will be setup in Active mode, or you have AUTH_METHOD set to allow SSO only, make sure you have at least one administrative user added to Elentra with a valid student/employee ID before enabling Shibboleth.

In Passive mode, SSO authentication will appear as an option on the login page and the user may use SSO or a local/LDAP login to get access to the system, as controlled by AUTH_METHOD.

To enable Shibboleth authentication, set the constants in core/config/settings.inc.php.

define("AUTH_SSO_ENABLED", true); 
define("AUTH_SSO_TYPE", "Shibboleth");
define("AUTH_SSO_LOCAL_USER_QUERY_FIELD", "number");

The language file in the templates directory has an entry "SSO Login" that can be changed to customize the prompt that will appear on the login page.

You can use AUTH_SSO_LOCAL_USER_QUERY_FIELD to change the column that is searched in the authorization database user_data table to match the attribute returned from the Identity Provider.

Additional core/config/settings.inc.php settings are related to the Service Provider configuration:

define("AUTH_SHIB_URL", "https://elentrasp.yourschool.ca");
define("AUTH_SHIB_LOGIN_URI", "/Shibboleth.sso/Login");
define("AUTH_SHIB_LOGOUT_URI", "/Shibboleth.sso/Logout");
define("AUTH_SHIB_SESSION", "Shib-Session-ID");
define("AUTH_SHIB_ID", "shib-studentid");

The Service Provider component is installed on the same web server as the Elentra application, but could be set up on a separate virtual host. Change AUTH_SHIB_URL to point to that host.

The LOGIN and LOGOUT URIs will point to the login and logout targets to use on the SP host. The definitions provided are the default settings for Shibboleth.

If the Service Provider is using the same virtual host as the Elentra application, you may need to add entries to the root folder's .htaccess file to ensure the login and logout URIs are not re-written.

...
RewriteRule ^Shibboleth.sso/* - [L,NC]

# Default Entrada Rules
...

The final two constants refer to the Metadata and User Attributes configured in Shibboleth. If Shibboleth authentication is successful, the Service Provider will set attributes in the $_SERVER environment. AUTH_SHIB_ID refers to the attribute that represents the unique identifier for the Elentra user. This will be matched against a column in the Elentra Authorization Database's user_data table, based on the column name contained in AUTH_SSO_LOCAL_USER_QUERY_FIELD. This defaults to the "number" column. Other good candidate columns might be username or email, depending on what your organization is prepared to return from the Identity Provider.

After logging into Elentra with Shibboleth, the logout process will invoke the Service Provider's logout end point. What happens then will depend on the configuration of Shibboleth. In most cases this would redirect to a logout page on the Identity Provider, which will terminate all SSO sessions that the user has created - with Elentra and any other services supported by that Identity Provider.

CAS

To enable CAS authentication, update the constants in core/config/settings.inc.php

define("AUTH_SSO_ENABLED", true);
define("AUTH_SSO_TYPE", "cas");

define("AUTH_CAS_HOSTNAME", "cas.schoolu.ca");
define("AUTH_CAS_PORT", 443);
define("AUTH_CAS_URI", "cas");
define("AUTH_CAS_COOKIE", "isCasOn");
define("AUTH_CAS_SESSION", "phpCAS");
define("AUTH_CAS_ID", "peopleid");

The architecture for CAS is similar to Shibboleth, except that the Service Provider component is handled by the phpCAS library that is included with Elentra.

For CAS, the AUTH_CAS_ID needs to be set to the attribute returned by the CAS server that represents the student/employee ID number, and will be matched to the number column of the Elentra Authorization database's user_data table.

When CAS is enabled, the Elentra login screen will get a link that allows the user to select CAS authentication, or to login with local or LDAP credentials.

Chained Authentication

define("AUTH_METHOD", "local, ldap"); // Defined in `core/config/settings.inc.php`

Elentra supports chained authentication to allow you to offer users multiple methods of authenticating into the same account in your system.

If you would like to allow both local, and LDAP authentication you simply define the AUTH_METHODconstant in core/config/settings.inc.php to be "local, ldap" or "ldap, local" (depending on the chain order you prefer) instead of "local" or "ldap".

Load balancer - configure authentication in a no-SSL setup

If you're using a load balancer, it is probably the load balancer handling SSL certificates. In this case, you don't have SSL on the server itself.

In this case, you need to tell Elentra ME not to use SSL when authenticating with the API.

Change the following line in the settings.inc.php file:

define("AUTH_PRODUCTION", ENTRADA_URL . "/api/v2/auth/login");

to:

define("AUTH_PRODUCTION", "http://elentra.med.university.edu/api/v2/auth/login");

This will make the authentication module not use SSL when connecting to the API to login.