Server Developer Guide

Obtain access token for user in the realm aerobase with username admin and password password:

The result will be a JSON document. To invoke the API you need to extract the value of the access_token property. You can then invoke the API by including the value in the Authorization header of requests to the API.

The following example shows how to get the details of the aerobase realm:

A theme can provide one or more types to customize different aspects of Aerobase. The types available are:

All theme types, except welcome, are configured through the Admin Console. To change the theme used for a realm open the Admin Console, select your realm from the drop-down box in the top left corner. Under Realm Settings click Themes.

Aerobase comes bundled with default themes in the server’s root themes directory. To simplify upgrading you should not edit the bundled themes directly. Instead create your own theme that extends one of the bundled themes.

A theme consists of:

Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the Aerobase theme, but you could also consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and message bundles, while the Aerobase theme primarily contains images and stylesheets.

When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release.

While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources directly from the themes directory without restarting Aerobase. Please see the Disable theme caching section of this guide for more information

To create a new theme start by creating a new directory in the themes directory. The name of the directory becomes the name of the theme. For example to create a theme called mytheme create the directory themes/mytheme.

Inside the theme directory create a directory for each of the types your theme is going to provide. For example to add the login type to the mytheme theme create the directory themes/mytheme/login.

For each type create a file theme.properties which allows setting some configuration for the theme. For example to configure the theme themes/mytheme/login that we just created to extend the base theme and import some common resources create the file themes/mytheme/login/theme.properties with following contents:

You have now created a theme with support for the login type. To check that it works open the admin console. Select your realm and click on Themes. For Login Theme select mytheme and click Save. Then open the login page for the realm.

You can do this either by login through your application or by opening the Account Management console (/realms/{realm name}/account).

To see the effect of changing the parent theme, set parent=aerobase in theme.properties and refresh the login page.

Themes can be deployed to Aerobase by copying the theme directory to themes or it can be deployed as an archive. During development you can copy the theme to the themes directory, but in production you may want to consider using an archive. An archive makes it simpler to have a versioned copy of the theme, especially when you have multiple instances of Aerobase for example with clustering.

To deploy a theme as an archive you need to create a JAR archive with the theme resources.

For example for the mytheme theme create mytheme.jar with the contents:

The contents of .json in this case would be:

A single archive can contain multiple themes and each theme can support one or more types.

To deploy the archive to Aerobase simply drop it into the standalone/deployments/ directory of Aerobase and it will be automatically loaded.

By default the theme configured for the realm is used, with the exception of clients being able to override the login theme. This behavior can be changed through the Theme Selector SPI.

This could be used to select different themes for desktop and mobile devices by looking at the user agent header, for example.

To create a custom theme selector you need to implement ThemeSelectorProviderFactory and ThemeSelectorProvider.

Follow the steps in Service Provider Interfaces for more details on how to create and deploy a custom provider.

When implementing custom providers in Aerobase there may often be a need to add additional templates and resources.

The easiest way to load additional theme resources is to create a JAR with templates in theme-resources/templates and resources in theme-resources/resources and drop it into the standalone/deployments/ directory of Aerobase.

If you want a more flexible way to load templates and resources that can be achieved through the ThemeResourceSPI. By implementing ThemeResourceProviderFactory and ThemeResourceProvider you can decide exactly how to load templates and resources.

By default, the locale is selected using the DefaultLocaleSelectorProvider which implements the LocaleSelectorProvider interface. English is the default language when internationalization is disabled. With internationalization enabled, the locale is resolved in the following priority:

This behaviour can be changed through the LocaleSelectorSPI by implementing the LocaleSelectorProvider and LocaleSelectorProviderFactory.

The LocaleSelectorProvider interface has a single method, resolveLocale, which must return a locale given a RealmModel and a nullable UserModel.

Custom implementations can extend the DefaultLocaleSelectorProvider in order to reuse parts of the default behaviour. For example to ignore the Accept-Language request header, a custom implementation could extend the default provider, override it’s getAcceptLanguageHeaderLocale, and return a null value. As a result the locale selection will fall back on the realms’s default language.

To be able to enter custom attributes in the registration page copy the template themes/base/login/register.ftl to the login type of your custom theme. Then open the copy in an editor.

As an example to add a mobile number to the registration page add the following snippet to the form:

Ensure the name of the input html element starts with user.attributes.. In the example above, the attribute will be stored by Aerobase with the name mobile.

To see the changes make sure your realm is using your custom theme for the login theme and open the registration page.

To be able to manage custom attributes in the user profile page in the account management console copy the template themes/base/account/account.ftl to the account type of your custom theme. Then open the copy in an editor.

As an example to add a mobile number to the account page add the following snippet to the form:

Ensure the name of the input html element starts with user.attributes..

To see the changes make sure your realm is using your custom theme for the account theme and open the user profile page in the account management console.

Aerobase allows you to store tokens and responses from the authentication process with the external IDP. For that, you can use the Store Token configuration option on the IDP’s settings page.

Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP. For example, an application might want to use the Google token to invoke on other Google services and REST APIs. To retrieve a token for a particular identity provider you need to send a request as follows:

An application must have authenticated with Aerobase and have received an access token. This access token will need to have the broker client-level role read-token set. This means that the user must have a role mapping for this role and the client application must have that role within its scope. In this case, given that you are accessing a protected service in Aerobase, you need to send the access token issued by Aerobase during the user authentication. In the broker configuration page you can automatically assign this role to newly imported users by turning on the Stored Tokens Readable switch.

These external tokens can be re-established by either logging in again through the provider, or using the client initiated account linking API.

Some applications want to integrate with social providers like Facebook, but do not want to provide an option to login via these social providers. Aerobase offers a browser-based API that applications can use to link an existing user account to a specific external IDP. This is called client-initiated account linking. Account linking can only be initiated by OIDC applications.

The way it works is that the application forwards the user’s browser to a URL on the Aerobase server requesting that it wants to link the user’s account to a specific external provider (i.e. Facebook). The server initiates a login with the external provider. The browser logs in at the external provider and is redirected back to the server. The server establishes the link and redirects back to the application with a confirmation.

There are some preconditions that must be met by the client application before it can initiate this protocol:

To initiate the login, the application must fabricate a URL and redirect the user’s browser to this URL. The URL looks like this:

Here’s a description of each path and query param:

Why is this hash included? We do this so that the auth server is guaranteed to know that the client application initiated the request and no other rogue app just randomly asked for a user account to be linked to a specific provider. The auth server will first check to see if the user is logged in by checking the SSO cookie set at login. It will then try to regenerate the hash based on the current login and match it up to the hash sent by the application.

After the account has been linked, the auth server will redirect back to the redirect_uri. If there is a problem servicing the link request, the auth server may or may not redirect back to the redirect_uri. The browser may just end up at an error page instead of being redirected back to the application. If there is an error condition and the auth server deems it safe enough to redirect back to the client app, an additional error query parameter will be appended to the redirect_uri.

This is a very powerful extension, which allows you to deploy your own REST endpoints to the Aerobase server. It enables all kinds of extensions, for example the possibility to trigger functionality on the Aerobase server, which is not available through the default set of built-in Aerobase REST endpoints.

To add a custom REST endpoint, you need to implement the RealmResourceProviderFactory and RealmResourceProvider interfaces. RealmResourceProvider has one important method:

which allows you to return an object, which acts as a JAX-RS Resource. For more details, see the Javadoc and our examples. There is a very simple example in the example distribution in providers/rest and there is a more advanced example in providers/domain-extension, which shows how to add an authenticated REST endpoint and other functionalities like Extending datamodel with your own JPA entities.

If the Aerobase data model does not exactly match your desired solution, or if you want to add some core functionality to Aerobase, or when you have your own REST endpoint, you might want to extend the Aerobase data model. We enable you to add your own JPA entities to the Aerobase JPA EntityManager .

To add your own JPA entities, you need to implement JpaEntityProviderFactory and JpaEntityProvider. The JpaEntityProvider allows you to return a list of your custom JPA entities and provide the location and id of the Liquibase changelog. An example implementation can look like this:

In the example above, we added a single JPA entity represented by class Company. In the code of your REST endpoint, you can then use something like this to retrieve EntityManager and call DB operations on it.

The methods getChangelogLocation and getFactoryId are important to support automatic updating of your entities by Liquibase. Liquibase is a framework for updating the database schema, which Aerobase internally uses to create the DB schema and update the DB schema among versions. You may need to use it as well and create a changelog for your entities. Note that versioning of your own Liquibase changelog is independent of Aerobase versions. In other words, when you update to a new Aerobase version, you are not forced to update your schema at the same time. And vice versa, you can update your schema even without updating the Aerobase version. The Liquibase update is always done at the server startup, so to trigger a DB update of your schema, you just need to add the new changeset to your Liquibase changelog file (in the example above it’s the file META-INF/example-changelog.xml which must be packed in same JAR as the JPA entities and ExampleJpaEntityProvider) and then restart server. The DB schema will be automatically updated at startup.

For more details, take a look at the example distribution at example providers/domain-extension, which shows the ExampleJpaEntityProvider and example-changelog.xml described above.