Creating and Configuring an Active Directory System of Record

Prerequisites

  • Active Directory Domain Controller with LDAP/LDAPS enabled
  • Service Account with read permissions to Active Directory objects (users, groups, and any other entities you wish to synchronize)
  • SGNL User Account with Admin privileges
  • Network connectivity between SGNL and your Active Directory Domain Controller(s)
    • For LDAP: Port 389 (default) or custom port
    • For LDAPS: Port 636 (default) or custom port
  • (For LDAPS) SSL certificate chain from your Active Directory server

Permissions Required

  • The service account used for LDAP binding requires the following minimum permissions:
    • Read permissions on any User objects and their attributes you plan to synchronize
    • Read permissions on any Group objects and their attributes you plan to synchronize
    • Read permissions on any additional entities you plan to synchronize
    • Ability to perform LDAP searches within the configured Base DN

Configuring Active Directory

Setting up a Service Account

  1. Open Active Directory Users and Computers on your Domain Controller
  2. Create a new user account for SGNL synchronization (e.g., sgnl-sync-service)
  3. Set a strong password and ensure “Password never expires” is checked
  4. Add the account to the appropriate security groups that grant read access to the objects you need to synchronize
  5. Note the full Distinguished Name (DN) of this account (e.g., CN=sgnl-sync-service,CN=Users,DC=example,DC=com)

Verifying LDAP/LDAPS Connectivity

  1. Test LDAP connectivity from a machine that can reach your Domain Controller:

    ldapsearch -x -H ldap://your-dc.example.com:389 -D "CN=sgnl-sync-service,CN=Users,DC=example,DC=com" -W -b "DC=example,DC=com" "(objectClass=user)"
    
  2. For LDAPS, verify SSL certificate:

    openssl s_client -showcerts -connect your-dc.example.com:636
    

Obtaining SSL Certificate Chain (for LDAPS)

If using LDAPS for secure communication:

  1. Run the following command to retrieve the certificate chain:

    openssl s_client -showcerts -connect your-dc.example.com:636 < /dev/null
    
  2. Copy all certificates from the output (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)

  3. Create a file containing all certificates in order (server certificate first, then intermediate certificates, then root CA)

  4. Base64 encode the entire certificate chain:

    base64 -w 0 certificate-chain.pem
    
  5. Save this base64 encoded string for use in the SGNL configuration

Configuring SGNL

  1. Login to the SGNL Console

  2. From the left menu, select Identity Data Fabric

  3. Click “Add System of Record” or “Add”

  4. The SGNL SoR Catalog will show up on the screen

  5. Click on “Active Directory” which will open up the New System of Record screen with some configuration options pre-populated from the Active Directory SoR template

  6. Configure the following fields:

    System Configuration:

    • Display Name: Give your Active Directory instance a meaningful name (e.g., “Corporate Active Directory”)
    • Description: Add a description to help identify this instance
    • Hostname: Enter your Domain Controller hostname or IP address
      • For LDAP: your-dc.example.com or your-dc.example.com:389
      • For LDAPS: your-dc.example.com:636
    • Type: Keep as LDAP-1.0.0

    Authentication:

    • Username: Enter the full DN of your service account (e.g., CN=sgnl-sync-service,CN=Users,DC=example,DC=com)
    • Password: Enter the service account password
  7. Configure the Adapter Configuration. Click on the Adapter Config field and update the JSON with your Active Directory settings:

    For LDAP (without SSL):

    {
      "baseDN": "DC=example,DC=com",
      "entityConfig": {
        "User": {
          "query": "(&(objectCategory=user)(objectClass=user)(distinguishedName=*))"
        },
        "Group": {
          "query": "(&(objectCategory=group)(objectClass=group)(distinguishedName=*))"
        }
      }
    }
    

    For LDAPS (with SSL):

    {
      "baseDN": "DC=example,DC=com",
      "certificateChain": "LS0tLS1CRUdJTi...[your base64 encoded certificate chain]...LS0tLS0K",
      "entityConfig": {
        "User": {
          "query": "(&(objectCategory=user)(objectClass=user)(distinguishedName=*))"
        },
        "Group": {
          "query": "(&(objectCategory=group)(objectClass=group)(distinguishedName=*))"
        }
      }
    }
    

    Note: You can customize the LDAP queries to filter specific objects. For example:

    • To sync only users from a specific OU: (&(objectCategory=user)(objectClass=user)(distinguishedName=*OU=SpecificOU,DC=example,DC=com))
    • To sync only security groups: (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))
  8. Click “Continue” to save your Active Directory System of Record. You will be taken to the Active Directory System of Record page.

  9. All entities and relationships are created as defined in the Active Directory template:

    • User: Active Directory user accounts
    • Group: Active Directory security and distribution groups
    • Computer: Active Directory computer objects (if configured)
    • GroupMember: Relationship entity connecting users to groups
  10. If needed, you can edit an entity to modify its properties or attributes. Hover over the entity to see the Edit button.

  11. (Optional) Create additional relationships to connect Active Directory data with other Systems of Record. For example:

    • Link AD users to HR system employees using email or employeeID
    • Connect AD groups to application roles in other systems
  12. Enable synchronization for each entity you want to sync. Note that synchronization is disabled by default:

    • Hover over each entity and click “Enable Sync”
    • Start with core entities like User and Group
    • Enable GroupMember to sync group memberships
  13. Finally, enable synchronization for the entire System of Record by clicking the sync toggle at the top of the page.

  14. After synchronization completes, you’ll see the number of objects ingested for each entity. You can then:

    • Use Data Lens to explore your Active Directory data in the SGNL graph
    • Create policies based on AD group memberships, user attributes, or organizational structure
    • Make access evaluation calls that consider Active Directory data

Advanced Configuration

Custom LDAP Queries

You can customize the LDAP queries in the adapter configuration to filter or select specific objects:

{
  "entityConfig": {
    "User": {
      "query": "(&(objectCategory=user)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"
    }
  }
}

This example excludes disabled user accounts by checking the userAccountControl attribute.

Adding Custom Attributes

To sync additional Active Directory attributes not included in the default template:

  1. Navigate to the entity you want to modify
  2. Click Edit on the entity
  3. Add new attributes with:
    • Name: Friendly name for SGNL
    • External ID: The exact LDAP attribute name (e.g., employeeID, manager, telephoneNumber)
    • Type: Choose the appropriate data type
    • Indexed: Set to true if you’ll use this in policies

Using the On-Premises Connector

If your Active Directory is not directly accessible from SGNL’s cloud infrastructure:

  1. Deploy the SGNL On-Premises Connector in your network
  2. Configure the connector to communicate with your Active Directory
  3. Update the hostname in SGNL to point to your on-premises connector instead of directly to AD

Troubleshooting

Certificate Chain Issues

If you encounter SSL certificate errors when using LDAPS:

  1. Ensure you’ve included the complete certificate chain (server, intermediate, and root certificates)
  2. Verify the certificates are in the correct order
  3. Check that the base64 encoding doesn’t contain any line breaks or spaces
  4. Test the complete certificate chain using:
    echo "[your-base64-string]" | base64 -d > cert_chain.pem
    openssl crl2pkcs7 -nocrl -certfile cert_chain.pem | openssl pkcs7 -print_certs -text -noout
    

Connection Timeouts

If synchronization fails with timeout errors:

  1. Verify network connectivity between SGNL and your Domain Controller
  2. Check firewall rules for the appropriate ports (389 for LDAP, 636 for LDAPS)
  3. Ensure the service account has not been locked or disabled
  4. Test connectivity using telnet your-dc.example.com 389 (or 636 for LDAPS)

No Data Synchronized

If entities show 0 objects after synchronization or the entity shows that ‘Sync has Failed’:

  1. Verify the Base DN is correct and includes the objects you want to sync
  2. Check that the LDAP queries in the adapter configuration match your AD structure
  3. Ensure the service account has read permissions on the target objects
  4. Test your LDAP queries using ldapsearch with the same service account credentials

Performance Optimization

For large Active Directory deployments:

  1. Use specific LDAP queries to limit the scope of synchronization
  2. Consider synchronizing only active users and relevant groups
  3. Adjust the page size in entity configuration if needed
  4. Schedule synchronization during off-peak hours

Next Steps

Once your Active Directory data is successfully synchronized to SGNL:

  1. Explore your data using Data Lens
  2. Create policies leveraging AD group memberships and user attributes
  3. Configure protected systems to make authorization decisions based on AD data
  4. Set up additional Systems of Record to enrich your authorization graph
  5. Consider implementing Continuous Access workflows based on AD group membership