Academy

Embedding icCube into an existing Web Application: Authentication

19th August 2021

This article is explaining a typical way to embed icCube into an existing customer Web Application and configure the authentication.

icCube will always be “behind” the customer Web application/web-server that is responsible for authentication. Once the authentication is performed, the customer Web application is sending the user information (e.g., user name, role name) to icCube via HTTP headers. icCube is being configured to retrieve this information and perform the authorization.

We advise putting in place a reverse proxy to make icCube appear (for the browser) in the same domain as the Web application to avoid all issues related to iFrame usage and/or CORS requests. All the HTTP requests that are hitting the customer Web Application targeted to icCube are being forwarded by the reverse proxy.

Authentication

It is performed by the customer Web Application that is responsible to add (for example) the following HTTP headers:

	IC3_USER_NAME
	IC3_ROLE_NAME

The IC3_ROLE_NAME must be an existing role within icCube. This is not an obligation. In a later article, we’ll explain how to perform custom/on-the-fly authorization to prevent duplicating user management into icCube.

Authorization

Simply define the required roles. Once logged the authenticated user will be attached to one of them. Find here the documentation for the access rights.

Reverse Proxy Setup

The reverse proxy is responsible for mapping the requested URLs (in the webapp.com domain) to the “internal” icCube URLs.

For example using Apache you could do something like:

ProxyRequests Off

<Proxy *>
  Order deny,allow
  Allow from all
</Proxy>

ProxyPass /analytics/icCube http://localhost:8282/icCube
ProxyPassReverse /analytics/icCube http://localhost:8282/icCube

meaning www.webapp.com/analytics would be internally forwarded to http://localhost:8282/icCube. Note that the browser will not see this internal forwarding. Everything would appear as if icCube is fully part of the www.webapp.com domain.

File: icCube.xml

You’ll have to change the <filter> configuration for each service. We’re going to use a filter that is passing through the HTTP request to the icCube authentication service.

Note that we’re removing the anonymous login as well (highly recommended for production usage). The same way you can manually remove the ‘anonymous’ role using the icCube/console (icCube/console/admin/Roles) to ensure there is no way to connect as anonymous in icCube.

<uxComponentConfiguration>

	<static>
		<filter>PASSTHROUGH</filter>
	</static>

	<ux-api>
		<filter>PASSTHROUGH</filter>
	</ux-api>

	<api>
		<filter>PASSTHROUGH</filter>
	</api>

</uxComponentConfiguration>

<reportingComponentConfiguration>
	<filter>PASSTHROUGH</filter>
</reportingComponentConfiguration>

<gviComponentConfiguration>
	<filter>PASSTHROUGH</filter>
</gviComponentConfiguration>

<filterConfiguration>
	<filter>
		<filter-name>PASSTHROUGH</filter-name>
		<filter-class>
			crazydev.iccube.server.authentication.passthrough.IcCubePassthroughAuthenticationServletFilter
		</filter-class>
	<init-param>
		<param-name>anonymousLogon</param-name>
		<param-value>false</param-value>
	</init-param>
	</filter>
	
</filterConfiguration>

The authentication service is configured to accept the HTTP headers:

	IC3_USER_NAME
	IC3_ROLE_NAME

The roles have to be defined within icCube. Note the name of the administrator role is: administrator.

<icCubeAuthenticationService>

	<serviceclass> crazydev.iccube.server.authentication.IcCubeHeaderAuthenticationService</service-class>
	
	<param>
		<name>header.user</name>
		<value>IC3_USER_NAME</value>
	</param>
	
	<param>
		<name>header.role</name>
		<value>IC3_ROLE_NAME</value>
	</param>
	
	<param>
		<name>header.role.onTheFly</name>
		<value>false</value>
	</param>
	
</icCubeAuthenticationService>

Configuration: log4j.xml is controlling the logging level/information in the files: /log/icCube.log.

The following two loggers may be set to “debug” for tracing HTTP requests headers/parameters while putting in place the authorization:

<logger name="icCube.authorization">
	<level value="debug"/>
</logger>

<logger name="icCube.http.request">
	<level value="debug"/>
</logger>

Embedding icCube

To check the single sign-on within icCube via the your Web application, you can add an iFrame or DIV within your Web application and setup its source attribute to either the permalink of a report or a report application as following (assuming your webapp is available at www.webapp.com/analytics):

For more information, check our documentation page on embedding and an example on GitHub.

Note that a two-way communication between the customer Web application and icCube can be set up but this is for another article.

Do not hesitate to contact us if you need more information.

By Nathalie Leroy Tapia Heredia