REST LDAP Configuration
REST
HTTP
OpenDJ offers two alternatives for RESTful access to directory
data.
OpenDJ directory server has an HTTP connection handler that exposes
the RESTful API over HTTP (or HTTPS). You configure the mapping between
JSON resources and LDAP entries by editing the configuration file for the
HTTP connection handler, by default
/path/to/OpenDJ/config/http-config.json.
The OpenDJ REST LDAP gateway runs as a Servlet independent from your
directory service. You configure the gateway to access your directory service
by editing opendj-rest2ldap-servlet.json where you
deploy the gateway web application.
The JSON format configuration can hold the following configuration
objects.
"primaryLDAPServers" (required)
The gateway accesses this array of LDAP servers before failing over
to the secondary LDAP servers. These might be LDAP servers in the same
data center for example.
{
"primaryLDAPServers": [
{
"hostname": "local1.example.com",
"port": 1389
},
{
"hostname": "local2.example.com",
"port": 1389
}
]
}
By default, the gateway connects to the directory server listening
on port 1389 on the local host.
"authentication" (required)
The gateway authenticates by simple bind using the credentials
specified.
{
"authentication": {
"bindDN": "cn=Directory Manager",
"password": "password"
}
}
"mappings"
For each gateway collection URI such as /users and
/groups, you configure a mapping between the JSON
resource returned by the gateway, and the LDAP entry returned by the
directory service.
Each mapping has a number of configuration elements.
"baseDN" (required)
The base DN where LDAP entries are found for this mapping.
"attributes" (required)
How the JSON resource fields map to attributes on LDAP
entries, each taking the form "field-name":
mapping-object. A number of
mapping-objects are supported.
"constant"
Maps a single JSON attribute to a fixed value.
This can be useful as in the default case where each JSON
resource "schemas" takes the SCIM URN, and so the value is not related
to the underlying LDAP entries.
{
"schemas": {
"constant": [
"urn:scim:schemas:core:1.0"
]
}
}
"simple"
Maps a JSON field to an LDAP attribute.
Simple mappings are used where the correspondence between JSON
fields and LDAP attributes is one-to-one.
{
"userName": {
"simple": {
"ldapAttribute": "mail",
"isSingleValued": true,
"writability": "readOnly"
}
}
}
Simple mappings can take a number of fields.
(Required) "ldapAttribute": the name of LDAP attribute.
(Optional) "defaultValue": the JSON value if no LDAP attribute
is available on the entry.
(Optional) "isBinary": true means the LDAP attribute is
binary and the JSON field gets the base64-encoded value.
(Optional) "isRequired": true means the LDAP attribute is
mandatory and must be provided to create the resource; false means
it is optional.
(Optional) "isSingleValued": true means represent a possibly
multi-valued LDAP attribute as a single value; false means represent
it as an array of values.
(Optional) "writability": indicates whether the LDAP attribute
supports updates. This field can take the following values.
"createOnly": This attribute can be set only when the
entry is created. Attempts to update this attribute thereafter
result in errors.
"createOnlyDiscardWrites": This attribute can be set only
when the entry is created. Attempts to update this attribute
thereafter do not result in errors. Instead the update value
is discarded.
"readOnly": This attribute cannot be updated. Attempts to
update this attribute result in errors.
"readOnlyDiscardWrites": This attribute cannot be updated.
Attempts to update this attribute do not result in errors. Instead
the update value is discarded.
"readWrite": This attribute can be set at creation and
updated thereafter.
"object"
Maps a JSON object to LDAP attributes.
This mapping lets you create JSON objects whose fields themselves
have mappings to LDAP attributes.
"reference"
Maps a JSON field to an LDAP entry found by reference.
This mapping works for LDAP attributes whose values reference
other entries. This is shown in the following example from the default
configuration. The LDAP manager attribute values
are user entry DNs. Here, the JSON manager field
takes the user ID and name from the entry referenced by the LDAP
attribute. On updates, changes to the JSON manager
_id affect which manager entry is referenced, yet
any changes to the manager's name are discarded, because changing
managers only affects which user entry to point to, not the referenced
user's name.
{
"manager": {
"reference": {
"ldapAttribute": "manager",
"baseDN": "ou=people,dc=example,dc=com",
"primaryKey": "uid",
"mapper": {
"object": {
"_id": {
"simple": {
"ldapAttribute": "uid",
"isSingleValued": true,
"isRequired": true
}
},
"displayName": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"writability": "readOnlyDiscardWrites"
}
}
}
}
}
}
}
Babs Jensen's manager in the sample LDAP data is Torrey Rigden,
who has user ID trigden. Babs's entry has
manager: uid=trigden,ou=People,dc=example,dc=com.
With this mapping, the resulting JSON field is the following.
{
"manager": [
{
"_id": "trigden",
"displayName": "Torrey Rigden"
}
]
}
Reference mapping objects have the following fields.
(Required) "baseDN": indicates the base LDAP DN under which
to find entries referenced by the JSON resource.
(Required) "ldapAttribute": specifies the LDAP attribute in
the entry underlying the JSON resource whose value points to the
referenced entry.
(Required) "mapper": describes how the referenced entry
content maps to the content of this JSON field.
(Required) "primaryKey": indicates which LDAP attribute in
the mapper holds the primary key to the referenced entry.
(Optional) "filter": specifies the LDAP filter to use to
search for the referenced entry. The default is
"(objectClass=*)".
(Optional) "isRequired": true means the LDAP attribute is
mandatory and must be provided to create the resource; false means
it is optional.
(Optional) "isSingleValued": true means represent a possibly
multi-valued LDAP attribute as a single value; false means represent
it as an array of values.
(Optional) "scope": indicates the scope of the LDAP search to
find the referenced entry. The default is
"SearchScope.WHOLE_SUBTREE".
(Optional) "writability": indicates whether the mapping
supports updates, as described above for the simple mapping. The
default is "readWrite".
"namingStrategy" (required)
The approach used to map LDAP entry names to JSON resources. One
of the following.
RDN and resource ID are both derived from a single user attribute
in the LDAP entry, as in the following example, where the
uid attribute is the RDN and its value is the
JSON resource ID.
{
"namingStrategy": {
"strategy": "clientDNNaming",
"dnAttribute": "uid"
}
}
RDN and resource ID are derived from separate user attributes in
the LDAP entry, as in the following example where the RDN attribute is
uid but the JSON resource ID is the value of the
mail attribute.
{
"namingStrategy": {
"strategy": "clientNaming",
"dnAttribute": "uid",
"idAttribute": "mail"
}
}
RDN is derived from a user attribute and the resource ID from an
operational attribute in the LDAP entry, as in the following example,
where the RDN attribute is uid but the JSON resource
ID is the value of the entryUUID operational
attribute.
{
"namingStrategy": {
"strategy": "serverNaming",
"dnAttribute": "uid",
"idAttribute": "entryUUID"
}
}
"additionalLDAPAttributes" (optional, but necessary)
LDAP attributes to include during LDAP add operations as an
array of type-value lists, such as the following example.
{
"additionalLDAPAttributes": [
{
"type": "objectClass",
"values": [
"top",
"person",
"organizationalPerson",
"inetOrgPerson"
]
}
]
}
This configuration element is useful to set LDAP object classes
for example, which are not present in JSON resources.
"etagAttribute" (optional)
The LDAP attribute to use for multi-version concurrency control
(MVCC).
Default: "etag"
"readOnUpdatePolicy" (optional)
The policy used to read an entry before it is deleted, or to
read an entry after it is added or modified. One of the following.
"controls": use RFC 4527 read-entry controls to reflect the
state of the resource at the time the update was performed.
The directory service must support RFC 4527.
This is the default if no policy is specified.
"disabled": do not read the entry or return the resource on
update.
"search": perform an LDAP search to retrieve the entry before
deletion or after it is added or modified.
The JSON resource returned might differ from the LDAP entry that
was updated.
The default mappings expose a SCIM view of user and group data.
{
"/users": {
"baseDN": "ou=people,dc=example,dc=com",
"readOnUpdatePolicy": "controls",
"additionalLDAPAttributes": [
{
"type": "objectClass",
"values": [
"top",
"person",
"organizationalPerson",
"inetOrgPerson"
]
}
],
"namingStrategy": {
"strategy": "clientDNNaming",
"dnAttribute": "uid"
},
"etagAttribute": "etag",
"attributes": {
"schemas": {
"constant": [
"urn:scim:schemas:core:1.0"
]
},
"_id": {
"simple": {
"ldapAttribute": "uid",
"isSingleValued": true,
"isRequired": true,
"writability": "createOnly"
}
},
"_rev": {
"simple": {
"ldapAttribute": "etag",
"isSingleValued": true,
"writability": "readOnly"
}
},
"userName": {
"simple": {
"ldapAttribute": "mail",
"isSingleValued": true,
"writability": "readOnly"
}
},
"displayName": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"isRequired": true
}
},
"name": {
"object": {
"givenName": {
"simple": {
"ldapAttribute": "givenName",
"isSingleValued": true
}
},
"familyName": {
"simple": {
"ldapAttribute": "sn",
"isSingleValued": true,
"isRequired": true
}
}
}
},
"manager": {
"reference": {
"ldapAttribute": "manager",
"baseDN": "ou=people,dc=example,dc=com",
"primaryKey": "uid",
"mapper": {
"object": {
"_id": {
"simple": {
"ldapAttribute": "uid",
"isSingleValued": true,
"isRequired": true
}
},
"displayName": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"writability": "readOnlyDiscardWrites"
}
}
}
}
}
},
"groups": {
"reference": {
"ldapAttribute": "isMemberOf",
"baseDN": "ou=groups,dc=example,dc=com",
"writability": "readOnly",
"primaryKey": "cn",
"mapper": {
"object": {
"_id": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true
}
}
}
}
}
},
"contactInformation": {
"object": {
"telephoneNumber": {
"simple": {
"ldapAttribute": "telephoneNumber",
"isSingleValued": true
}
},
"emailAddress": {
"simple": {
"ldapAttribute": "mail",
"isSingleValued": true
}
}
}
},
"meta": {
"object": {
"created": {
"simple": {
"ldapAttribute": "createTimestamp",
"isSingleValued": true,
"writability": "readOnly"
}
},
"lastModified": {
"simple": {
"ldapAttribute": "modifyTimestamp",
"isSingleValued": true,
"writability": "readOnly"
}
}
}
}
}
},
"/groups": {
"baseDN": "ou=groups,dc=example,dc=com",
"readOnUpdatePolicy": "controls",
"additionalLDAPAttributes": [
{
"type": "objectClass",
"values": [
"top",
"groupOfUniqueNames"
]
}
],
"namingStrategy": {
"strategy": "clientDNNaming",
"dnAttribute": "cn"
},
"etagAttribute": "etag",
"attributes": {
"schemas": {
"constant": [
"urn:scim:schemas:core:1.0"
]
},
"_id": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"isRequired": true,
"writability": "createOnly"
}
},
"_rev": {
"simple": {
"ldapAttribute": "etag",
"isSingleValued": true,
"writability": "readOnly"
}
},
"displayName": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"isRequired": true,
"writability": "readOnly"
}
},
"members": {
"reference": {
"ldapAttribute": "uniqueMember",
"baseDN": "dc=example,dc=com",
"primaryKey": "uid",
"mapper": {
"object": {
"_id": {
"simple": {
"ldapAttribute": "uid",
"isSingleValued": true,
"isRequired": true
}
},
"displayName": {
"simple": {
"ldapAttribute": "cn",
"isSingleValued": true,
"writability": "readOnlyDiscardWrites"
}
}
}
}
}
},
"meta": {
"object": {
"created": {
"simple": {
"ldapAttribute": "createTimestamp",
"isSingleValued": true,
"writability": "readOnly"
}
},
"lastModified": {
"simple": {
"ldapAttribute": "modifyTimestamp",
"isSingleValued": true,
"writability": "readOnly"
}
}
}
}
}
}
}
"secondaryLDAPServers" (optional)
The gateway accesses this array of LDAP servers if primary LDAP
servers cannot be contacted. These might be LDAP servers in the same
data center for example.
{
"secondaryLDAPServers": [
{
"hostname": "remote1.example.com",
"port": 1389
},
{
"hostname": "remote2.example.com",
"port": 1389
}
]
}
No secondary LDAP servers are configured by default.
"connectionPoolSize" (optional)
The gateway creates connection pools to the primary and secondary
LDAP servers that maintain up to connectionPoolSize
connections to the servers.
Default: 10
"connectionPoolSize": 10
"heartBeatIntervalSeconds" (optional)
The gateway tests its connections every
heartBeatIntervalSeconds seconds to detect whether the
connection is still alive.
Default: 30 (seconds)
"heartBeatIntervalSeconds": 30