What is the AD Bridge agent?

The AD Bridge agent is installed on a Linux or Unix computer to connect it to Microsoft Active Directory and to authenticate users with their domain credentials.

The agent integrates with the core operating system to implement the mapping for any application, such as the logon process (/bin/login), that uses the name service (NSS) or pluggable authentication module (PAM). As such, the agent acts as a Kerberos 5 client for authentication and as an LDAP client for authorization. In AD Bridge, the agent also retrieves Group Policy Objects (GPOs) to securely update local configurations, such as the sudo file.

Daemon services and architecture in AD Bridge

The AD Bridge agent is composed of the service manager daemon (/opt/pbis/sbin/lwsmd). At startup, the operating system (OS) is configured to start the service manager daemon. It is then instructed (by the OS) to start all desired services with the command /opt/pbis/bin/lwsm autostart. The service manager daemon keeps track of the services already started and ensures the services are started and stopped in the appropriate order.

The following options are available on the service manager daemon:

/opt/pbis/sbin/lwsmd –help
Usage: /opt/pbis/sbin/lwsmd [options ...]
OPTIONS:
            
--start-as-daemon        Start as a background process
--syslog                 Log to syslog (default when starting as daemon)
--logfile                Log to file
--loglevel <level>       Set log level to <level> (error, warning, info, verbose, debug, trace)
--container <group>Start as a container for service group <group>
--ignoresmf              Do not start ADBridge daemons using Solaris SMF
--help                   Show usage information

✅

Example

/opt/pbis/sbin/lwsmd --start-as-daemon --logfile /tmp/log.log

The service manager daemon (/opt/pbis/sbin/lwsmd) includes the following services:

LSASS architecture

AD Bridge input-output service

The lwio service multiplexes input and output by using SMB1 or SMB2. The service's plugin-based architecture includes several drivers, the most significant of which is coded as rdr, the redirector.

The redirector multiplexes Common Internet File System (CIFS) and Server Message Block (SMB) connections to remote systems. For instance, when two different processes on a local Linux computer need to perform input-output operations on a remote system by using CIFS and SMB, with either the same identity or different identities, the preferred method is to use the APIs in the lwio client library, which routes the calls through the redirector. In this example, the redirector maintains a single connection to the remote system and multiplexes the traffic from each client by using multiplex IDs.

The input-output service plays a key role in the AD Bridge architecture because AD Bridge uses Distributed Computing Environment/Remote Procedure Calls (DCE/RPC). DCE/RPC uses SMB. Thus, the DCE-RPC client libraries use the AD Bridge input-output client library, which in turn makes calls to lwio with Unix domain sockets.

When you join a domain, AD Bridge uses DCE-RPC calls to establish the machine password. The AD Bridge authentication service periodically refreshes the machine password by using DCE-RPC calls. Authentication of users and groups in Active Directory takes place with Kerberos, not RPC.

In addition, when a joined computer starts up, the AD Bridge authentication service enumerates Active Directory trusts by using DCE-RPC calls that go through the redirector. With one-way trusts, the authentication service uses RPC to look up domain users, groups, and security identifiers. With two-way trusts, lookup takes place through LDAP, not RPC.

Because the authentication service registers a trust only when it starts up, you should restart lsass with the AD Bridge Service Manager after you modify a trust relationship.

The AD Bridge Group Policy agent also uses the input-output client library and the redirector when it copies files from the sysvol share of a domain controller.

To troubleshoot remote procedure calls that go through the input-output service and its redirector, use a Wireshark trace or a TCP dump to capture the network traffic.

ℹ️

Note

We recommend Wireshark, a free open-source packet analyzer.

Privileged Access Managment (PAM) options

AD Bridge uses the following standard PAM options:

• try_first_pass
• use_first_pass
• use_authtok
• debug

Additionally, there are non-standard options to the PAM configuration on some systems:

• unknown_ok: Allows local users to continue down the stack while blocking domain users who do not meet group membership requirements.
• remember_chpass: Prevents the AIX computer on AIX systems, which have both PAM and LAM modules, from trying to change the password twice and prompting the user twice.
• set_default_repository: Used to make sure password changes work as expected on Solaris systems.
• smartcard_prompt: Enables smart card prompts.
• no_require_membership: Allows the require membership check to be skipped.

Manage AD Bridge services

Using the AD Bridge Service Manager, you can:

• Track and troubleshoot all the AD Bridge services with a single command-line utility. For example, check the status of the services, view their dependencies, and start or stop them. The service manager is the preferred method for restarting a service, because it automatically identifies a service's dependencies and restarts them in the correct order.
• Use the service manager to set the logging destination and the log level.

ℹ️

Note

For more information, see Manage AD Bridge Enterprise services.

Caches and databases in AD Bridge

To maintain the current state and to improve performance, the AD Bridge authentication service (lsass) caches information about users and groups in memory.

You can change the cache to store the information in an SQLite database.

The AD Bridge site affinity service, netlogon, caches information about the optimal domain controller and global catalog in the AD Bridge registry.

The following files are in /var/lib/pbis/db:

Since the default UIDs that AD Bridge generates are large, the entries made by the operating system in the lastlog file when AD users log in make the file appear to increase to a large size. This is normal and are not cause for concern. The lastlog file (typically /var/log/lastlog) is a sparse file that uses the UID and GID of the users as disk addresses to store the last login information. Because it is a sparse file, the actual amount of storage used by it is minimal.

Additional information about a computer's Active Directory domain name, machine account, site affinity, domain controllers, forest, the computer's join state, and so forth is stored in the AD Bridge registry. Here is an example of the kind of information that is stored under the netlogon key:

[HKEY_THIS_MACHINE\Services\netlogon\cachedb\example.com-0]
"DcInfo-ClientSiteName"="Default-First-Site-Name"
"DcInfo-DCSiteName"="Default-First-Site-Name"
"DcInfo-DnsForestName"="example.com"
"DcInfo-DomainControllerAddress"="192.168.92.20"
"DcInfo-DomainControllerAddressType"=dword:00000017
"DcInfo-DomainControllerName"="w2k3-r2.example.com"
"DcInfo-DomainGUID"=hex:71,c1,9e,b5,18,35,f3,45,ba,15,05,95,fb,5b,62,e3
"DcInfo-Flags"=dword:000003fd
"DcInfo-FullyQualifiedDomainName"="example.com"
"DcInfo-LMToken"=dword:0000ffff
"DcInfo-NetBIOSDomainName"="EXAMPLE"
"DcInfo-NetBIOSHostName"="W2K3-R2"
"DcInfo-NTToken"=dword:0000ffff
"DcInfo-PingTime"=dword:00000006
"DcInfo-UserName"=""
"DcInfo-Version"=dword:00000005
"DnsDomainName"="example.com"
"IsBackoffToWritableDc"=dword:00000000
"LastDiscovered"=hex:c5,d9,86,4b,00,00,00,00
"LastPinged"=hex:1b,fe,86,4b,00,00,00,00
"QueryType"=dword:00000000
"SiteName"=""

Name Service Caching Daemon (NSCD)

If nscd is not disabled, clear the cache after a domain join by restarting the service: service nscd restart/reload.

For optimal efficiency, AD Bridge best practice is to disable the nscd cache from the configuration file /etc/nscd.conf. For any issues on systems running nscd, it should be turned off.

Cached credentials

AD Bridge caches credentials so that users can log on when their Linux or Unix computer is disconnected from the network or if their Active Directory services are unavailable.

Synchronize time between AD Bridge and the domain controller

For the AD Bridge agent to communicate over Kerberos with the domain controller, the clock of the client must be within the domain controller's maximum clock skew, which is 300 seconds, or 5 minutes, by default.

The clock skew tolerance is a server-side setting. When a client communicates with a domain controller, it is the domain controller's Kerberos key distribution center that determines the maximum clock skew. Since changing the maximum clock skew in a client's krb5.conf file does not affect the clock skew tolerance of the domain controller, the change does not allow a client outside the domain controller's tolerance to communicate with it.

The clock skew value that is set in the /etc/pbis/krb5.conf file of Linux or Unix computers is useful only when the computer functions as a server for other clients. In such cases, you can use an AD Bridge Group Policy setting to change the maximum tolerance.

The domain controller uses the clock skew tolerance to prevent replay attacks by keeping track of every authentication request within the maximum clock skew. Authentication requests outside the maximum clock skew are discarded. When the server receives an authentication request within the clock skew, it checks the replay cache to make sure the request is not a replay attack.

ℹ️

Note

For more information, see the MIT article Clock Skew.

Use a Network Time Protocol server

If you set the system time on your computer with a Network Time Protocol (NTP) server, the time value of the NTP server and the time value of the domain controller could exceed the maximum skew. As a result, you will be unable to log on your computer.

If you use an NTP server with a cron job, there will be two processes trying to synchronize the computer's time, causing a conflict that will change the computer's clock back and forth between the time of the two sources.

We recommend that you configure your domain controller to get its time from the NTP server and configure the domain controller's clients to get their time from the domain controller.

Auto-detection of offline domain controller and global catalog

The AD Bridge authentication service, lsass, manages site affinity for domain controllers and global catalogs and caches the information with netlogon. When a computer is joined to Active Directory, netlogon determines the optimum domain controller and caches the information.

If the primary domain controller goes down, lsass automatically detects the failure and switches to another domain controller and another global catalog within a minute.

However, if another global catalog is unavailable within the forest, the AD Bridge agent will be unable to find the Unix and Linux information of users and groups. The AD Bridge agent must have access to the global catalog to function. Therefore, we recommend that each forest has redundant domain controllers and redundant global catalogs.

AD Bridge agent Active Directory trust support

The AD Bridge agent supports the following Active Directory trusts:

ℹ️

Note

In all Default Cell scenarios, you must enable the Default Cell in both forests.

ℹ️

Note

For more information on the types of trusts, see the Microsoft article Trust Types.

Notes on trusts

The following is general information about working with trusts.

• To access a trust, users or groups must be added to a cell.
• In a two-way trust, AD Bridge searches across all trusted global catalogs. Each domain must opt in by creating the Default Cell object within that domain.
• If there is a UID conflict across two domains, only the user provisioned to the cell authenticates. If both are provisioned, a true conflict occurs and the users are not allowed access until it is resolved.
• In a one-way trust in which Forest A trusts Forest B, a computer in Forest A cannot get group information from Forest B, because Forest B does not trust Forest A. The computer in Forest A can obtain group information if the user logs on with a password for a domain user, but not if the user logs on with Kerberos single sign-on credentials. Only the primary group information, not the secondary group information, is obtained.
• To support a one-way trust without duplicating user accounts, you must use a Named Cell, not a Default Cell. If Domain A trusts Domain B (but not the reverse) and if Domain B contains all the account information in cells associated with OUs, then when a user from Domain B logs on a machine joined to Domain A, Domain B will authenticate the user and authorize access to the machine in Domain A.

ℹ️

Note

In such a scenario, you should also add a domain user from the trusted domain to an administrative group in the trusting domain so you can manage the trusting domain with the appropriate level of read access to trusted user and group information. However, before you add the domain user from the trusted domain to the trusting domain, you must first add to the trusting domain a group that includes the user because Unix and Linux computers require membership in at least one group and Active Directory does not enumerate a user's membership in foreign groups.

• If joining a domain with an administrative account from a different domain, you must provide the account's UPN:

✅

Example

domainjoin-cli join domainA.com [email protected]

Trusts and cells in AD Bridge

In AD Bridge, a cell contains Unix settings, such as a UID and a GID, for an Active Directory user. When an AD user logs in to an AD Bridge client, AD Bridge searches Active Directory for the user's cell information and must find it to operate properly. Thus, your AD topology and your trust relationships may dictate where to locate a cell in Active Directory so that your AD Bridge clients can access their Unix settings.

With a Default Cell, AD Bridge searches for user or group attributes in the forest's global catalog. In a multi-domain topology, a Default Cell must exist in the domain where user and group objects reside in addition to the Default Cell that exists in the domain to which Linux or Unix computers are joined.

ℹ️

Note

In a multi-domain topology, be sure to create a Default Cell in each domain.

Ideally, Unix information is stored on the User and Group objects in Default Cell Directory Integrated mode. If the client computer does not have the access rights to read and write the information to the user object, as in an external one-way trust, the Unix information is stored locally in a Named Cell, that is, a cell associated with an organizational unit.

ℹ️

Note

For information about cells, see Install the Management Console .

Supported platforms for AD Bridge

AD Bridge runs on a broad range of Linux or Unix platforms. BeyondTrust frequently adds new vendors and distributions.

ℹ️

Note

For the list of supported platforms, see Supported platforms.

SELinux support

The AD Bridge SELinux implementation supports many operating systems.

ℹ️

Note

When you install on RedHat Enterprise Linux, AD Bridge runs under the unconfined_t domain.

The AD Bridge post install script checks if /usr/sbin/semodule and /etc/selinux/targeted/policy are present. If both checks pass, the targeted policy file (pbis.pp) is installed if found in /opt/pbis/share///pbis.pp.

Unsupported operating systems

If SELinux is enabled and you are installing to an unsupported operating system, the installation is stopped. You must place SELinux in permissive mode to continue.

• SELinux enabled is only detected with the RPM package.
• SELinux enabled is not detected with the self-extracting installer or domainjoin.

ℹ️

Note

For more information, see Configure SELinux in AD Bridge.