. . .

[Bouncer] Installation


Introduction

With ApiOmat Bouncer, we introduce a service as an identity and access management solution. The service is based on Keycloak and helps you with the integration of third party authentication providers like LDAP, Active Directory and others.
The service provides a central point for authentication. When a user logs in with Bouncer, he obtains a JWT. A JWT is a token that is signed by Bouncer and includes information about the user. The JWT is included in every request as bearer authentication header and can be used to check the authorization within the services.

This page provides the steps to install and configure the Bouncer. For further functional information please refer to Bouncer's Usage documentation.

Overview

If configured correctly, Bouncer integrates nicely with other ApiOmat components.

A Bouncer installation contains different "containers" that are isolated from each other and each manage a set of users, credentials and roles. These containers are called realms.
In the ApiOmat context, there is one realm "Apiomat" and one realm for each App-Backend and system.

images/download/attachments/91591974/Bouncer-Apiomat-Realms.png

This reflects that every App-Backend (and system) has it's own users. ApiOmat will take care of creating and configuring the realm when you create a new App-Backend.

We ship our Bouncer with an extension, which is responsible for handling login requests according to ApiOmat customers, organizations and application users.

Installation

USERNAME, PASSWORD, and TOKEN values are provided per customer from ApiOmat.

Debian/Ubuntu
# Install the repo key
wget -O - https://repo-int.apiomat.com/yambas/rest/web/Key/LIVE/apiomat-archive-keyring.asc | sudo apt-key add -
# Add the repository
echo "deb https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/deb ./" | sudo tee /etc/apt/sources.list.d/apiomat.list
 
# Update APT and install
apt-get update
apt-get install -y aom-bouncer
service bouncer start
Centos/Oracle/RedHat
# Add the repository
echo "[apiomat]
name=ApiOmat
baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/rpm
gpgcheck=0
enabled=1" > /etc/yum.repos.d/apiomat.repo
 
# Install
yum -y --nogpgcheck install aom-bouncer
service bouncer start
Suse
# Add the repository
zypper addrepo --no-gpgcheck https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
 
# Refresh zypper and install
zypper refresh
zypper --no-gpg-checks --non-interactive install aom-bouncer
service bouncer start
Docker Compose
# Docker login
docker login -u <USERNAME> -p <PASSWORD>
 
# Store the following file and execute:
docker-compose -f bouncer.yml up

bouncer.yml:

version: '3'
services:
postgres:
image: postgres
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
POSTGRES_DB: bouncer
POSTGRES_USER: bouncer
POSTGRES_PASSWORD: b0uncer
networks:
- proxy
bouncer:
image: "apiomat/bouncer:<version>"
environment:
CONSUL_ENABLED: "true"
CONSUL_URL: http://consul:8500/
REGISTRY_SERVICE_ID: bouncer
REGISTRY_SERVICE_NAME: bouncer
REGISTRY_SERVICE_HOST: <your-bouncer-hostname>
REGISTRY_SERVICE_PORT: <your-bouncer-port>
REGISTRY_HEALTHCHECK_URL: http://<your-bouncer-hostname>:<your-bouncer-port>/auth/realms/master/health/check
networks:
- proxy
ports:
- 8081:8080
- 9990:9990
- 8787:8787
depends_on:
- postgres
volumes:
- "${PWD}/bouncer-service.yml:/opt/bouncer/configuration/service.yaml"

service.yaml:

server:
# Configuration file for your server which depends on which mod your server runs. Defaults to standalone.xml
# configFile: standalone.xml
# Http port of your server
port: 8080
# Https port of your server
ssl:
port: 8443
# Keystore configuration to store your servers credential
keystore:
# If true (default false) you must configure file, and password for the keystore. If false, keystore will be
# generated on startup with self-signed certificate.
enabled: false
# Name of the keystore. It is /opt/bouncer/configuration/keystore.jks by default.
file: your_keystore.jks
# Password of the keystore
password: keystore password
# Host of your service's key pair in the keystore
keyHost: your hostname
# Password of your service's key pair in the keystore
keyPassword: password of your key
# Alias for the key
keyAlias: keyAlias
# Truststore configuration to store other servers credential
truststore:
# If true (default false) you must configure file, and password for the truststore. If false truststore
# configuration will be ignored, and certificate checking will fall back to JSSE (Java Secure Socket Extension)
# configuration.
enabled: false
# Name of the keystore. It is /opt/bouncer/configuration/truststore.jks by default.
file: your_truststore.jks
# Password of the truststore
password: truststore password
# WILDCARD by default. For HTTPS requests, this verifies the hostname of the server’s certificate.
# "ANY" means that the hostname is not verified.
# "WILDCARD" allows wildcards in subdomain names i.e. *.foo.com.
# "STRICT" means CN must match hostname exactly.
hostnameVerification: WILDCARD
 
# Management Server configuration
management:
port: 9990
ssl:
port: 9993
# AJP configuration
ajp:
port: 8009
# Transaction configuration
txn:
recoveryManager:
port: 4712
statusManager:
port: 4713
# SMTP Server Configuration
smtp:
host: localhost
port: 25
 
# Application configuration
application:
# default themes
theme:
default: easy-theme
welcome: easy-theme
# default admin configuration
admin:
username: admin
password: Pa55w0rd
# database configuration
database:
# accepted driver values are [postgresql, oracle, mysql, mariadb, sqlserver]
# leaving it empty will result in Bouncer using H2 in memory database as default
driver: postgresql
# optional for postgresql
port: 5432
addr: postgres
name: bouncer
user: bouncer
password: b0uncer
# mandatory for postgres and mssql
schema: public
Kubernetes

To obtain the latest manifest file, please contact the EASY ApiOmat support.

Windows
  1. Download file: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/aom-bouncer-<VERSION>.zip?token=<TOKEN> and unzip to installation folder

  2. Ensure that the path to your installed jdk\bin is set to the system-environment variable 'Path' (java.exe needs to be accessible for windows' system user!)

  3. Open administrative console and execute

    Bouncer-<VERSION>.exe install
    Bouncer-<VERSION>.exe start

    to install as service and start afterwards.

    For a removal of the service, execute

    Bouncer-<VERSION>.exe uninstall

Configuration

Bouncer configuration

You can find the fully commented configuration file under /opt/apiomat/bouncer/<bouncerVersion/configuration/service.yaml

You can find the fully commented configuration file under %BOUNCER_INSTALLATION_PATH%\configuration\service.yaml

Besides environment variables, you need to provide a service.yaml that gets mapped into the container, see the Installation section for that.

Environment variables:

Key

Default

Explanation

CONSUL_ENABLED

true

Whether the service should register to Consul. If this option is set to true, Consul must be available on CONSUL_URL.

CONSUL_URL

http://localhost:8500/

Consul URL reachable from Bouncer.

CONSUL_CONNECT_TIMEOUT_MS

10000

Time in ms after which a failing request to Consul will be cancelled.

CONSUL_READ_TIMEOUT_MS

10000

Time in ms after which a failing read request to Consul will be cancelled.

CONSUL_WRITE_TIMEOUT_MS

10000

Time in ms after which a failing write request to Consul will be cancelled.

CONSUL_MAX_RETRY

-1

Retry count when registering to consul is failed. Default is -1 which is infinitely try to register to consul.

CONSUL_RETRY_DELAY_S

30

Delay in seconds between consul registry retries.

REGISTRY_SERVICE_ID

bouncer

Service ID used to register to Consul.

REGISTRY_SERVICE_NAME

bouncer

Service name used to register to Consul.

REGISTRY_SERVICE_HOST

localhost

Bouncer host used to register to Consul.

REGISTRY_SERVICE_PORT

8080

Bouncer port used to register to Consul.

REGISTRY_HEALTHCHECK_URL

http://localhost:8080/auth/realms/master/health/check

Health URL of Bouncer reachable from Consul.

REGISTRY_CHECK_INTERVAL_S

5

Time interval in seconds between each health check from Consul.

REGISTRY_DEREGISTER_S

120

Time in seconds after which a failing service will automatically be deregistered from Consul.

YAMBAS configuration

You need to set the following properties:

  • common.auth.servicename: Name of the service in Consul, defaults to "bouncer"

  • common.auth.url.internal: Used as fallback if Bouncer couldn't be discovered via Consul

  • common.auth.url.public: For the publicly accessible URL of Bouncer

  • common.auth.username: Username of the Bouncer admin (Or a user with the rights to create realms and change their configuration)

  • common.auth.userpass: Password of the admin (or the user)

There are also some optional properties:

  • common.auth.enabled: If set to "false" (default is true), usage of Bouncer will be disabled (e.g. no realms or users will be created). Available since ApiOmat 20.11.1 (YAMBAS 3.6.1) and 21.03.0 (YAMBAS 3.7.0).

  • common.auth.tokenRefresh.delayOnTempError: How long to wait, in seconds, before reattempting to refresh the admin/user's access token if a temporary error (e.g. server is unavailable for a few seconds) occured during the previous refresh attempt (Refreshing is done in the background, to ensure all requests to Bouncer are made with a valid token). Default value is 3. Available since ApiOmat 20.11.1 (YAMBAS 3.6.1) and 21.03.0 (YAMBAS 3.7.0).

  • common.auth.tokenRefresh.delayOnError: Similar to the above, except it is used for all other errors. Default value is 20. Available since ApiOmat 20.11.1 (YAMBAS 3.6.1) and 21.03.0 (YAMBAS 3.7.0).

Dashboard configuration

You may need to set the properties common.auth.servicename (default is "bouncer") and common.auth.url.public (for the publicly accessible URL of Bouncer)

Innkeeper configuration

You need to set the property auth.service.url

Generated services configuration

You need to set the following properties:

apiomat:
service:
discovery:
uses:
Bouncer:
name: bouncer
version: "[1.0,)"
fallbackurl: "https://bouncer/fallback-address/auth"

These properties are used for the authorization checks of the configuration endpoints of your service. You can also use them to discover the Bouncer URL to create the JWTValidator (see the usage in generated services example).

Post installation steps

After all services are set up, configured and started correctly, Yambas will already have created a Realm for "Apiomat". You should be able to see it, if you login to bouncer with the Admin credentials of Bouncer.
To be able to use the Dashboard along with Bouncer, it is necessary to "Connect" it under "Configuration" section when you're logged in with the SuperAdmin.

images/download/attachments/91591974/ConnectDashboardWithBouncer.png

The click on the "Connect" button will internally create the ApiOmat realm within Bouncer (if it did not happen automatically during the start of Yambas) and a "Client" for the Dashboard within the Apiomat Realm.

ApiOmat will take care of creating and configuring the realm, when you create a new App-Backend. If you have an App-Backend that already existed before, you can create the realm afterwards by using the "Connect" button in the "Connect to auth service" section of the App-Backend configuration.

The ability to log in with your ApiOmat account is provided by our extension in Bouncer. The extension is contained in the ApiOmat Bouncer installation packages as well as the docker image.
The extension and it's configuration can be found in the "Apiomat" realm in Bouncer under "User federation" with the ID "yambas-user-storage". You can configure there the necessary aspects, like the MongoDB connection information or the configEncryptionKey of Yambas (which is necessary to validate the account passwords). Generally these values should already be configured correctly after the start of yambas or the click on the "Connect" button with the SuperAdmin, as mentioned above.
By default, the configuration for App-Backend Realms are left empty and therefore the configuration from the Apiomat realm gets used. However, if you want to configure it differently for one AppBackend realm you could do it, even when this is not recommended.

Next Steps

Either install other services or take a look at the Usage Documentation