Local User Database

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

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

2. Elentra's index.php connects to the auth/login path on the Elentra API. The authentication code then queries the elentra_auth.user_data database table for the username and password combination, then ensures a valid elentra_auth.user_access database table record exists.

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

LDAP / Active Directory

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 core/config/settings.inc.php

2. Ensure that 'ldap' (for Unix LDAP) or 'ad' (for Active Directory LDAPis present in the AUTH_METHOD constant.

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

4. Elentra index.php connects to the Elentra API auth/login path, which binds to the LDAP server (LDAP_HOST constant). Unix LDAP typically requires a privileged account to connect to the LDAP server, LDAP_SEARCH_DN and LDAP_SEARCH_PASS constants will hold the credential for this connection.

5. If a privileged account is required and successfully authenticated, the authentication server queries the directory to obtain the account information for the University username that the user entered.

6. Providing a record does exist in the directory, the authentication server then attempts to re-bind to the LDAP server using the generated user_dn, and the University password that the user entered. The constant LDAP_BIND_REQUIRES_DN controls whether this user_dn is fully qualified.

   Example User DN: UniUid=mr66,ou=people,dc=queensu,dc=ca

7. Finally if the authentication server was successfully able to bind to the LDAP server with the user_dn and password, it then queries the elentra_auth.user_data database tables' number field (by default) for the staff / student number LDAP_USER_QUERY_FIELD constant returned by the directory for that account.

8. If a valid record is found authentication was success, 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.

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".