REST LDAP Gateway Configuration
REST LDAP gateway
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.
(Optional) "isSingleValued": true means represent a possibly
multi-valued LDAP attribute as a single value, rather than 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.
"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 mapping exposes a SCIM view of sample 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
}
}
}
},
"contactInformation": {
"object": {
"telephoneNumber": {
"simple": {
"ldapAttribute": "telephoneNumber",
"isSingleValued": true
}
},
"emailAddress": {
"simple": {
"ldapAttribute": "mail",
"isSingleValued": true
}
}
}
}
}
}
}
"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