Overview
The Lyftron provider for Active Directory offers the most natural way to access ActiveDirectory data from .NET applications. The provider wraps the complexity of accessing ActiveDirectory data in an easy-to-integrate, fully managed ADO.NET Data Provider. .NET applications can then access ActiveDirectory as a traditional database through the provider.
The provider hides the complexity of accessing data and provides additional powerful security features, smart caching, batching, socket management, and more.
Key Features
- DataBind to ActiveDirectory using Visual Studio wizards.
- Real-time access to ActiveDirectory.
- Comprehensive support for create, read, update, and delete (CRUD) operations.
- Collaborative query processing.
Establishing a Connection
Authenticating to ActiveDirectory
To authenticate requests, set the User and Password properties to valid ActiveDirectory credentials (e.g., set User to "Domain\\BobF" or "cn=Bob F,ou=Employees,dc=Domain").
The provider uses plaintext authentication by default, since the provider attempts to negotiate TLS/SSL with the server. You can specify another authentication method with AuthMechanism.
See Advanced Settings for more information on TLS/SSL configuration.
Connecting to ActiveDirectory
Set Server and Port for basic connectivity. Additionally, you can fine-tune the connection with the following:
- FollowReferrals: When set, the provider surfaces data as views from only referral servers. To modify data on a referral server, you must specify this server with Server and Port.
- LDAPVersion: Set this to the version of the protocol your server implements; by default, the provider uses version 2.
- UseDefaultDC: Set this to connect to the default Domain Controller and authenticate using the current user credentials.
Fine-Tuning Data Access
The following properties control the scope of data returned:
- BaseDN will limit the scope of LDAP searches to the height of the distinguished name provided. Note: Specifying a narrow BaseDN may greatly increase performance; for example, a value of "cn=users,dc=domain" will only return results contained within "cn=users" and its children.
- Scope: This property enables more granular control over the data to return from a subtree.
Customizing Tables
The provider surfaces the columns most often needed from ActiveDirectory entities. However, if you need to work with other data, the tables are easy to modify. Tables are defined in schema files, which have a simple format.
To use custom schemas, set the Location property to the folder containing the schema files.
Advanced Settings
Customizing the SSL Configuration
By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.
Connecting Through a Firewall or Proxy
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
- The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.
Data Model
| Name | Type | Description |
| Account | Tables | The account object class is used to define entries that represent computer accounts. |
| ApplicationEntity | Tables | X.500 base class for applications: Directory Service only uses subclass MSFT-DSA. |
| ApplicationProcess | Tables | X.500 base class for applications: Exchange only uses subclass DSA-Application. |
| ApplicationSettings | Tables | Base class for server-specific application settings. |
| ApplicationSiteSettings | Tables | Contains all site-specific settings. |
| ApplicationVersion | Tables | Can be used by application developers to store version information about their application or its schema. |
| BuiltinDomain | Tables | The container that holds the default groups for a domain. |
| CertificationAuthority | Tables | Represents a process that issues public key certificates, for example, a Certificate Server. |
| Computer | Tables | This class represents a computer account in the domain. |
| Contact | Tables | This class contains information about a person or company that you may need to contact on a regular basis. |
| CRLDistributionPoint | Tables | The object holding Certificate, Authority, and Delta Revocation lists. |
| DHCPClass | Tables | Represents a DHCP Server (or set of servers). |
| DnsNode | Tables | Holds the DNS resource records for a single host. |
| DnsZone | Tables | The container for DNS Nodes. Holds zone metadata. |
| Domain | Tables | Contains information about a domain. |
| DomainDNS | Tables | Windows NT domain with DNS-based (DC=) naming. |
| DomainPolicy | Tables | Defines the local security authority policy for one or more domains. |
| DomainRelatedObject | Tables | The domainRelatedObject object class is used to define an entry that represents a series of documents. |
| ForeignSecurityPrincipal | Tables | The Security Principal from an external source. |
| Group | Tables | Stores a list of user names. Used to apply security principals on resources. |
| GroupOfNames | Tables | Used to define entries that represent an unordered set of names that represent individual objects or other groups of names. |
| GroupOfUniqueNames | Tables | Defines the entries for a group of unique names. In general, used to store account objects. |
| GroupPolicyContainer | Tables | This represents the Group Policy Object. It is used to define group polices. |
| IpHost | Tables | Represents an abstraction of a host or other IP device. |
| IpNetwork | Tables | Represents an abstraction of a network. The distinguished name value of the Common-Name attribute denotes the canonical name of the network. |
| Organization | Tables | Stores information about a company or organization. |
| OrganizationalPerson | Tables | This class is used for objects that contain organizational information about a user, such as the employee number, department, manager, title, office address, and so on. |
| OrganizationalRole | Tables | This class is used for objects that contain information that pertains to a position or role within an organization, such as a system administrator, manager, and so on. It can also be used for a nonhuman identity in an organization. |
| OrganizationalUnit | Tables | A container for storing users, computers, and other account objects. |
| Person | Tables | Contains personal information about a user. |
| PosixAccount | Tables | Represents an abstraction of an account with Portable Operating System Interface (POSIX) attributes. |
| PosixGroup | Tables | Represents an abstraction of a group of accounts. |
| PrintQueue | Tables | Contains information about a print queue. |
| SecurityObject | Tables | This is an auxiliary class that is used to identify security principals. |
| SecurityPrincipal | Tables | Contains the security information for an object. |
| Server | Tables | This class represents a server computer in a site. |
| Site | Tables | A container for storing server objects. Represents a physical location that contains computers. Used to manage replication. |
| Top | Tables | The top level class from which all classes are derived. |
| TrustedDomain | Tables | An object that represents a domain trusted by (or trusting) the local domain. |
| User | Tables | This class is used to store information about an employee or contractor who works for an organization. It is also possible to apply this class to long term visitors. |
| ChangePassword | Stored Procedures | Changes the password of the current user, provided the current password is known. To set the password without a current password (requires an administrator), use ResetPassword. Note that the User set in the connection settings must be a valid DN. Additionally, you must be connected to the server using SSL. |
| CreateTableFromSchema | Stored Procedures | Converts an LDAP RFC 2242 compliant schema into a table. |
| GetAttributes | Stored Procedures | Returns all the attribute names and values of the specified DN. |
| MoveToDN | Stored Procedures | Moves objects from one DN to another one. |
| ResetPassword | Stored Procedures | Resets the password of a specific user specified by DN. Use ChangePassword instead if the current password is to be authenticated first. Note that the User set in the connection settings or the AdminUser, if set when calling this procedure, must be a valid DN. Additionally, you must be connected to the server using SSL. |
Connection Strings
| Name | Description |
| AuthMechanism | The authentication mechanism to be used when connecting to the Active Directory server. |
| AutoCache | Automatically caches the results of SELECT queries into a cache database specified by either CacheLocation or both of CacheConnection and CacheProvider . |
| BaseDN | The base portion of the distinguished name, used for limiting results to specific subtrees. |
| CacheConnection | The connection string for the cache database. This property is always used in conjunction with CacheProvider . Setting both properties will override the value set for CacheLocation for caching data. |
| CacheLocation | Specifies the path to the cache when caching to a file. |
| CacheMetadata | This property determines whether or not to cache the table metadata to a file store. |
| CacheProvider | The name of the provider to be used to cache data. |
| CacheTolerance | The tolerance for stale data in the cache specified in seconds when using AutoCache . |
| ConnectionLifeTime | The maximum lifetime of a connection in seconds. Once the time has elapsed, the connection object is disposed. |
| FirewallPassword | A password used to authenticate to a proxy-based firewall. |
| FirewallPort | The TCP port for a proxy-based firewall. |
| FirewallServer | The name or IP address of a proxy-based firewall. |
| FirewallType | The protocol used by a proxy-based firewall. |
| FirewallUser | The user name to use to authenticate with a proxy-based firewall. |
| FollowReferrals | Whether or not to follow referrals returned by the Active Directory server. |
| FriendlyGUID | Whether to return GUID attribute values in a human readable format. |
| FriendlySID | Whether to return SID attribute values in a human readable format. |
| IntegratedSecurity | Whether or not to use the user's current context when logging in. |
| LDAPVersion | The LDAP version used to connect to and communicate with the server. |
| Location | A path to the directory that contains the schema files defining tables, views, and stored procedures. |
| Logfile | A path to the log file. |
| MaxLogFileCount | A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted. |
| MaxLogFileSize | A string specifying the maximum size in bytes for a log file (for example, 10 MB). When the limit is hit, a new log is created in the same folder with the date and time appended to the end. |
| MaxRows | Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time. |
| Offline | Use offline mode to get the data from the cache instead of the live source. |
| Other | These hidden properties are used only in specific use cases. |
| Password | The password for the distinguished name of the specified user. |
| PoolIdleTimeout | The allowed idle time for a connection before it is closed. |
| PoolMaxSize | The maximum connections in the pool. |
| PoolMinSize | The minimum number of connections in the pool. |
| PoolWaitTime | The max seconds to wait for an available connection. |
| Port | The port the Active Directory server is running on. |
| PseudoColumns | This property indicates whether or not to include pseudo columns as columns to the table. |
| Readonly | You can use this property to enforce read-only access to ActiveDirectory from the provider. |
| RTK | The runtime key used for licensing. |
| Scope | Whether to limit the scope of the search to the whole subtree (BaseDN and all of its descendants), a single level (BaseDN and its direct descendants), or the base object (BaseDN only). |
| Server | The domain name or IP of the Active Directory server. |
| SSLServerCert | The certificate to be accepted from the server when connecting using TLS/SSL. |
| SupportEnhancedSQL | This property enhances SQL functionality beyond what can be supported through the API directly, by enabling in-memory client-side processing. |
| Tables | This property restricts the tables reported to a subset of the available tables. For example, Tables=TableA,TableB,TableC. |
| Timeout | The value in seconds until the timeout error is thrown, canceling the operation. |
| UseConnectionPooling | This property enables connection pooling. |
| UseDefaultDC | Used to connect to the default Domain Controller and authenticate using the current user credentials. |
| User | The distinguished name of a user. |
| Verbosity | The verbosity level that determines the amount of detail included in the log file. |
| Views | Restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC. |