# 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 {% hint style="info" %} Significant changes were introduced to the LDAP configuration in Elentra ME 1.15.0. Please ensure that you update your settings files appropriately. {% endhint %} ``` 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](https://apereo.github.io/cas) or [Shibboleth](https://shibboleth.net/), 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](https://www.shibboleth.net/about-us/) 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. {% hint style="success" %} Full Shibboleth installation instructions can be found on the [Shibboleth Single Sign-on](/technical/administrators/application-server/shibboleth-single-sign-on.md) page under the [Application Server](/technical/administrators/application-server.md) setup. {% endhint %} 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_METHOD`constant 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.elentra.org/technical/developers/authentication-methods.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.