Application Technical Requirements

General technical requirements

This page describes general technical requirements for the application. These include important specifications for security, proxy awareness, i.e. it is mandatory for the application to meet the following requirements so that it can be integrated with the standard eIAM service.

Encrypted data transmission

The entire data transmission from the web browser to the application MUST be encrypted using TLS in the Transport Layer. In order to enable the WAF features of eIAM and the reverse proxy functionality, the encryption between the browser and the application must be broken on the load balancer before the WAF and on the eIAM-Web PEP and a new, also encrypted connection must be established. Likewise, all communication on the transport layer necessary for authentication of the user must be encrypted.

Proxy Awareness

To enable the integration of applications into the eIAM service, requirements are placed on the so-called proxy awareness of the application. Applications that are built proxy-aware can be used behind a reverse proxy without additional effort and can thus be integrated into the service eIAM.

Whether a web application is proxy-aware can be found out by testing the application via the reverse proxy or by searching the HTML content for fully qualified or absolute links. J2EE servlet applications are usually proxy-aware or can be made proxy-aware without much effort by adjusting the deployment URL. If the HTML content does not change when the deployment URL is adapted, the application is completely proxy-aware.

Following, the criteria for proxy awareness are explained in more detail. These requirements are mandatory for applications used with eIAM.

Note
Is not a requirement of eIAM for applications outside the networks of the Federal Administration.

URLs in "proxy-aware" applications
Typically, the user uses an application by addressing requests to URLs. A URL can be either a fully qualified, an absolute or a relative address. In contrast to a fully qualified URL, a relative URL contains neither a schema prefix nor the server address, but only the path and the name of the target document. The path itself can again be absolute (starting from the root directory of the web server) or relative to the directory of the source document. If the path begins with "/", it is an absolute path starting from the respective root directory.

The following table lists the different types of links with examples.

Type of link	Example
Relative paths	./Documents/index.html ../images/logo.gif ../../resources/title_bar.png
Absolute paths	/myapp/Documents/index.html /myapp/images/logo.gif
Fully qualified URL	https://mycompany.com/myapp/Documents/index.html https://mycompany.com/myapp/images/logo.gif

The following figure shows the different types of links as they must be used in the application.

: Use of the different types of links

The following rules apply to the cases in the figure above.

Case	Link	Type	Rule
1	./Documents/index.html	Relative path within the application	1st rule
2	./images/logo.gif	Relative path to internal resources]	3rd rule
3	/otherapp/start.do	Absolute path to another application behind the same PEP (identical FQDN)]	4th rule
4	https://www.otherserver. com/foo/bar/	Fully qualified URL to external web resource (outside the FQDN of the current application)	5th rule

The following guidelines apply to application development

Use of relative URLs
1st rule: applications must use relative URLs within the application for integration into eIAM.
The use of relative URLs is a necessary but not sufficient condition for proxy awareness. In a proxy environment, all integrated applications are mapped to a dedicated top-level location (root location) on the reverse proxy (e.g. "https://somehost.ch/myappl/"). From this, the criteria for proxy awareness described in the following sections can also be derived.

Self-contained URLs
2nd rule: Web applications and their resources must be accessible and functional under a self-contained URL.
Since the proxy carries out the servlet mapping and thus the construction of the filter chain on the basis of the URL, web applications must be accessible and functional under their own, self-contained URL (e.g. "https://somehost.ch/myappl/"). They must not be deployed under the root directory (i.e. "https://somehost.ch/"). This applies to all resources provided by the application - i.e. including style sheets, images, scripts, etc.

URLs within applications
3rd rule: All links to in-app resources within the application must be relative paths.
Similarly, links within the application that address their own resources must be relative (e.g. "./pics/picture.gif") and must not be absolute (e.g. "http://somehost.ch/myappl/pics/picture.gif").

Link applications via absolute paths
4th rule: Applications are linked by means of absolute path specifications without server addresses.
If another application is addressed within an application, this is referred to as coupled applications. Within the eIAM, this coupling must take place exclusively via the proxy. The application must know how its partner application can be reached via the proxy. Accordingly, links to partner applications must be realised as absolute path specifications without specifying the server address (e.g. "/otherapp/start.do").

Addressing external URLs
5th rule: Application-external URLs are always addressed via absolute server and path specifications
URLs that address an external resource (e.g. reference to a website of another organisation or general website on the Internet) are of course specified absolutely with server and path details. It must be ensured that such URLs are globally accessible.

The HTML tag "basehref"
6th rule: The HTML tag "basehref" must not be set in any HTML page.
The HTML tag "basehref" is often used to reduce the amount of repetitive text in an HTML document. The "basehref" tag tells the browser that all relative links in this document begin with the specified address. While this helps when creating an HTML document, because layout and behaviour can be easily tested locally and the document does not need to be placed on a server. However, it is difficult to implement in a proxy environment because the proxy maps the application to a dedicated top-level location. Thus, the "basehref" tag must not be set in any HTML page.

Specification of the Content-Type
7th rule: The content type must always be specified.
The content type must always be specified, otherwise the reverse proxy will use a default value. This can lead to undesired effects in the browser (HTML code is displayed as text).

The following rules are not a requirement of eIAM for applications outside the networks of the Federal Administration.

URIs within applications
8th rule: The different URI namespaces of an application with different protection requirements must be structured simply and must not overlap.
Overlaps occur if, for example, you want to protect /appl1/private/* and /appl1/private/public/* differently. Within the path /appl1/private/*, which is protected in itself, there is an unprotected path ./public/*. This is not permitted.

Requirements for the URLs of the application

Cookies for session tracking
9th rule: The use of cookies for session tracking of the application is mandatory.
Session tracking of the application has to be done by session cookie. URL rewriting as a session tracking method is not supported by eIAM.

General requirements for session management

Session-Tracking
[Rule 10: Application timings shall be higher than those on the PEP. The PEP is the master over the sessions.
It is important that applications adjust their session duration and timeouts to the PEP.

General requirements for session management

SAML/messages on fixed URLs
11th rule: Applications within the Federal Administration networks must accept SAML/messages on fixed URLs.
For applications within the Federal Administration networks, the destination address of the eIAM-Web PEP's response to the application's AuthnRequest is fixed and is preconfigured in the application's metadata. The application must therefore accept the SAML response, the logout request and the logout response on a fixed URL each.

Detailed technical requirements from the SAML 2.0 interface

End SSO session
12th rule: When ending an SSO session (SLO Single Logout/Timeout), applications can be informed by the PEP via the configured logout URI.
One Logout URI per application can be configured in the eIAM-Web PEP. If this URI is defined, each application used within this SSO session will be notified when the SSO session is terminated. In this way, applications can be notified by the PEP of terminated SSO sessions in order to in turn cleanly close the user's session.

Session Termination RP-PEP

Query Parameters Reserved by eIAM

The following query parameters are reserved for the eIAM service and MUST NOT be used by applications.

?logout
?login

Note
Is not a requirement of eIAM for applications outside the Federal Administration networks.

http verbs supported by eIAM

The following http verbs are supported by default by the eIAM service:

GET
POST

Depending on the application, it may be necessary to enable further http verbs. This must be agreed with the IAM Integration Expert. Login with an initial POST request is not possible. The POST request is redirected by eIAM-Web to the same URL with the query parameter "login". The user agent then sends the original POST request as a GET request with the query parameter "login".

Note
Is not a requirement of eIAM for applications outside the Federal Administration networks.

eIAM Cookie Handling

By default, cookies issued by the application are cached on the eIAM Web PEP and not passed through to the web browser. The cookies set by the application therefore only travel between the eIAM PEP and the application.

If cookies set by the application are not to be cached on the PEP, but must be passed through to the user's web browser, this must be noted in the eIAM dossier, stating the exact name of the cookie when ordering the eIAM service.

If cookies from the PEP are allowed through to the user's web browser by the PEP, they are automatically rewritten (path and host) so that they apply to the PEP and not to the application.

Note
Is not a requirement of eIAM for applications outside the Federal Administration networks.

eIAM Request Timeout

The eIAM-Web PEP can process a limited number of simultaneous http requests. Therefore, in the interest of all applications that can be reached via the eIAM-Web PEP, the time in which such a process is occupied with waiting for the response of the application is limited. This ensures that this process is released again for the processing of another request and that a single faulty application does not negatively influence the availability of other applications.

Experience shows that users rarely wait more than 1-2 minutes to see if a response is delivered to their request until they either give up (close the browser or navigate to another resource) or resend the request (refresh).

The value for this timeout is set to 2 minutes in eIAM-Web. After this interval an html error page with the http code 502 (Upstream Server not available) is delivered to the client.

The value for the request timeout can be configured differently per mapping in justified exceptional cases. A request must be made to change the value.

Note
Is not a requirement of eIAM for applications outside the networks of the Federal Administration.

Client Tracking between eIAM-Web PEP - Web Browser

A non-persistent session cookie is issued by the PEP on the name '<eiam-amt>' e.g. 'eiam-foitt'. Client tracking on the PEP is based on this cookie. The coo-kie is renewed after the establishment of a security context (session) on the PEP.

The session cookie issued by the eIAM-Web PEP has the following attributes:

HttpOnly - (The web browser must not allow the cookie to be read by a script. This is not supported in all browsers, especially older ones).
Secure - (The web browser must only return the cookie via a connection secured on the Transport Layer).
Host - (not set) by default set to the FQDN of the cookie issuer
Path - / (root)

Client Tracking between Application - eIAM-Web PEP

If the application establishes a security context with the user's session on the PEP, the application MUST use client tracking based on cookie. The application's cookies only travel between the application and the PEP and are not passed on to the user's web browser. Other session tracking mechanisms such as SSL-ID, and URL rewriting are not supported by the eIAM service.

Note
Is not a requirement of eIAM for applications outside the Federal Administration networks.

Application Logout Button with Logout Page and Re-Login Option

The application to be integrated must offer the users the possibility to close their currently running session. For this purpose, a button or a link that initiates a logout must be implemented in the application. For applications that are implemented using STS-PEP (standard), the STS-PEP then forwards the user to the logout page of the application. This logout page, which must be provided by the application, confirms to the user that his session has been correctly closed.

: Logout Confirmation with Re-Login

In order for a user to be able to log back into the application directly after a logout, there is an optional "Re-Login" button on the logout page. This button facilitates navigation if you want to log in again directly, for example if the user has forgotten an action in the specialist application or if something is being tested in the specialist application. The button is available on all environments REF, ABN and PROD.