Technical Guide

Technical requirements

Deployment

avodaq provides the IMM 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:

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

Network:

• Server requires network access to the ISE API

  • Port: 9060
  • 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:

• ISE ERS Admin User (to perform ISE API operations) ¹
• TLS/SSL certificate(s) for the included web server (nginx)
• AD User for Active Directory functionality (if desired)
  • TLS/SSL full chain certificate for Active Directory server

Installation

Pre-flight

Confirm that the server required to host the IMM 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

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 password

Create django secret using the following command:

docker start django && docker exec -it django /usr/bin/python3 manage.py shell -c "from django.core.management.utils import get_random_secret_key; print(f'Secret key is: {get_random_secret_key()}')" && docker stop django

Generate a password for the MySQL database using your preferred password manager (tip: don’t use any special characters).

Set environment variables

Set the environment variable SECRET_KEY in the file ./django/.env to the generated django secret.

Replace the <placeholder> in the environment variable DATABASE_URL in the file ./django/.env to the generated database password.

Set the environment variable MYSQL_ROOT_PASSWORD in the file ./database/.env to the generated database password.

Set the variable DOCKERDIR in the file ./.env to the full path of the installation directory, e.g.

DOCKERDIR="/opt/avodaq-imm"

Set the variable ALLOWED_HOSTS in the file ./django/.env to one or more valid hosts. Typically this will be the IP address and/or hostname(s) of the server running the IMM app.

ALLOWED_HOSTS=1.2.3.4,imm-app.domain.com

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, for example:

./nginx/certificate.crt

./nginx/certificate.key

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

volumes:
  - $DOCKERDIR/nginx/certificate.crt:/etc/nginx/certs/certificate.crt
  - $DOCKERDIR/nginx/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 ./django/ldap, for example:

./django/ldap/certificate.pem

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

  - $DOCKERDIR/django/ldap/certificate.pem:/website/ldap/certificate.pem

Set the following environment variable to True in the ./django/.env file.

LDAP_CA_CERT_FILE_VALIDATION=True

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 ./django/ise_tls, for example:

./django/ise_tls/certificate.pem

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

  - $DOCKERDIR/django/ise_tls/certificate.pem:/website/ise_tls/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.

(Optional) Configure docker to start on boot

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 IMM

docker compose up -d

Stop IMM

docker compose stop

View the logs

docker logs -f -n 20000 django

Perform an update

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

Update your docker-compose.yml file

Update the line image: avodaq.azurecr.io/avodaq/software/projects/ise-mac-manager/ise-mac-manager:v1.1.1 to reflect the new version number

Download new images

docker compose pull

Restart docker containers

docker compose up -d

Configure a background synchronisation with the ISE server

See the Django environment variable ISE_SYNC_INTERVAL.

Example:

ISE_SYNC_INTERVAL=06:00,12:00,18:00

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 IMM 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 Django environment variable GROUPS_EXCLUDE_TO_FETCH_ENDPOINTS.

Example:

GROUPS_EXCLUDE_TO_FETCH_ENDPOINTS:Unknown,Profiled

Environment (.env) files

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