Configuration

• 1: Reverse-Proxy and TLS/SSL
• 2: Local Authentication
• 3: Basic Authentication
• 4: SAML/OIDC Authentication
• 5: LDAP Authentication
• 6: Forced Authentication

1 - Reverse-Proxy and TLS/SSL

You should setup a TLS/SSL reverse-proxy in front of your Cavaliba docker deployment.

A reverse-proxy would perform the following tasks:

• offload (terminate) HTTPS SSL/TLS user connections and handle certificate configuration and renewal
• filter user source IP addresses if restricted network exposure is needed
• perform HTTP Basic/Digest user authentication if this auth mode is selected for Cavaliba
• produce log and audit-trail
• on large / fault-tolerant setups, perfom user trafic load-balancing accross multiple Cavaliba nodes
• display a Maintenance/Sorry page if it detects that cavalliba stack is down

You may use an enterprise wide / netork managed load-balancer and reverse-proxy. You can also deploy a small NGINX or HA-PROXY component on your Cavaliba host virtual machine.

Node Healthcheck / status

An external reverse-proxy or load-balancer should remove a failed node from its server pool and stop sending user traffic to failed nodes.

Additionally, a monitoring tool should check the availability of services.

Basic healthcheck can be implemented by verifying a simple TCP on http endpoint (TCP can connect). you can also check an HTTP 200 response.

Better, you may implement a deeper healthcheck on the /status/ page and check for an “OK” answer from Cavaliba. This check confirms that the application node is alive and healthy.

curl http://cavaliba/status/
OK

Example : minimal NGINX / Let’s Encrypt SSL/TLS reverse-proxy

Setup

$ sudo apt install nginx apache2-utils certbot python3-certbot-nginx
$ sudo certbot -n --agree-tos --email mycontact@mydomain.com --nginx -d mycavaliba.mydomain.com
$ sudo systemctl enable nginx

Configuration

$ sudo cat /etc/nginx/sites-enabled/default

	upstream cavaliba {
	  keepalive 60;
	  server 127.0.0.1:8000;
	}
	server
	{
	    if ($host = mycavaliba.mydomain.com ) {
	        return 301 https://$host$request_uri;
	    } # managed by Certbot
	    listen 80 default_server;
	    server_name mycavaliba.mydomain.com;
	    return 404; # managed by Certbot
	}
	server
	{
	    server_name mycavaliba.mydomain.com;
	    listen 443 ssl; # managed by Certbot
	    ssl_certificate /etc/letsencrypt/live/mycavaliba.mydomain.com/fullchain.pem; # managed by Certbot
	    ssl_certificate_key /etc/letsencrypt/live/mycavaliba.mydomain.com/privkey.pem; # managed by Certbot
	    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
	    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

	    # -------------
	    location /
	    {
	        proxy_set_header Host $http_host;
	        proxy_set_header X-Forwarded-Host $host;
	        proxy_set_header X-Forwarded-Server $host;
	        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	        #rewrite ^/cavaliba/(.*)$  /$1  break;
	        proxy_pass http://cavaliba;
	        proxy_http_version 1.1;
	        proxy_set_header Connection "";
	    }
	}

2 - Local Authentication

This is the default mode, which is enabled after a fresh install.

This mode is suitable for small deployment with a limited number of users, and little to no need for advanced features such as multi-factor authentication, registration/sign-up forms, password loss/change self-service, etc.

User accounts (login/password) are configured manually and directly inside in Cavaliba by an administrator.

Sign-in/Sign-out Web forms are provided by Cavaliba.

Steps to configure this mode

• connect to Cavaliba with an admin level account
• go to the conf module
• select the user tab.
• select AUTH_MODE = local
• save the configuration

Be sure to remove other authentication mode you may have already configured such as OAUTH SAML/OIDC modes.

How does-it work

In Local Authentication mode, users are authenticated ny the Django App Framework. They must exist in the Django auth structure, which is basically a specific DB table. Login, Password are the sole mandatory attributes for the purpose of authenticating a user.

Then, the user must also in the Cavaliba Data Model, with the same login. This model is common to all authentication modes. It defines who is the user (extended attributes, group membership, directory pages), if and what he can do when logged-in, what notifications he will receive, etc.

Add a user

Manually from Cavaliba :

• open the DB Admin tool from Cavaliba main menu
• select the django user table
• clic the “add user” top-right button and fill-in the form : login, password
• get back to cavaliba
• go to the Cavaliba User module
• add the user (same login) with extended informations, group membership, etc.

CLI / Shell:

 $ cd cavaliba/
 $ docker exec -it cavaliba_app python manage.py shell
  >>> from django.contrib.auth.models import User
  >>> user = User.objects.create_user("john", "lennon@thebeatles.com", "johnpassword")

Suspend / Remove a user

• open the DB Admin tool from Cavaliba main menu
• select the django user table
• select the appropriate user
• edit the form, disable / remove and save

As this point, the user can’t sign-in to cavaliba. But he still exists in the Data Model and can receive notifications (Sirene).

• go to the Cavaliba User module
• select the user (same login) and disable/remove

Change a user’s password

Web interface :

• open the DB Admin tool from Cavaliba main menu
• select the django user table
• select the appropriate user
• use the change password tool

CLI / Shell

 $ cd cavaliba/
 $ docker exec -it cavaliba_app python manage.py changepassword LOGIN

3 - Basic Authentication

Basic Authentication is an external authentication mode. It is not performed by the Cavaliba application itself. A front Web server is in charge of this authentication and will set standard HTTP Authentication headers, passed to Cavaliba.

This mode, like the Local Authentication mode, is suitable for small deployment, with no advanced authentication and access management features. User management is to be performed externally, as well as inside Cavaliba.

Internal Cavaliba Web Server (NGINX)

Basic Authentication can be configured at the Cavaliba container with the NGINX Web server.

Steps:

• edit the nginx.conf file next to the docker-compose.yml, to uncomment basic authentication lines
• create a standard htpassword file (htpasswd)
• edit the docker-compose.yml to uncomment the line mounting this htpassword file inside the nginx containtener
• restart Cavaliba (the cavaliba_nginx container)
• in Cavaliba / Conf, configure AUTH_MODE=Basic
• populate / manage the htpasswd file on the server

You may then edit and update dynamically the htpasswd file, to add or remove users, change their password, etc.

External Web-Server / Reverse-PRoxy

Basic Authentication can also be configured at any upstream Web server / Reverse-Proxy which may be set up before reaching Cavaliba Application.

This Reverse-Proxy must set the HTTP Authentication Header to let Cavaliba obtain the user’s login value.

Cavaliba users

Don’t forget to always map external users (in the htpasswd), to users objects in the Cavaliba User model with the same login value.

4 - SAML/OIDC Authentication

SAML/OIDC Authentication is an external authentication mode. It is called OAUTH2 in Cavaliba.

It is performed by a companion component, namely oauth2_proxy, which is included in Cavaliba as an additional container, ready to be started and configured.

This model is suitable for modern/large scale deployment. It offloads all the access / authentication process to an external Authentication server (IdP, Identity Provider). It may provide Multi-factor strong authentication, and many user self-service to manage their account and credentials depending on the IDP.

Identity Providers are external services such as Keycloak, OKTA, Microsoft Azure AD and numerous other providers.

steps to configure

Identity Provider

• Register your Cavaliba deployement to your IDP (identity provider)

Docker .env file

• Configure the .env docker file with the received registration parameters (client id, secret, URLs)

Oauth2 Proxy configuration

• configure/adapt the oa2p_xxx.cfg to match the SAML/OIDC requirements of your Identity Provider

Start the Docker OAUTH2 component

• uncomment the oauth2_proxy block in the docker-compose.yml file
• start the cavaliba_oa2p container

Configure NGINX to catch/redirect authentication to oauth2

• uncomment the nginx.conf directives to enable the oauth2 authentication workflow
• restart the cavaliba nginx container

Inform Cavaliba to use OAUTH2

• in Cavaliba/Conf, select AUTH_MODE=oauth2

Setup a local Keycloak IDP

TBD - start a local Keycloak container, configure User directory, authentication workflows. Register Cavaliba as a a new Service Provider for this IDP.

Bonus : LDAP Authentication

LDAP authentication is a mean to authenticate users against a central Directory like Openldap, Lemonldap or Active Directory.

Although not immediately available in Cavaliba it can be set up with the OAUTH2 mode requesting a local Identity Provider (like Keycloak) which in turn, queries an LDAP Directory.

5 - LDAP Authentication

Cavaliba doesn’t provide out of the box LDAP authentication.

See SAML/OIDC for indirect LDAP Authentication through an ODIC/SAML local Identity Provider such as Keycloak.

6 - Forced Authentication

Forced authentication means no authentication. No authentication is performed and all connections are mapped to a single internal Cavaliba user. It is indented for developpment purpose, or Robinson Crusoe on a desert island.

Don’t use in production, or even in QUA / Tests, on a shared network.