Keycloak Authentication

Starting with v6.8.7, icCube can authenticate users, in an embedded context, against a Keycloak server using both the OpenID Connect and SAML protocols. For an embedded setup we do not advise using this authentication but use a header based authentication instead. Note that technical support for Keycloak is not provided by icCube.

OpenID Connect

Ensure you have the following filters in the icCube.xml filterConfiguration. You'll have to configure the path to your own keycloak.json file.

<filter>
    <filter-name>Keycloak OIDc</filter-name>
    <filter-class>crazydev.iccube.server.authentication.keycloak.oidc.KeycloakOpenIDcFilter</filter-class>
    <init-param>
        <param-name>keycloak.config.file</param-name>
        <param-value>.../keycloak.json</param-value>
    </init-param>
</filter>

<filter>
    <filter-name>Passthrough</filter-name>
    <filter-class>crazydev.iccube.server.authentication.passthrough.IcCubePassthroughAuthenticationServletFilter</filter-class>
</filter>
    

Then setup the following authentication service. You can assign a default locale for the users.

<service-class>crazydev.iccube.server.authentication.keycloak.oidc.KeycloakOpenIDcAuthenticationService</service-class>

<param>
    <name>ic3.default.locale</name>
    <value>fr</value>
</param>
    

Then setup the different entry points to use the right filters:

<uxComponentConfiguration>

    <static>

        ...

        <filter>Keycloak OIDc</filter>
        <filter>Passthrough</filter>

    </static>

    <ux-api>

        ...
        
        <filter>Keycloak OIDc</filter>
        <filter>Passthrough</filter>

    </ux-api>
    
    ...
    
</uxComponentConfiguration>
        
<reportingComponentConfiguration>
    
    ...
    
    <filter>Keycloak OIDc</filter>
    <filter>Passthrough</filter>
    
</reportingComponentConfiguration>
        
<gviComponentConfiguration>
    
    ...
    
    <filter>Keycloak OIDc</filter>
    <filter>Passthrough</filter>
    <filter>GVI Authentication (logout)</filter>

</gviComponentConfiguration>
    

SAML

Ensure you have the following filters in the icCube.xml filterConfiguration. You'll have to configure the path to your own keycloak-saml.xml file.

<filter>
    <filter-name>Keycloak SAML</filter-name>
    <filter-class>crazydev.iccube.server.authentication.keycloak.saml.KeycloakSamlFilter</filter-class>
    <init-param>
        <param-name>keycloak.config.file</param-name>
        <param-value>.../keycloak-saml.xml</param-value>
    </init-param>
</filter>

<filter>
    <filter-name>Passthrough</filter-name>
    <filter-class>crazydev.iccube.server.authentication.passthrough.IcCubePassthroughAuthenticationServletFilter</filter-class>
</filter>
    

Then setup the following authentication service. You can assign a default locale for the users.

<service-class>crazydev.iccube.server.authentication.keycloak.saml.KeycloakSamlAuthenticationService</service-class>

<param>
    <name>ic3.default.locale</name>
    <value>fr</value>
</param>
    

Then setup the different entry points to use the right filters:

<uxComponentConfiguration>

    <static>

        ...

        <filter>Keycloak SAML</filter>
        <filter>Passthrough</filter>

    </static>

    <ux-api>

        ...

        <filter>Keycloak SAML</filter>
        <filter>Passthrough</filter>

    </ux-api>

    ...

</uxComponentConfiguration>

<reportingComponentConfiguration>

    ...

    <filter>Keycloak SAML</filter>
    <filter>Passthrough</filter>

</reportingComponentConfiguration>

<gviComponentConfiguration>

    ...

    <filter>Keycloak SAML</filter>
    <filter>Passthrough</filter>
    <filter>GVI Authentication (logout)</filter>

</gviComponentConfiguration>
    

GWT / Rest API

Note that the Web interface of the server administration (aka. GWT) is not supported (this interface is deprecated). So please login first using the new administration console (aka. UX) and then open a tab for the GWT interface. Contact us if the new administration console is not activated in your version.

The latest Rest API does not support yet Keycloak authentication. Please contact for more information.

Keycloak Server Configuration

When authenticating a user against your Keycloak server icCube is going to retrieve the user's locale and icCube role name. As of now, the role has to be defined in icCube. Please contact us if you'd like to support on-the-fly role description.

User's Locale

The user's locale is retrieved using the Keycloak user's attribute name: ic3_locale. So you'll have to add this attribute in the Keycloak user definition and then add a "User Attribute" protocol mapper mapping that attribute into the "Token Claim": ic3_locale. If not present icCube attempts to use the IDToken.getLocale() and is no locale has been found the default locale of the authentication service is being used.

User's Name (SAML only)

Please add a "User Property" protocol mapper mapping the property "UserName" into the "Friendly Name" ic3_name.

User's Role

icCube is retrieving the role name by filtering the list of user's roles and use the only one starting with IC3_. The actual name of the role is the Keyclaok name minus the prefix IC3_. IC3_Admin is a special role giving administrator privilege to the user.

[Keycloak] IC3_Admin         => [icCube] administrator
[Keycloak] IC3_Standard User => [icCube] Standard User
    

Support

Should you have any question please do not hesitate to contact our support or contact us via our Web site.

Next chapter : describes Azure AD B2C authentication.