To configure a specialized authentication portal landing page that will allow your site to provide both RemoteAuth and Non-RemoteAuth logon options from a single link within a catalog or finding aid, see the instructions below.
The application files needed for this feature are available as a zip file on the ILLiad Downloads page. Alternatively, ILLiad Customer Service can supply the application to you and assist you with the setup.
Authentication Portal Details
Sites wanting to provide users with one link to various different logon options can use the Atlas Authentication Portal feature. The Atlas Authentication Portal application allows sites to provide a single link from a catalog or finding aid system that will take users to a page where they can select whether they log in via RemoteAuth or another method. In addition to providing logon links, this feature supports passing query string data through the portal to the selected destination.
The specialized authentication portal landing page, Index.cshtml, displays instructional text to help sites configure the portal for viewing and editing. Once configured, this page will provide users the options for logging into ILLiad. When the user clicks the link and logs into ILLiad, the item data embedded in the original link is carried through and applied to the request form. This page is located in the AtlasAuthPortal file under \AtlasAuthPortal\Views\Portal.
Two Types of Access
There are two options available for configuring the portal: form-based access and linked based access. The default authentication portal page explains in detail how each option works and how to configure either of these options for use by your site.
Automatic Redirect Feature
When the portal is invoked it supports cookie-based tracking of the options selected by the user. If the user is currently logged into the destination system and has previously gone through the portal, it will forward them to their destination rather than show them the selection screen again.
As of Atlas Auth Portal version 1.3, the redirectUrl parameter has been replaced with the authType parameter. The default pages accept the authType values of AtlasAuth and RemoteAuth. For instructions on configuring the authType parameter settings of AtlasAuth and RemoteAuth, see the index.cshtml page for examples. In the index.cshtml, the examples use the default AtlasAuth and RemoteAuth values as placeholder for demonstration purposes only. When configuring your site's redirect URL, take the redirect URL values from your index.cshtml page and put them in the web.config as a named setting, and then update the index.cshtml to pass the authType parameter with the respective names.
In version 1.3, the RedirectUrlCookieName setting has been removed and replaced with the AuthTypeCookieName which defaults to AtlasAuthType. This change prevents the redirect URL from storing the user's cookies. Instead we now store the name of the auth type to use instead. This change will also prevent upgrade issues with users that have redirect URL cookies in their browsers already.
Session Cookie Features
As of Atlas Auth Portal version 1.3.2, the session cookie generated by the Atlas Auth Portal upon login will now include SameSite and Secure properties to address the recent SameSite cookie changes rolled out by Google Chrome and other web browsers. Note that the issues caused by these changes are only present in other Atlas products and do not affect ILLiad at this time. As these changes do not affect ILLiad, this update is optional and is not required to maintain any existing Auth Portal functionality in ILLiad. After the update is applied, the SameSite and Secure properties will be set on the user's session cookie as follows when the user places a request to ILLiad from an external website (i.e., a website outside of the ILLiad web pages, such as a library catalog):
- When a user places a request from an external website using HTTPS:
- The SameSite property on the session cookie will be set to None and the Secure property set to True
- When a user places a request from an external website using HTTP:
- The SameSite property on the session cookie will be set to Lax and the Secure property set to False
Installing the Atlas Authentication Portal Application
As of version 1.3.2, in order for the Atlas Authentication Portal to work properly, you must have Microsoft .NET 4.7.2 Framework (or higher) installed on your ILLiad web server. You must be on ILLiad Web DLL v9.2.3 to use the new features in Atlas Authentication Portal v1.3.2.
- Download the AtlasAuthPortal files and extract the folder to the web folder on the server (C:\inetpub\wwwroot\illiad is the default).
- Open the IIS Manager on your server.
- Navigate to AtlasAuthPortal by clicking Your Server Name | Sites | Default Web Site | ILLiad | AtlasAuthPortal.
- Right click on the Atlas Auth Portal and select Convert to Application.
- Accept the application defaults or make changes and click OK. The AtlasAuthPortal icon will change from a folder to an application icon.
Configuring the Atlas Authentication Portal
OpenURL and the Atlas Authentication Portal | Overriding the Default Session Cookie SameSite Attributes
Once you have installed the Atlas Auth Portal application, there are two steps to set up the authentication portal feature.
- Modify the default portal page (Index.cshtml) using the instructions provided on the page. This page is located in the AtlasAuthPortal file under \AtlasAuthPortal\Views\Portal.
- Edit the Web.config file for the authentication portal to include the correct <appSettings> values for the SessionCookieName and UsePersistentRedirectCookie settings. This file is located in the AtlasAuthPortal file under \AtlasAuthPortal\Views.
- SessionCookieName value: ILLiadSessionID: This controls the cookie that should be looked for to identify whether or not the user is logged in. By default ILLiad stores the login as ILLiadSessionID.
- UsePersistentRedirectCookie value: true: This determines whether or not the cookie used to store the redirectURL the user selected on their last visit should be persistent or not (whether the cookie should be available after the user has closed their browser and come back to the portal).
- RedirectUrlCookieName: RedirectUrl: This specifies the name to use when storing the portal's redirect URL in a cookie. By default ILLiad stores the name as RedirectUrl. This can be changed to avoid conflicts between multiple instances of the Atlas Auth Portal on the same domain. For example, if a second instance of the Atlas Auth Portal is set up to redirect to the open URL action, its RedirectUrlCookieName might be set to OpenUrlRedirectUrl.
Because cookies are generally specific to the domain that they are created under, the Automatic Redirect Feature cannot be used unless both the Portal landing page and the ILLiad.dll (which generates the session cookie that the Portal is looking for) are both under the same domain. Therefore, the Portal landing page URL needs to have the same domain name as the resulting ILLiad DLL pages. Generally, all of these web pages are on the same server, but take care to use a consistent DNS name. Otherwise, the portal page will be set up correctly, but users will still have to pass through that page after having authenticated.
OpenURL and the Atlas Authentication Portal
Link resolvers can pass an OpenURL link through the Atlas Authentication Portal. To do so, you'll need to configure the target base URL along with any additional query parameters. When sites either only use the Auth Portal for OpenURL requests or have multiple instances of the Auth Portal configured (dual auth sites) with one dedicated to OpenURL, the Action and Form parameters (e.g., Action=10 and Form=30) should be configured as part of the redirect URL in the Auth Portal pages and should be transparent in the link resolver.
Overriding the Default Session Cookie SameSite Attributes (Not Recommended)
The default SameSite property values that are set on the Atlas Auth Portal session cookie as of v1.3.2 can be altered if necessary by manually setting an override value for CookieSameSiteMode in the portal's web.config file. When an override value is configured, the SameSite property on the session cookie will be set to that value for both HTTPS and HTTP requests, rather than having it set to None by default for HTTPS requests and Lax by default for HTTP requests. Valid override values are Strict, Lax, or None:
- Strict: The SameSite property on the cookie will always be set to Strict
- Lax: The SameSite property on the cookie will always be set to Lax
- None: The SameSite property on the cookie will always be set to None
Setting the Override Value
To override the default SameSite attributes on the session cookie with one of these three options:
- Open file explorer and navigate to C:\inetpub\wwwroot\ILLiad\AtlasAuthPortal.
- Right-click and open the web.config file in your preferred code editor (e.g., Notepad ++, Visual Studio Code)
-
Add the following key just below the "AuthTypeCookieName" line, replacing [InsertOverrideValueHere] with one of the options above:
<add key="CookieSameSiteMode" value="[InsertOverrideValueHere]"/> - Save your changes