Server Installation and Configuration Guide

These are the requirements to run the Aerobase authentication server:

Please see the Installing Distribution Files section of this guide for more information.

This chapter walks you through the directory structure of the server distribution.

Let’s examine the purpose of some of the directories:

Standalone operating mode is only useful when you want to run one, and only one Aerobase server instance. It is not usable for clustered deployments and all caches are non-distributed and local-only. It is not recommended that you use standalone mode in production as you will have a single point of failure. If your standalone mode server goes down, users will not be able to log in. This mode is really only useful to test drive and play with the features of Aerobase

Clustered operation mode is for when you want to run Aerobase within a cluster. This mode requires that you have a copy of the Aerobase distribution on each machine you want to run a server instance. This mode is very easy to deploy, and require a few configuration cahnge.

Due to variations in data types and SQL syntax, the following databases are currently supported out of the box. Additional databases as well as enhancements to support new databases are available through Aerobase support site.

This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation.

By default Aerobase reconfigure process will generate SQL Users/Schema/Tables required for runtime. If required object is already exists in database, it will be skiped. Therefore it is safe to run reconfigure command multiple times.

Database schema in Aerobase only accounts for Unicode strings in the following special fields:

Otherwise, characters are limited to those contained in database encoding which is often 8-bit. However, for some database systems, it is possible to enable UTF-8 encoding of Unicode characters and use full Unicode character set in all text fields. Often, this is counterbalanced by shorter maximum length of the strings than in case of 8-bit encodings.

Some of the databases require special settings to database and/or JDBC driver to be able to handle Unicode characters. Please find the settings for your database below. Note that if a database is listed here, it can still work properly provided it handles UTF-8 encoding properly both on the level of database and JDBC driver.

Technically, the key criterion for Unicode support for all fields is whether the database allows setting of Unicode character set for VARCHAR and CHAR fields. If yes, there is a high chance that Unicode will be plausible, usually at the expense of field length. If it only supports Unicode in NVARCHAR and NCHAR fields, Unicode support for all text fields is unlikely as Keycloak schema uses VARCHAR and CHAR fields extensively.

The Nginx config will tell browsers and clients to only communicate with your Aerobase instance over a secure connection for the next 24 months. By enabling HTTPS you’ll need to provide a secure connection to your instance for at least the next 24 months. By default, Aerobase does not use HTTPS. If you want to enable HTTPS for aerobase.example.com, add the following statement to /etc/aerobase/aerobase.rb:

Because the hostname in our example is 'aerobase.example.com', aerobase will look for key and certificate files called /etc/aerobase/ssl/aerobase.example.com.key and /etc/aerobase/ssl/aerobase.example.com.crt respectively. Create the /etc/aerobase/ssl directory and copy your key and certificate there.

For self-signed certificate, we can create the SSL key and certificate files in one motion by typing:

By default, when you specify an external_url starting with 'https', Nginx will no longer listen for unencrypted HTTP traffic on port 80. If you want to redirect all HTTP traffic to HTTPS you can use the redirect_http_to_https setting.

If you need to use an HTTPS port other than the default (443), just specify it as part of the external_url.

In order for Aerobase to properly validete oauth requests it needs to know the URL under which it is reached by your users, e.g. http://idp.aerobase.com. Add or edit the following line in /etc/aerobase/aerobase.rb:

Aerobase service names can be labled with your company name, Add or edit the following line in C:\Aerobase\Configuration\aerobase.rb

Aerobase packages loads all configuration from /etc/aerobase/aerobase.rb file. This file has strict file permissions and is owned by the root user. The reason for strict permissions and ownership is that /etc/aerobase/aerobase.rb is being executed as Ruby code by the root user during aerobase-ctl reconfigure. This means that users who have write access to /etc/aerobase/aerobase.rb can add configuration that will be executed as code by root.

You can include an external configuration file overrides.rb inside /etc/aerobase/. Any configuration that is set in /etc/aerobase/overrides.rb will take precedence over the configuration from the included aerobase.rb file.

Place your custom realm.json file under /etc/aerobase/

In order for Aerobase to load custom realm it needs to know the PATH under which it is located, e.g. /etc/aerobase/your-realm.json. Add or edit the following line in /etc/aerobase/aerobase.rb:

Add or edit the following line in /etc/aerobase/aerobase.rb:

The recommended network architecture for deploying Aerobase is to set up an HTTP/HTTPS load balancer on a public IP address that routes requests to Aerobase servers sitting on a private network. This isolates all clustering connections and provides a nice means of protecting the servers.

This section discusses a number of things you need to configure before you can put a reverse proxy or load balancer in front of your clustered Aerobase deployment. It also covers configuring the built in load balancer that was Clustered Domain Example.

Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more Aerobase servers on private network. For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same Aerobase backend node.

The reason is, that Aerobase is using Infinispan distributed cache under the covers for save data related to current authentication session and user session. The Infinispan distributed caches are configured with one owner by default. That means that particular session is saved just on one cluster node and the other nodes need to lookup the session remotely if they want to access it.

For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity.

It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend Aerobase nodes can be like this:

From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .

The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to sticky over the AUTH_SESSION_ID cookie. How exactly do this is dependent on your loadbalancer.

When cluster nodes are isolated on a private network it requires access to the private network to be able to join a cluster or to view communication in the cluster. In addition you can also enable authentication and encryption for cluster communication. As long as your private network is secure it is not necessary to enable authentication and encryption. Aerobase does not send very sensitive information on the cluster in either case.

Aerobase cluster nodes are allowed to boot concurrently. When Aerobase server instance boots up it may do some database migration, importing, or first time initializations. A DB lock is used to prevent start actions from conflicting with one another when cluster nodes boot up concurrently.

By default, the maximum timeout for this lock is 900 seconds. If a node is waiting on this lock for more than the timeout it will fail to boot. Typically you won’t need to increase/decrease the default value, but just in case it’s possible to configure it in /etc/aerobase/aerobase.rb

There are multiple different caches configured for Aerobase. There is a realm cache that holds information about secured applications, general security data, and configuration options. There is also a user cache that contains user metadata. Both caches default to a maximum of 10000 entries and use a least recently used eviction strategy. Each of them is also tied to an object revisions cache that controls eviction in a clustered setup. This cache is created implicitly and has twice the configured size. The same applies for the authorization cache, which holds the authorization data. The keys cache holds data about external keys and does not need to have dedicated revisions cache. Rather it has expiration explicitly declared on it, so the keys are periodically expired and forced to be periodically downloaded from external clients or identity providers.

The eviction policy and max entries for these caches can be configured in the /etc/aerobase/aerobase.rb.

In addition, there are also separate caches sessions, clientSessions, offlineSessions, offlineClientSessions, loginFailures and actionTokens. These caches are distributed in cluster environment and they are unbounded in size by default. If they are bounded, it would then be possible that some sessions will be lost. Expired sessions are cleared internally by Aerobase itself to avoid growing the size of these caches without limit. If you see memory issues due to a large number of sessions, you can try to:

There is an additional replicated cache, work, which is mostly used to send messages among cluster nodes; it is also unbounded by default. However, this cache should not cause any memory issues as entries in this cache are very short-lived.

There are caches like sessions, authenticationSessions, offlineSessions, loginFailures and a few others (See Eviction and Expiration for more details), which are configured as distributed caches when using a clustered setup. Entries are not replicated to every single node, but instead one or more nodes is chosen as an owner of that data. If a node is not the owner of a specific cache entry it queries the cluster to obtain it. What this means for failover is that if all the nodes that own a piece of data go down, that data is lost forever. By default, Aerobase only specifies one owner for data. So if that one node goes down that data is lost. This usually means that users will be logged out and will have to login again.

You can change the number of nodes that replicate a piece of data by change the cache_owners attribute in the /etc/aerobase/aerobase.rb declaration.

Here we’ve changed it so at least two nodes will replicate one specific user login session.

To clear the realm or user cache, go to the Aerobase admin console Realm Settings→Cache Config page. On this page you can clear the realm cache, the user cache or cache of external public keys.