此内容没有您所选择的语言版本。
12.20. LDAP Translator
12.20.1. LDAP Translator
The LDAP translator exposes an LDAP directory tree relationally with pushdown support for filtering via criteria. This is typically coupled with the LDAP resource adapter.
The LDAP translator is implemented by the
org.teiid.translator.ldap.LDAPExecutionFactory
class and known by the translator type name ldap
.
Note
The resource adapter for this translator is provided by configuring the
ldap
data source in the JBoss EAP instance. See the Red Hat JBoss Data Virtualization Administration and Configuration Guide for more configuration information.
12.20.2. LDAP Translator: Execution Properties
Name | Description | Default |
---|---|---|
SearchDefaultBaseDN | Default Base DN for LDAP Searches | null |
SearchDefaultScope | Default Scope for LDAP Searches. Can be one of SUBTREE_SCOPE, OBJECT_SCOPE, ONELEVEL_SCOPE. | ONELEVEL_SCOPE |
RestrictToObjectClass | Restrict Searches to objectClass named in the Name field for a table | false |
UsePagination | Use a PagedResultsControl to page through large results. This is not supported by all directory servers. | false |
ExceptionOnSizeLimitExceeded | Set to true to throw an exception when a SizeLimitExceededException is received and a LIMIT is not properly enforced. | false |
Note
There are no import settings for the LDAP translator; it also does not provide metadata.
If one of the methods below is not used and the attribute is mapped to a non-array type, then any value may be returned on a read operation. Also insert/update/delete support will not be multi-value aware.
String columns with a default value of "multivalued-concat" will concatenate all attribute values together in alphabetical order using a ? delimiter. If a multivalued attribute does not have a default value of "multivalued-concat", then any value may be returned.
Multiple attribute values may also be supported as an array type. The array type mapping also allows for insert/update operations.
This example shows a DDL with objectClass and uniqueMember as arrays:
create foreign table ldap_groups (objectClass string[], DN string, name string options (nameinsource 'cn'), uniqueMember string[]) options (nameinsource 'ou=groups,dc=teiid,dc=org', updatable true)
The array values can be retrieved with a SELECT. Here is an example insert with array values:
insert into ldap_groups (objectClass, DN, name, uniqueMember) values (('top', 'groupOfUniqueNames'), 'cn=a,ou=groups,dc=teiid,dc=org', 'a', ('cn=Sam Smith,ou=people,dc=teiid,dc=org',))
12.20.3. LDAP Translator: Native Queries
LDAP procedures may optionally have native queries associated with them (see Section 12.7, “Parameterizable Native Queries”). The operation prefix (for example, select;, insert;, update;, delete; - see the native procedure logic below) must be present in the native query, but it will not be issued as part of the query to the source.
The following is an example DDL for an LDAP native procedure:
CREATE FOREIGN PROCEDURE proc (arg1 integer, arg2 string) OPTIONS ("teiid_rel:native-query" 'search;context-name=corporate;filter=(&(objectCategory=person)(objectClass=user)(!cn=$2));count-limit=5;timeout=$1;search-scope=ONELEVEL_SCOPE;attributes=uid,cn') returns (col1 string, col2 string);
Note
Parameter values have reserved characters escaped, but are otherwise directly substituted into the query.
12.20.4. LDAP Translator: Native Procedure
Warning
This feature is turned off by default because of the security risk this exposes to execute any command against the source. To enable this feature, override the translator property called "SupportsNativeQueries" to true. See Section 12.6, “Override Execution Properties”. above.
LDAP translator provides a procedure with name native that gives ability to execute any ad hoc native LDAP queries directly against the source without any JBoss Data Virtualization parsing or resolving. The metadata of this procedure's execution results are not known to JBoss Data Virtualization, and they are returned as object array. Users can use the ARRAYTABLE construct ( Section 2.6.10, “Nested Tables: ARRAYTABLE”) to build tabular output for consumption by client applications. Since there is no known direct query language for LDAP, JBoss Data Virtualization exposes this procedure with a simple query structure as below.
12.20.5. LDAP Translator Example: Search
Example 12.7. Search Example
SELECT x.* FROM (call pm1.native('search;context-name=corporate;filter=(objectClass=*);count-limit=5;timeout=6;search-scope=ONELEVEL_SCOPE;attributes=uid,cn')) w, ARRAYTABLE(w.tuple COLUMNS "uid" string , "cn" string) AS x
The "search" keyword is followed by the below properties. Each property must be delimited by semicolon (;) If a property contains a semicolon (;), it must be escaped by another semicolon. See also Section 12.7, “Parameterizable Native Queries” and the example in Section 12.20.3, “LDAP Translator: Native Queries”.
Name
|
Description
|
Required
|
---|---|---|
context-name
|
LDAP Context name
|
Yes
|
filter
|
query to filter the records in the context
|
No
|
count-limit
|
limit the number of results. same as using LIMIT
|
No
|
timeout
|
Time out the query if not finished in given milliseconds
|
No
|
search-scope
|
LDAP search scope, one of SUBTREE_SCOPE, OBJECT_SCOPE, ONELEVEL_SCOPE
|
No
|
attributes
|
attributes to retrieve
|
Yes
|
12.20.6. LDAP Translator Example: Delete
Example 12.8. Delete Example
SELECT x.* FROM (call pm1.native('delete;uid=doe,ou=people,o=teiid.org')) w, ARRAYTABLE(w.tuple COLUMNS "updatecount" integer) AS x
In the above code, the "delete" keyword is followed by the "DN" string. All the string contents after the "delete;" are used as the DN.
12.20.7. LDAP Translator Example: Create and Update
Example 12.9. Create Example
SELECT x.* FROM (call pm1.native('create;uid=doe,ou=people,o=teiid.org;attributes=one,two,three', 'one', 2, 3.0)) w, ARRAYTABLE(w.tuple COLUMNS "update_count" integer) AS x
In the above code, the "create" keyword is followed by the "DN" string. All the string contents after the "create;" is used as the DN. It also takes one property called "attributes" which is comma separated list of attributes. The values for each attribute is specified as separate argument to the "native" procedure.
Update is similar to create:
Example 12.10. Update Example
SELECT x.* FROM (call pm1.native('update;uid=doe,ou=people,o=teiid.org;attributes=one,two,three', 'one', 2, 3.0)) w, ARRAYTABLE(w.tuple COLUMNS "update_count" integer) AS x
Important
By default, the name of the procedure that executes the queries directly is called native, however this can be changed by overriding an execution property in the
vdb.xml
file. See Section 12.6, “Override Execution Properties”.
12.20.8. LDAP Connector Capabilities Support
LDAP does not provide the same set of functionality as a relational database. The LDAP Connector supports many standard SQL constructs, and performs the job of translating those constructs into an equivalent LDAP search statement. For example, the SQL statement:
SELECT firstname, lastname, guid FROM public_views.people WHERE (lastname='Jones' and firstname IN ('Michael', 'John')) OR guid > 600000
Uses a number of SQL constructs, including:
SELECT
clause support- select individual element support (firstname, lastname, guid)
FROM
supportWHERE
clause criteria support- nested criteria support
- AND, OR support
- Compare criteria (Greater-than) support
IN
support
The LDAP Connector executes LDAP searches by pushing down the equivalent LDAP search filter whenever possible, based on the supported capabilities. JBoss Data Virtualization automatically provides additional database functionality when the LDAP Connector does not explicitly provide support for a given SQL construct. In these cases, the SQL construct cannot be pushed down to the data source, so it will be evaluated in JBoss Data Virtualization, in order to ensure that the operation is performed.
In cases where certain SQL capabilities cannot be pushed down to LDAP, JBoss Data Virtualization pushes down the capabilities that are supported, and fetches a set of data from LDAP. JBoss Data Virtualization then evaluates the additional capabilities, creating a subset of the original data set. Finally, JBoss Data Virtualization will pass the result to the client. It is useful to be aware of unsupported capabilities, in order to avoid fetching large data sets from LDAP when possible.
12.20.9. LDAP Connector Capabilities Support List
The LDAP Connector has these capabilities:
SELECT
queriesSELECT
element pushdown (for example, individual attribute selection)AND
criteria- Compare criteria (e.g. <, <=, >, >=, =, !=)
IN
criteriaLIKE
criteria.OR
criteriaINSERT
,UPDATE
,DELETE
statements (must meet Modeling requirements)
Due to the nature of the LDAP source, the following capability is not supported:
SELECT
queries
The following capabilities are not supported in the LDAP Connector, and will be evaluated by the JBoss Data Virtualization after data is fetched by the connector:
- Functions
- Aggregates
BETWEEN
Criteria- Case Expressions
- Aliased Groups
- Correlated Subqueries
EXISTS
Criteria- Joins
- Inline views
IS NULL
criteriaNOT
criteriaORDER BY
- Quantified compare criteria
- Row Offset
- Searched Case Expressions
- Select Distinct
- Select Literals
UNION
- XA Transactions
The ldap-as-a-datasource quick start shows you how to access data in the OpenLDAP Server. Use the
ldap
translator in the vdb.xml
file.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <vdb name="ldapVDB" version="1"> <model name="HRModel"> <source name="local" translator-name="ldap" connection-jndi-name="java:/ldapDS"/> </model> </vdb>
The translator does not provide a connection to OpenLDAP. Instead, you can use a JCA adapter that uses the Java Naming API. To do so, use the following XML fragment in the
standalone-teiid.xml
file. See a example in JBOSS-HOME/docs/teiid/datasources/ldap
.
<resource-adapter id="ldapQS"> <module slot="main" id="org.jboss.teiid.resource-adapter.ldap"/> <connection-definitions> <connection-definition class-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory" jndi-name="java:/ldapDS" enabled="true" use-java-context="true" pool-name="ldapDS"> <config-property name="LdapAdminUserPassword"> redhat </config-property> <config-property name="LdapAdminUserDN"> cn=Manager,dc=example,dc=com </config-property> <config-property name="LdapUrl"> ldap://localhost:389 </config-property> </connection-definition> </connection-definitions> </resource-adapter>
The code above defines the translator and connector. The LDAP translator can derive the metadata based on existing Users/Groups in the LDAP Server. You need the user to define the metadata. For example, you can define a schema using DDL:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <vdb name="ldapVDB" version="1"> <model name="HRModel"> <metadata type="DDL"><![CDATA[ CREATE FOREIGN TABLE HR_Group ( DN string options (nameinsource 'dn'), SN string options (nameinsource 'sn'), UID string options (nameinsource 'uid'), MAIL string options (nameinsource 'mail'), NAME string options (nameinsource 'cn') ) OPTIONS(nameinsource 'ou=HR,dc=example,dc=com', updatable true); </metadata> </model> </vdb>
When the SELECT operation is executed against a table using JDV, it retrieves the users and groups from the LDAP Server:
SELECT * FROM HR_Group
12.20.10. LDAP Attribute Datatype Support
LDAP providers currently return attribute value types of
java.lang.String
and byte[]
, and do not support the ability to return any other attribute value type. The LDAP Connector currently supports attribute value types of java.lang.String
only. Therefore, all attributes are modeled using the String datatype in Teiid Designer.
Conversion functions that are available in JBoss Data Virtualization allow you to use models that convert a String value from LDAP into a different data type. Some conversions may be applied implicitly, and do not require the use of any conversion functions. Other conversions must be applied explicitly, via the use of
CONVERT
functions.
Since the
CONVERT
functions are not supported by the underlying LDAP system, they will be evaluated in JBoss Data Virtualization. Therefore, if any criteria is evaluated against a converted datatype, that evaluation cannot be pushed to the data source, since the native type is String.
Note
When converting from String to other types, be aware that criteria against that new data type will not be pushed down to the LDAP data source. This may decrease performance for certain queries.
As an alternative, the data type can remain a string and the client application can make the conversion, or the client application can circumvent any LDAP supports <= and >=, but has no equivalent for < or >. In order to support < or > pushdown to the source, the LDAP Connector will translate < to <=, and it will translate > to >=.
When using the LDAP Connector, be aware that strictly-less-than and strictly-greater-than comparisons will behave differently than expected. It is advisable to use <= and >= for queries against an LDAP based data source, since this has a direct mapping to comparison operators in LDAP.
12.20.11. LDAP: Testing Your Connector
You must define LDAP Connector properties accurately or the JBoss Data Virtualization server will return unexpected results, or none at all. As you deploy the connector in Console, improper configuration can lead to problems when you attempt to start your connector. You can test your LDAP Connector in Teiid Designer prior to Console deployment by submitting queries at modeling time for verification.
12.20.12. LDAP: Console Deployment Issues
The Console shows an Exception That Says Error Synchronizing the Server
If you receive an exception when you synchronize the server and your LDAP Connector is the only service that does not start, it means that there was a problem starting the connector. Verify whether you have correctly typed in your connector properties to resolve this issue.