LoginRendererServlet
The LoginRendererServlet generates the HTML pages required for user interaction during initial authentication, authentication stepups, unlock (screensaver) or logout.
The LoginRenderer has three different modes to generate HTML pages. The first mode (localBuiltIn) embeds XML data received from the authentication service in a built-in template file. The second mode (localTemplate) embeds the received XML data in a user-defined template file. The third mode (remote) forwards the XML data to a configured remote rendering servlet.
Furthermore, the LoginRenderer can be used to configure whether the HTML pages are displayed inside the browser window (embedded) or in a popup window (popup), or, in a new window on top of all the other windows. This configuration can be done separately for every authentication method (authenticate, logout, stepup, unlock).
The LoginRenderer can be set to enable the handling of cookies, although the default is set to block (not accept) cookies.
It is possible to render language-specific logon screens because the attribute language was added to the GUI descriptor. The templates are names <realm>_<language>_template.html.
Classname:
ch::nevis::isiweb4::servlet::rendering::LoginRendererServlet
Library:
libRenderingServlets.so.1
Configuration
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| RenderingProvider | enum: localBuiltIn: [html|soap|xml|auto]:<status>; localTemplate: <dir>; remote: <servlet>:<uri>; optional, basic feature; default: localBuiltIn:xml:200 | Describes how the authentication data is rendered. localBuiltIn:[html|soap|xml|auto]: <status> is used for built-in rendering. The type of the generated response can be configured: html: an HTML response will be generated soap: a SOAP fault response will be generated xml: the XML data from the authentication service will be sent as response auto: a HTML response or a SOAP fault will be generated, depending on the existence of SOAPAction HTTP header in the request. localTemplate: <dir> is used for customized rendering templates in the directory <dir>. The directory <dir> must be readable. remote: <servlet>:<uri> can be used to fully control the look of the HTML page. |
| UseFallback | boolean; optional, basic feature; default: true | If the remote rendering service is not available, the mode ‘localBuiltIn’ is used as a fallback. That behavior can be disabled by setting ‘UseFallback’ to ‘false’. |
| PreloadTemplates | boolean; required, advanced; default: true | If the attribute ’PreloadTemplates’ is configured to ’false’ the rendering templates will be read every time the login page will be rendered. |
| authmethod.Authenticate | enum: top, embedded, popup:<height>:<width>; optional, advanced; default: embedded | The parameter value ‘embedded’ displays the authentication data inside the browser window. The parameter value ‘top’ displays the authentication data inside the top frame of the browser window. The parameter value popup:<h>:<w> opens a popup window.<height> (<width>) is the popup window height (width). A positive integer has to be used. If ‘top’ or ‘popup’ is set, the login page is rendered via the JavaScript method document.write(). In some browsers, this may cause problems. To render the login page in the top frame avoiding these problems, set the value of the attribute ‘ClearFrames’ of the corresponding IdentityCreationFilter to ‘authenticate🔓stepup’. |
| authmethod.Unlock | optional, advanced; default: popup:300:500 | see above. |
| authmethod.Stepup | optional, advanced; default: embedded | see above. |
| authmethod.Logout | optional, advanced; default: embedded | see above. |
| AcceptHtmlFormattedTexts | boolean; default: true | Defines whether or not nevisAuth info and error texts are used as is. |
| PropagateRemoteHeaders | string | Defines a list of HTTP headers that will be propagated from the remote rendering service to the client. The single values must be separated by : or newline. ‘Set-cookie’ can be added to enable the propagation of cookies from rendering provider. |
| BufferResponse | string; default: true | If set to ’true’, which is the default, the response will be buffered and only written if the request has been processed. |
| PipedHttpServletRespnseWrapper | string | Also used by CacheFilter and DumpFilter, can be modified to handle cookies separately from headers. We have added the ’BufferResponse’. If set to ’true’ which is the default. The response will be buffered and only written if the request has been processed. Note that there is no performance penalty since there is no streaming. |
| LinkType | optional, advanced; default: qualified | Permits configuration of the URL generated for the form action. The following values are supported (sample request URL=<<https://fulvia.adnovum.ch:44411/filter/auth/esauth/): Requirement: Login should also be possible for cascaded nevisProxy servers. Description: The login page generated by the LoginRenderingServlet is not proxy- aware because the target URL of the login form is qualified. - qualified - absolute - relative The default value is ’qualified’, i.e., the behavior remains the same as in previous versions. |
| OverrideRemoteResponse | boolean; optional, advanced; default: true | Defines if the remote response will be overridden. This option has no effect if the HTTP response code received is 200. Such responses are never overridden. |
| ContentTypeCharset | string; optional, advanced; default: utf-8 | Defines the charset of the "Content-Type" response header, if not already set. |
RenderingProvider
localBuiltin
This 'localBuiltin' mode uses a built-in HTML renderer with no site-specific customizations. The style sheet and a single image may be customized. This approach is very convenient for tests or simple login dialogs where:
- language support is not a requirement
- it is handled by the authentication service (e.g. nevisAuth).
In the generated HTML response, one style sheet and one image will be referenced. These two resources can be configured with the attribute 'generalResourceDir' in the tag Engine. See the Virtual hosts chapter.
localTemplate
The HTML pages generated by the 'localTemplate' mode contain three parts: the HTML header part, the authentication block, and the HTML footer part. The header and footer can be customized using templates. The LoginRendererServlet accepts HTML templates provided in the configured directory for different domains. The template's file name must match one of the following formats: <domain-name>_template.html
<domain-name>_<language>_template.html, with the value of language in lower case.
The latter option enables the support of language specific rendering of login screens. The language can be selected by the user by the query or body parameter 'language' or by the 'Accept-language' header. If no language is specified or found, then the first option (<domain-name>_template.html) is used.
The template file contains a customized header and footer, and the string 'NEVIS_AUTH_FORM' (typically somewhere between the header and the footer). This string is replaced by the authentication block before the whole HTML page is sent to the client.
This approach is very convenient for tests or simple login dialogs, where language support is either not a requirement or handled by the authentication service (e.g. nevisAuth). The installation contains a template for the 'test' domain (i.e. nevisProxy spool directory test_template.html).
remote
When using the 'remote' mode, an external rendering servlet can be configured to render the login pages. As input, the login renderer service will receive a body in a POST request containing an XML structure completely describing the required GUI. A login page may therefore be rendered by simply performing a style-sheet transformation. The specification for the login GUI descriptor is available in the nevisAuth Reference Guide (A.2, Nevis GUI Descriptor).
Be aware that the "remote" RenderingProvider relies on the values of the clientId and transferId provided by nevisProxy. The default nevisProxy configuration contains a DelegationFilter that propagates these values to the RenderingProvider. The following sample configuration replaces the DelegationFilter, in case it has been deleted:
<filter>
<filter-name>LoginRendererDelegationFilter</filter-name>
<filter-class>::ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>
<init-param>
<param-name>Delegate</param-name>
<param-value>
ENV:bcx.servlet.session.HttpSessionId:clientId
ENV:bcx.servlet.request.TransferID:transferId
</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>LoginRendererDelegationFilter</filter-name>
<servlet-name>NameOfLoginRendererServlet</servlet-name>
</filter-mapping>