Authentication in Gawati


Authentication in Gawati is handled by a separate component service called KeyCloak. Keycloak is a solution for Identity Management (IDM) and Single Sign On (SSO); See KeyCloak .

Keycloak has the following components:
  • Keycloak server – an authentication server to store the user information and used to get the access token.
  • Keycloak adapter – It is a componenet which help us to integrate keycloak in the existing application.

It needs to be installed and integrated to work with Gawati. For an overview of how KeyCloak works in Gawati, see How Trust & Security Works in Gawati

Installing & Configuring KeyCloak for Production


The following instructions deploy keycloak behind an Apache reverse proxy and SSL.

  1. Download KeyCloak 3.4.3 Final and unzip into the /opt folder. (We are assuming these commands are run as root)

    cd /opt
  2. Add a user for keycloak called keycloak, and change the ownership of the unzipped files to this user.

    sudo chown keycloak: -R keycloak-3.4.3.Final
  3. Add a keycloak admin to /opt/keycloak-3.4.3.Final/standalone/configuration/keycloak-add-user.json.

    # run this in /opt/keycloak-3.4.3.Final if you are not already there
    # run ``su keycloak`` to run this as the ``keycloak`` user
    ./bin/ --user admin --password <set an appropriate password> --realm master
  4. Modify standalone/configuration/standalone.xml to enable proxying to Keycloak:

    Run these 3 commands as the keycloak user:

    # enable proxy forwarding, we need to forward traffic from port 8443 the secure port of keycloak to port 443 on Apache
    ./bin/ 'embed-server,/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=proxy-address-forwarding,value=true)'
    # add the redirect-socket attribute to enable https proxy forwarding
    ./bin/ 'embed-server,/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=redirect-socket,value=proxy-https)'
    # enable forwarding to port 443
    ./bin/ 'embed-server,/socket-binding-group=standard-sockets/socket-binding=proxy-https:add(port=443)'
  5. Add a service startup config keycloak.service for systemd to start keycloak as a service:

    ExecStart=/opt/keycloak-3.4.3.Final/bin/ -b

    Now enable the service:

    systemctl daemon-reload
    systemctl start keycloak.service

    Now check if the service is running:

    systemctl status keycloak.service
  6. Now add the appropriate configuration to apache.

    <IfModule mod_ssl.c>
    <VirtualHost *:443>
        ProxyRequests off
        ErrorLog ${APACHE_LOG_DIR}/error_auth.log
        CustomLog ${APACHE_LOG_DIR}/access_auth.log combined
        ProxyPreserveHost On
        ProxyPass / http://localhost:8080/
        ProxyPassReverse / http://localhost:8080/
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Forwarded-Port "443"
        SSLCertificateFile /etc/letsencrypt/live/
        SSLCertificateKeyFile /etc/letsencrypt/live/
        Include /etc/letsencrypt/options-ssl-apache.conf


If you only wish to install and test the system, See Setup. Here we created the SSL Certificates using letsencrypt. Instructions for setting up signed SSL Certificates can be found here:

Installing the Gawati Theme

KeyCloak is themed independently of Gawati.

  1. Download the `gawati keycloak theme <>`_images

  2. Go to the themes folder, and extract the gawati theme into a folder called gawati.

  3. Navigate to standalone/configuration/standalone.xml and add, a <welcomeTheme> with the value gawati.

    .. note::
          You can set ``cacheThemes`` and ``cacheTemplates`` to ``false`` for development purposes
  4. Change the Display Name and the HTML Display Name

Installing & Configuring KeyCloak for Development


  1. Java 8 JDK
  2. zip or gzip and tar
  3. At least 512M of RAM
  4. At least 1 GB of diskspace

Installation Steps

  1. Install the Java 8 JDK

  2. Visit and download KeyCloak 3.4.3 Final.

  3. Unzip this and navigate to the bin directory.


    To prevent KeyCloak from hanging due to lack of available entropy, change the jvm to use urandom instead of random:

    • Open the $JAVA_HOME/jre/lib/security/ file in a text editor.
    • Change the line:
      • Change the entry securerandom.source=file:/dev/random to read:
      • securerandom.source=file:/dev/urandom ; Save your change and exit the text editor.
  4. Run (or in windows standalone.bat). By default it starts on port 8080. You should change the default port as it clashes with the default ports of eXist-db. You will need to do that in standalone/configuration/standalone.xml.

    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="http" port="${jboss.http.port:11080}"/>
        <socket-binding name="https" port="${jboss.https.port:11443}"/>
  5. Restart the service and visit the link : http://localhost:11080

  6. Click on the administration console. Login with the admin and admin.

  7. Clone

  8. Generate a new development realm using the command:

    cd gawati-keycloak-scripts
    npm install
    node index.js --new_realm_name=auth.gawati.local --input_realm=model_realm/model-realm.json --output_file=auth.gawati.local.json
  9. Switch back to the administration console of KeyCloak in the browser

  10. Create a dev realm by importing configuration from auth.gawati.local.json generated above.

    Add Realm

Configuring Single Sign-on across different applications

In Gawati single-sign-on (SSO) is provided via KeyCloak.

Functionally it works in the following way – you login into an application (e.g. the Portal), and that automatically logs you into other Applications which have been configured for SSO like the Profiles application.

The setup for such SSO aware applications is very easy.

  1. You just need to make use of the same KeyCloak JSON configuration file to initialize their authentication environments.

  2. You need to configure the client setup in KeyCloak associated with the KeyCloak JSON file to recognize multiple redirect urls. For example, if your portal is being served on and your profiles application is on , you need to initialize both with the same KeyCloak file, and set* and* as valid redirect URIs in KeyCloak. In the figure below, is an example where redirect URIs have been set to http://localhost:3000 & http://locahost:3001 and Web Origins has been set to +. This kind of setup allows you to login to locahost:3000 and move on to locahost:3001 as if you had already authenticated on it.

    Multiple Redirect URIs

A note on access tokens

KeyCloak uses 2 tokens - one on the client-side and one on the server side. The client side periodically requests the server to update its server-side token. The validity of the server-side token is recommended to be 15 minutes and should be set as below, in Realm Settings->Token.

Access Token Lifespan