Step-by-Step: Using the OTRS Active Directory Configuration CreatorOTRS (Open Ticket Request System) is a widely used open-source service management suite. Integrating OTRS with Active Directory (AD) simplifies user management by allowing centralized authentication and group-based authorization. The OTRS Active Directory Configuration Creator is a tool designed to generate the LDAP configuration entries you need to connect OTRS to AD, minimizing manual errors and accelerating setup. This article walks through the process step by step: prerequisites, planning your AD integration, using the Configuration Creator, importing the generated configuration into OTRS, testing, and troubleshooting.
Overview and prerequisites
Before starting, ensure you have the following:
- OTRS instance with administrative access (web admin or console).
- Active Directory credentials for an account that can perform LDAP queries (often a read-only service account).
- Network connectivity between the OTRS server and the AD domain controllers (ports 389 for LDAP, 636 for LDAPS).
- Optional but recommended: a test environment or a snapshot/backup of your OTRS configuration.
Having these in place prevents configuration mistakes and avoids downtime for production users.
Step 1 — Plan your integration
Decide how you want AD to interact with OTRS:
- Authentication only (users authenticate against AD but user accounts still exist in OTRS).
- Full directory synchronization (create/update user records in OTRS based on AD data).
- Group-based privileges (map AD groups to OTRS roles or groups).
Identify AD attributes you’ll map to OTRS fields. Common mappings:
- sAMAccountName → login
- mail → email
- displayName → full name
- memberOf → group memberships
Record the base DN(s) for user and group searches (e.g., dc=example,dc=com) and the distinguished name of the service account used for LDAP binds (e.g., cn=otrs,cn=Users,dc=example,dc=com).
Step 2 — Gather AD connection details
Collect:
- AD hostnames or IPs (ideally multiple DCs for redundancy).
- LDAP port (389) or LDAPS (636) and whether TLS/SSL is required.
- Service account DN and password.
- Base DN for users and groups.
- Search filters you intend to use (e.g., (&(objectClass=user)(!(objectClass=computer))) ).
Having precise details helps the Configuration Creator produce accurate LDAP settings.
Step 3 — Open the OTRS Active Directory Configuration Creator
Launch the Configuration Creator — this may be a web-based helper bundled with your OTRS distribution or a script/GUI provided by your organization. The tool typically prompts for the AD connection details you gathered.
Common fields you’ll encounter:
- LDAP server(s)
- Port and encryption method (LDAP/LDAPS/StartTLS)
- Bind DN and password
- Base DN(s) for user and group searches
- User and group object classes and attribute mappings
- Search filters and paging controls
- Group mapping rules
Step 4 — Fill in connection and search settings
Enter the AD host(s), port, and encryption choice. If using LDAPS or StartTLS, ensure the OTRS server trusts the AD certificate (import the CA certificate into the system trust store if necessary).
Provide the bind DN (service account) and password. Then set:
- User Base DN: where to search for user objects.
- User Filter: e.g., (&(objectClass=user)(!userAccountControl:1.2.840.113556.1.4.803:=2)) to exclude disabled accounts.
- User Login Attribute: typically sAMAccountName or userPrincipalName.
- Email Attribute: usually mail.
- Group Base DN and Group Filter (if mapping groups).
The Configuration Creator will often offer example filters and attribute defaults — adjust them to match your AD schema and policies.
Step 5 — Configure attribute and group mappings
Map AD attributes to OTRS fields. Typical minimal configuration:
- Login attribute → sAMAccountName
- UserFirstname/UserLastname or Fullname → givenName / sn or displayName
- Email → mail
If you want group-based roles, configure how memberOf or group membership is mapped to OTRS groups. The creator may let you specify patterns or exact mappings (e.g., CN=OTRS-Support,OU=Groups,DC=example,DC=com → OTRS::Group::Support).
Test group filters to ensure your AD groups are visible with the expected DNs.
Step 6 — Generate and review the configuration
Once all fields are filled, instruct the Configuration Creator to generate the LDAP configuration snippet. Review it carefully—key items to verify:
- Correct hostnames and ports.
- Proper bind DN and that passwords are not exposed in logs or saved insecurely.
- Base DNs and search filters match your AD structure.
- Attribute mappings look correct.
- Any special options (paging, referrals, TLS settings) are appropriate.
Save a copy of the generated configuration for backup.
Step 7 — Import configuration into OTRS
There are two common ways to apply the generated settings:
- Use the OTRS admin web interface (Admin -> System -> SysConfig) to edit the Kernel::System::Auth::LDAP* settings or the LDAP configuration section and paste the generated snippet.
- Place the configuration into an appropriate config file (e.g., Kernel/Config/Files/ZZZAAuto.pm or dynamic config file per your OTRS installation) and restart the OTRS services if required.
Ensure file permissions restrict access to any files containing credentials.
Step 8 — Test authentication and synchronization
Start with a few test accounts:
- Attempt login with an AD account using the OTRS web login.
- Check OTRS logs for LDAP bind and search activity (common log locations: var/log/otrs or system journal).
- If using synchronization, run a manual sync job or wait for the scheduled sync and confirm users are created/updated with correct attributes and group memberships.
If log entries show “invalid credentials” or “no such object”, verify bind DN, password, base DN, and filters.
Step 9 — Troubleshooting common issues
- TLS/LDAPS failures: import AD CA certificate into the OTRS server trust store; verify hostname matches certificate CN/SAN.
- Timeouts or partial results: enable LDAP paging (Simple Paged Results) and check network/firewall rules.
- Incorrect group mapping: confirm memberOf attribute values and use group DN matching in the creator.
- Disabled/locked accounts appearing: use userAccountControl filter to exclude them.
- Permission errors: ensure the bind account has read access to the user and group attributes you map.
Enable verbose LDAP logging temporarily to capture query samples for debugging.
Step 10 — Harden and maintain
- Rotate service account credentials periodically.
- Limit the bind account’s rights to read-only.
- Use LDAPS/StartTLS to protect credentials in transit.
- Monitor authentication logs for suspicious activity.
- Keep configuration backups and document changes.
By following these steps, you can use the OTRS Active Directory Configuration Creator to generate correct LDAP settings, import them into OTRS, and validate that AD-based authentication and group synchronization work reliably.
Leave a Reply