Technical Guide

Technical Requirements

Architecture

The application consists of one frontend and two backend services.

A redis service is also required for coordinating asynchronous handling of data.

Each backend service requires a corresponding database (postgres).

Ingress may be provided using the supplied nginx service.

All services are supplied as Docker images.

Deployment

avodaq provides the MAC Manager App as a series of Docker images.

All the Docker images are hosted on our private registry (URL: https://avodaq.azurecr.io).

avodaq can provide a sample Docker Compose configuration file on request.

Installation Requirements

Server (e.g. VM) sizing:

These values are sufficient for a test installation and should be revisited in a production environment.

• 2 CPUs
• 8 GB RAM
• min. 40 GB diskspace
• current Ubuntu LTE version

Network:

• Server requires network access to the ISE API

  • Port: 443
  • Source: IMM server
  • Destination: ISE

• Server requires network access to AD (if AD user import desired)

  • Ports: 389, 636 (assuming standard LDAP and LDAPS ports)
  • Source: IMM server
  • Destination: AD

• End users require desktop browser access to the server

  • Ports: 80, 443
  • Source: Wherever the end users are
  • Destination: IMM server

• Server requires internet access to our private image registry

  • Port: 443
  • Source: IMM server
  • Destination: avodaq.azurecr.io

• Creation of (local) DNS entries as desired

Users and certificates:

• TLS/SSL certificate(s) for the included web server (nginx)
• ISE ERS Admin User (to perform ISE API operations - see Cisco documentation for further details)
  • TLS/SSL full chain certificate for ISE server (to allow certificate verification)
• AD User for Active Directory functionality (if desired)
  • TLS/SSL full chain certificate for Active Directory server (to allow certificate verification)

Installation

Pre-Flight

Confirm that the server required to host the app is available and has the required hardware resources.

Confirm that all network configuration steps have been fulfilled as detailed above.

Confirm that users and certificates are available as detailed above.

Install Docker and Docker Compose

Follow these Docker instructions.

(Optional but recommended): Create a “service” user for performing all subsequent docker commands.

sudo useradd -m <new_user> [--no-user-group]

sudo passwd <new_user>

This user should be added to the “docker” group as described in these Docker instructions.

sudo usermod -aG docker <new_user>

sudo usermod -s /bin/bash <new_user>

Folder and File Setup

Decide where to install IMM (e.g. /home/<new_user>/avodaq-imm or /opt/avodaq-imm) and set up the recommended folder and file structure.

The easiest method is to unpack the provided zip file in the destination folder of your choice.

Download Docker Images

Note: If a proxy is required for internet access, please refer to the docker instructions here

Log in to our private registry. Username and password will be provided by avodaq.

docker login avodaq.azurecr.io

Download images.

docker compose up --no-start

Generate Secret Key and Database Passwords

Create a secret key using your preferred method (e.g. openssl rand -hex 32).

Generate passwords for each respective database using your preferred password manager (tip: avoid special characters).

Set Environment Variables

Rename all .env.example files to .env.

Docker Compose Enviroment

In the file ./.env

• set DOCKERDIR to the full path of the installation directory, e.g.

DOCKERDIR="/opt/avodaq-imm"

Management Service

In the file ./fastapi/management_ms/.env

• set SECRET_KEY to the secret key value generated above.
• set ORIGINS_STRING to the IP address(es) and/or URL(s) via which the application will be accessed
• in DB_CONNECTION_STRING replace <MANAGEMENT_DB_PASSWORD> with the password generated above
• If the provided Docker Compose files are used, ISE_API_BASE_URL need not be changed. It must point to the ISE microservice.

In the file ./fastapi/management_ms/database/.env

• in POSTGRES_PASSWORD replace <MANAGEMENT_DB_PASSWORD> with the password generated above

ISE Service

In the file ./fastapi/ise_ms/.env

• set ENCRYPTION_KEY to the secret key value generated above.
• in DB_CONNECTION_STRING replace <ISE_DB_PASSWORD> with the password generated above
• set ORIGINS_STRING to the IP address(es) and/or URL(s) via which the application will be accessed
• If the provided Docker compose files are used, REDIS_URI and MANAGEMENT_MICROSERVICE_URL need not be changed. They must point to the Redis and Management microservice respectively.

In the file ./fastapi/ise_ms/database/.env

• in POSTGRES_PASSWORD replace <ISE_DB_PASSWORD> with the password generated above

Frontend Service

In the file ./nodejs/.env

• set AVODAQ_API_URL_MAC_ISE to the base URL of the application
• set AVODAQ_API_URL_MAC_USER to the base URL of the application

Install TLS/SSL Certificates for Web Server (Optional)

Motivation: Access the IMM app in the browser without warnings regarding TLS/SSL encryption.

Copy your certificate files to the folder ./nginx/certs, for example:

./nginx/certs/certificate.crt

./nginx/certs/certificate.key

Uncomment or add the following lines in the docker-compose.yml file:

volumes:
  - $DOCKERDIR/nginx/certs/certificate.crt:/etc/nginx/certs/certificate.crt
  - $DOCKERDIR/nginx/certs/certificate.key:/etc/nginx/certs/certificate.key

Install Certificate File for Active Directory LDAP (Optional)

Motivation: Verify the certificate provided by Active Directory during LDAP communication.

Assuming that your on-premises Active Directory is using a certificate from an internal CA, the IMM app requires the full-chain Root CA certificate in order to verify the certificate presented by the Active Directory.

Copy your certificate file to the folder ./fastapi/management_ms/certificates/ldap/, for example:

./fastapi/management_ms/certificates/ldap/certificate.pem

Uncomment or add the following line in the docker-compose.yml file:

- $DOCKERDIR/fastapi/management_ms/certificates/ldap/certificate.pem:/website/app/certificates/ldap/certificate.pem

Install Certificate File for the Cisco ISE Server (Optional)

Motivation: Verify the certificate provided by the ISE server during API communication

The IMM app requires the full-chain Root CA certificate in order to verify the certificate presented by the Cisco ISE.

Copy your certificate file to the folder ./fastapi/ise_ms/certificates/ise/, for example:

./fastapi/ise_ms/certificates/ise/certificate.pem

Uncomment or add the following line in the docker-compose.yml file:

- $DOCKERDIR/fastapi/ise_ms/certificates/ise/certificate.pem:/website/app/certificates/ise/certificate.pem

In order to verify the ISE certificate, ensure that the appropriate option Verify server’s SSL certificate is checked on the ISE server page within the app.

Custom Ingress Configuration (Optional)

In the case that the preconfigured Nginx configuration provided by avodaq cannot be used, please consider the following aspects relating to ingress.

Request Routing Incoming requests are dispatched based on URL prefix:

WebSocket Support The /api/v1/ise/ws/ path has dedicated WebSocket handling, upgrading the HTTP connection and setting extended read/send timeouts of 1 hour to support long-lived connections.

Installation note: The container hostnames (management_microservice, ise_microservice, nodejs) must match the service names defined in the docker-compose.yml, and the TLS certificate files must be provisioned before starting the Nginx container.

Configure Docker to Start on Boot (Optional)

See these Docker instructions.

Operation

Basic Operations

Note that all docker compose commands are to be executed in the app folder where the file docker-compose.yml is located.

Note that all docker commands may need to be preceded with sudo.

Start MAC Manager

docker compose up -d

Stop MAC Manager

docker compose stop

View the logs

docker logs -f -n 20000 management_ms

docker logs -f -n 20000 ise_ms

Reload a container (e.g. after changing the .env file)

docker compose up <container_name> -d

Perform an Update

You will be informed as and when a new version is available.

Update your docker-compose.yml file

Update the following lines to reflect the new version number:

nodejs:
  image: avodaq.azurecr.io/avodaq/software/projects/ise-mac-manager/mac-manager-frontend:2.x.x

ise_microservice:
  image: avodaq.azurecr.io/avodaq/software/projects/ise-mac-manager/mac-manager-ise-microservice:2.x.x

management_microservice:
  image: avodaq.azurecr.io/avodaq/software/projects/ise-mac-manager/mac-manager-management-microservice:2.x.x

Download new images

docker compose pull

Restart docker containers

docker compose up -d

Configure Background Jobs

Background Synchronisation of Cisco ISE Endpoints and Groups

Create a cronjob to execute the following command

/usr/bin/docker exec ise_microservice python3 /website/app/tasks/sync_endpoints.py >> /home/docker/docker/cronjob_logs/sync_endpoints.log 2>&1

Note: In a kubernetes deployment, the cronjob should ideally use the same redis service as created for the ISE microservice backend.

Background Synchronisation of Active Directory Users

Create a cronjob to execute the following command

/usr/bin/docker exec management_microservice python3 /website/app/cron_jobs/ldap_sync.py >> /home/docker/docker/cronjob_logs/ldap_sync.log 2>&1

Configure Identity Groups to Exclude from Synchronisation

Some default identity groups in the Cisco ISE can grow very large, for example Unknown and Profiled.

This can negatively impact the performance of our data synchronisation. Therefore, it is possible to exclude these groups.

For an end user of the MAC Manager app, it appears that the endpoints do not exist. However, when they attempt to add any endpoint which is currently in one of the excluded groups, we apply a special logic in the background and move the endpoint to the new target group. End users do not require any access permissions for the excluded groups, but would require read-write permission on the target group.

See the environment variable EXCLUDED_GROUPS_STRING.

Example:

EXCLUDED_GROUPS_STRING:Unknown,Profiled

Environment (.env) files

The environment files allow environment-specific variables to be set.

Docker

./.env

Management Microservice

./fastapi/management_ms/.env

./fastapi/management_ms/database/.env

If the PostgreSQL Docker image is used in the docker-compose file, the following environment variables must be set. Otherwise, it is sufficient to provide only DB_CONNECTION_STRING above.

ISE Microservice

./fastapi/ise_ms/.env

./fastapi/ise_ms/database/.env

If the PostgreSQL Docker image is used in the docker-compose file, the following environment variables must be set. Otherwise, it is sufficient to provide only DB_CONNECTION_STRING above.

Frontend service

./nodejs/.env