AD-Listener

Sender

This service implements an ad listener. Set it up and listen to object and password changes from a domain controller.

docker pull registry.goingrid.io/services/ad-listener:v0.1.0

Table of contents

Prerequisite

Enable Active Directory Recycle Bin

Your domain controllers need to have Active Directory Recycle Bin activated. Refer to following guide Enable Active Directory Recycle Bin.

Password filter

To use the password filter feature in the Ad-Listener service, one need to configure LDAPS/STARTTLS and install it on the Domain controller. Refer to the Password Installation Walkthrough.

Service properties

This service implements the ingrid protocol message. Following properties are being used:

Property Usage
Class -
Operation -
Control See below
Data Contains the changed, deleted object or the password

Control

Key Multivalue Required Note
event no no Identifies the event if it is either a change, delete or an event from the password filter. Valid values object-changed, object-deleted and password-changed

Service capabilities

Poll object changes and delete changes

In order to listen to change and delete events from an active directory, you have to deploy the service and let the poller do the work. Following is a configuration example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ad-listener
spec:
  selector:
    matchLabels:
      app: ad-listener
  template:
    metadata:
      labels:
        app: ad-listener
    spec:
      containers:
      - name: ad-listener
        image: registry-dev.goingrid.io/services/ad-listener:latest
        imagePullPolicy: Always
        volumeMounts:
        - mountPath: /data
          name: data
        resources:
          limits:
            cpu: 200m
            memory: 32Mi
          requests:
            cpu: 50m
            memory: 16Mi
        env:
        - name: name
          value: ad-listener
        - name: SERVERHOST
          value: core-ingrid-hive
        - name: SERVERAUTH
          valueFrom:
            secretKeyRef:
              name: core-ingrid-serverkey
              key: serverkey
        - name: LOGLEVEL
          value: trace
        - name: LOGFORMAT
          value: TEXT/DEFAULT
        - name: LOGSENSITIVE
          value: "false"
        - name: OUTPUTCHANNEL
          value: ad-event
        - name: AD_SerialFile
          value: /data/serial.txt # mount volume, otherwise you will lose the last changed number after container restart
        - name: AD_Server
          value: adc.example.com
        - name: AD_Port
          value: 389
        - name: AD_TLS
          value: true
        - name: AD_User
          value: cn=Administrator,ou=Users,dc=example,dc=com
        - name: AD_Password
          valueFrom:
            secretKeyRef:
              name: ad-admin-pw
              key: pw
        - name: AD_BaseDN
          value: ou=Users,dc=example,dc=com
        - name: AD_DeletedObjectsDN
          value: ou=Deleted_Objects,dc=example,dc=com
      serviceAccountName: core-ingrid
      serviceAccount: core-ingrid
      restartPolicy: Always
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: ad-listener-claim

Password changes

In addition to listen to password changes, you need to configure the password filter. Following is a full configuration example with the password filter:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ad-listener
spec:
  selector:
    matchLabels:
      app: ad-listener
  template:
    metadata:
      labels:
        app: ad-listener
    spec:
      containers:
      - name: ad-listener
        image: registry-dev.goingrid.io/services/ad-listener:latest
        imagePullPolicy: Always
        volumeMounts:
        - mountPath: /data
          name: data
        resources:
          limits:
            cpu: 200m
            memory: 32Mi
          requests:
            cpu: 50m
            memory: 16Mi
        env:
        - name: name
          value: ad-listener
        - name: SERVERHOST
          value: core-ingrid-hive
        - name: SERVERAUTH
          valueFrom:
            secretKeyRef:
              name: core-ingrid-serverkey
              key: serverkey
        - name: LOGLEVEL
          value: trace
        - name: LOGFORMAT
          value: TEXT/DEFAULT
        - name: LOGSENSITIVE
          value: "false"
        - name: OUTPUTCHANNEL
          value: ad-event
        - name: AD_SerialFile
          value: /data/serial.txt # mount volume, otherwise you will lose the last changed number after container restart
        - name: AD_Server
          value: adc.example.com
        - name: AD_Port
          value: 389
        - name: AD_TLS
          value: true # needs to be true if using password filter
        - name: AD_User
          value: cn=Administrator,ou=Users,dc=example,dc=com
        - name: AD_Password
          valueFrom:
            secretKeyRef:
              name: ad-admin-pw
              key: pw
        - name: AD_BaseDN
          value: ou=Users,dc=example,dc=com
        - name: AD_DeletedObjectsDN
          value: ou=Deleted_Objects,dc=example,dc=com
        - name: AD_PasswordFilterAddress
          value: adc.example.com:5999
        - name: AD_PasswordFilterToken
          valueFrom:
            secretKeyRef:
              name: ad-token
              key: token
      serviceAccountName: core-ingrid
      serviceAccount: core-ingrid
      restartPolicy: Always
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: ad-listener-claim

Service configuration

The service configuration has been split up for easier readability and use.

General configuration

The are the configration parameters used to define the general configuration.

Parameter Default Description
AD_Class "object" Class used in the ingrid message
AD_Operation "change" Operation used in the ingrid message
AD_RequestTimeout "60s" Timeout of the request to the hive
AD_PollInterval "30s" Poll interval
AD_SerialFile "data/serial.txt" Filename where the last AD_SerialAttr will be stored
AD_FilterPlaceholder "%%%i%%%" Placeholder used to replace with the defined AD_SerialAttr value in AD_Filter
AD_SerialAttr "uSNChanged" The attribute used in the AD_Filter (only int64 attributes possible)
AD_FetchAttrs "uSNChanged" List of attributes to fetch for the object-changed and object-deleted events

Connection configuration

These are the configration parameters used to define the ldap connection to the active directory.

Parameter Default Description
AD_Server "" LDAP address used to connect to the active directory (use prefix ldaps:// for LDAPS)
AD_Port 389 LDAP port used to connect to the active directory
AD_TLS false Enable or disable LDAP TLS
AD_User "" Username used to connect to the active directory
AD_Password "" Password used to connect to the active directory

Poll change events configuration

These are the configuration parameters used to restrict the poll search for change events.

Parameter Default Description
AD_BaseDN "" Define a base dn to restrict the poll for object-changed events
AD_Filter "(&(objectCategory=person)(objectClass=user)(cn=*)(uSNChanged>=%%%i%%%))" Define a filter to restrict the poll for object-changed events even more

Poll delete events configuration

These are the configuration parameters used to restrict the poll search for delete events.

Parameter Default Description
AD_DeletedObjectsDN "" DN where the deleted objects are stored (usually something like CN=Deleted Objects,DC=example,DC=com)
AD_DeletedObjectsFilter "(&(isDeleted=TRUE)(uSNChanged>=%%%i%%%))" Define a filter to restrict the poll for object-deleted events

Password filter configuration

These are the configuration parameters to listen to password changes.

Parameter Default Description
AD_PasswordFilterAddress "0.0.0.0:5999" TCP/IP address the service will listen on
AD_PasswordFilterToken "" Token used for decryption

Additionally the AD-Listener service includes all properties of the service configuration and the output configuration.