Access Expert Active Directory Integration

[Alan_Wood]

Issue

Access Expert Integration Setup with Microsoft Active directory

Product Line

EcoStruxure Access Expert

Environment

• Access Expert Hosted V3
• Microsoft Active Directory

Resolution

Overview

The Feenics Appliance by Feenics runs the Feenics Active Directory Service. This service allows for secure communication between Active Directory Servers and Access Expert. The service is installed on the appliance by Feenics and is ready to use upon arrival.">The Feenics Appliance by Feenics runs the Feenics Active Directory Service. This service allows for secure communication between Active Directory Servers and Access Expert. The service is installed on the appliance by Feenics and is ready to use upon arrival.

How to set up the Appliance

The appliance is ready to use out of the box. Feenics will supply the password to log onto your appliance once you receive it.

The appliance will need to communicate outbound over port 443 to https://api.Feenics.com  in order for the service to reach your instance in Keep by Feenics.
The appliance will also need to have inbound and outbound communication to your Active Directory Server. The default ports used for this communication are either port 389 or 636 depending on if SSL is used.

Why an Appliance

The nature of Active Directory requires Access Expert to access the Domain Controller for Access Directory. For security purposes, Feenics has created an appliance that communicates via the LDAP protocol on the internal network and then makes outbound calls to the Feenics API server in AWS.

What is on my Appliance

Feenics installs 2 things on your Windows 10 appliance, the Active Directory Service and the logging software for the appliance:

1. Active Directory Service
2. SEQ Logs

The LDAP Service is installed on the C:\\ drive of the appliance. The files will reside within the C:\Program Files (x86)\Feenics\Active Directory Service folder. It is important to not modify or alter this folder in any way. If you open your 'Services' from the windows key you will see the status of the Feenics Active Directory Service. The Active Directory service is designed to interface with 1 (one) Keep Instance.

We install SEQ logs to allow the collection of a structured log of all events from the service. In most cases, these events are not needed or reviewed, however, in the case of an issue these logs provide critical information for Feenics to diagnose the problem. To access your SEQ logs, open Internet Explorer and enter the web address HTTP://localhost:5341 

Active Directory Requirements

1. Active Directory user that has appropriate read permissions on the sections you wish to pull data from.
2. The local network must allow the Active Directory to connect to the appliance.
3. The Active Directory Appliance must be able to connect to "https://api.Feenics.com" on port 443.

Active Directory Service

The Active Directory Service has the last ping associated with the Keep by Feenics UI. Open the LDAP Agent to see the most recent ping to confirm that the Active Directory Appliance is talking to the Keep Server. To check the Active Directory Service, Navigate to the General Configuration tab, select LDAP Agents Service, open one of the LDAP Agents, and view the Last Ping at the top of the page next to the user drop-down menu. This last ping shows the last communication between the Active Directory service and Keep by Feenics.

Active Directory Agent

The Active Directory Service will need to talk to the appliance.  When adding the LDAP Query, the IP address of the Domain Controller, the password for the panel, and port for communication will need to be specified. No two installations of the LDAP module will be the same, so it is important to work with the customer IT support team.

Adding an LDAP Agent

1. Navigate to the General Configuration tab and select LDAP Agents from the sub-menu. This will open a new tab with the LDAP Agents window.
2. From the top left of the page, you can select the 'Add LDAP Agent’.
3. Give the Agent a Display name.
4. Assign an LDAP User.
5. Click ‘OK’. This will add the Agent to the list of LDAP Agents. Double click to open the Agent and to add a query.
6. The new LDAP Agent will need to have all the information filled out. See the above section for detailed information on each section.

LDAP Query

Once the LDAP Agent is created, the LDAP Query will need to be created to indicate the AD being connected to, the authentication, and the mapping required.

The minimum required fields are:

1. Display Name of LDAP Query.
2. Person Mapping
   1. Display Name.
   2. First Name.
   3. Last Name.

The LDAP Query is composed of

• Instance: This is the instance that the Query will reside it. This is used in enterprise instances where the query may populate a shared instance.
• Display Name: The name of the Query that is used throughout the instance.
• Username: The username that will authenticate to the AD domain controller.
• Password: The password associated with the username to authenticate to the AD domain controller.
• Host Name: The hostname or IP address of the AD domain controller.
• Bind Path: This is a path that limits the search within AD. This is not required but can be used to limit the query to only search a certain subset of data.
• Port: The port that connection will be made (selecting SSL will change the port).
• Query: The specific requirements that a record must meet in order to be returned.
• Frequency: The time in seconds between syncs.
• Disable: Turns off the Query.
• Directory Sync: Changes the Sync type to Directory Synchronization.
• Use SSL: Turns on or off SSL.
• Preserve Cards: By default, Keep turns off all assigned cards to a cardholder if they are disabled in AD. This can be overridden by checking this box.

Person Mapping & Common AD References used by Keep. Note: All AD installations are different, and these examples may not accurately represent your mapping requirements.

• Display Name: cn
• First Name: givenname
• Last Name: sn
• Email: mail
• Home Address: true
• Home Phone: homephone
• Work Phone: telephonenumber
• Mobile: mobile
• Identification Photo: thumbnailphoto
• Badge Type: title

Mapping Custom Forms

1. Create a custom form.
2. Add a new field which matches the fieldname from Active Directory.
3. Within the AD Person mapping, add custom form.
4. (OPTIONAL) If you are querying based on this information, ensure the field names match exactly within the query.

**If your custom form was created using Pascal Case (default) then your query fieldname requires an uppercase leading character. i.e. if the AD field is ’employeeID’ the custom form field should read ‘EmployeeID’.

USNChanged

When a domain controller modifies an object, it sets that object's uSNChanged attribute to a value that is larger than the previous value of the uSNChanged attribute for that object and larger than the current value of the uSNChanged attribute for all other objects held on that domain controller. An application can find the most recently changed object on a domain controller by finding the object with the largest uSNChanged value. The second most recently changed object on a domain controller will have the second-largest uSNChanged value and so on.

Our LDAP service keeps track of the most recent uSNChanged attribute that it has assessed and compares that when it runs its query to check if there is anything new or changed that it must import.

However, the uSNChanged attribute is not replicated, therefore reading an object's uSNChanged attribute at two different domain controllers will typically give different values. Therefore, to use this method effectively we must bind to a controller to ensure we are not missing anything. If there is a load balancing operation that prevents binding to a controller then it would be better to set up the service to use Directory Synchronization.

Directory Synchronization (DirSync)

When you perform a DirSync search, you pass in a provider-specific data element (cookie) that identifies the directory state at the time of the previous DirSync search. For the first search, you pass in a null/blank cookie and the search returns all objects that match the filter. The search also returns a valid cookie and stores the cookie in the same storage that you are synchronizing with the Active Directory server. On subsequent searches, the cookie will be retrieved from storage and passed with the search request. The search results should now include only the objects and attributes that have changed since the previous state identified by the cookie. The search always returns a new cookie to store for the next search.

Our LDAP service, when using DirSync, stores the cookie in the LDAP Query as Metadata. It is a good idea to initialize the DirSync with a very general query as the more the initialization finds the more items will be tracked moving forward. The way we have set up the LDAP DirSync is to find all the interesting objects rebind to them and ensure all the needed information is caught (we do not want to think a security roll has been removed which is our default if we can not find one in the changeset) and that it is a valid item we are searching for (initialized generally).

The DirSync control is powerful, but has two significant limitations:

• Only for highly privileged applications: To use the DirSync control, an application must run under an account that has the SE_SYNC_AGENT_NAME privilege on the domain controller (Domain Administrator and higher). Few accounts are so highly privileged, so an application that uses the DirSync control cannot be run by ordinary users.
• No subtree scoping: The DirSync control returns all changes that occur within a naming context. An application interested only in changes that occur in a small subtree of a naming context must wade through many irrelevant changes, which is inefficient both for the application and for the domain controller.

Example Queries

1. objectClass=user – This query looks for all users within Active Directory.
2. (&(ObjectClass=Person)(employeeID=ps*)) – This query looks for all Persons in Active Directory with an employee ID that starts with “ps”.
3. (&(ObjectClass=Person)(givenname=A*)) – This query returns all Persons in Active Directory with a first name that starts with “A”
4. (&(ObjectClass=Person)(givenname=A*)(|(department=Engineering)(department=Sales))) – This query returns all Persons in Active Directory with a first name that starts with “A” and is in either the Sales or Engineering departments.
5. (objectClass=user)( mail=*@mail.gov)(userAccountControl=512) – This query returns all users in AD with an email at the ‘mail.gov’ domain and whose account status is normal.
6. (&(objectClass=User)(employeeID=*)(displayName=*)(division=*)(!(principalAccount=*))(userAccountControl=512)) – This query returns all users with an employee ID, display name and division who are not a principal account and whose account is normal.
7. (&(ObjectClass=Person)(|(company=CompanyA)(company=CompanyB)) – This query returns all people in Active Directory that work for Company A or Company B.
8. (objectClass=user)(mail=*@mail.com) – This query returns all users in Active Directory that have an email at the ‘mail.com’ domain.
9. (&(&(&(objectCategory=person)(objectClass=user)(employeeID=*)(| (division=1)(division=2)(division=3)(division=4) )))) ))) – This query returns all Persons in Active Directory with a user account, an assigned employee ID and are in division 1, 2, 3, or 4.

Common Issues

Issue	Fix
My LDAP Sync is pulling in people with no information	Confirm you have completed the person mapping from within the LDAP Query window. If the person mapping is blank, the information has not been assigned a field within Keep.
My LDAP Agent ping is recent but my last sync time on the query is not.	Check your query frequency and confirm that the frequency is set to the expected value and that the last sync is within that time frame. Note: The frequency is in seconds.
My query is returning zero results.	Check your query spelling and formatting. A single parenthesis can change the query. Check to make sure the user given in the query that is logging into Active Directory has the proper permissions to read the information being queried.
I am having trouble and have checked everything else.	Check the SEQ logs at HTTP://localhost:5341  to see if any errors are being reported. For help writing a query see SEQ help site at HTTP://docs.getseq.net/docs
My query was working but stopped recently.	Check to make sure no users have modified the query accidentally via the Audit Logs. Check with IT to make sure no network changes have been made recently. Even small changes can have big impacts.