<?xml version="1.0" encoding="UTF-8"?>

<appendix xml:id='appendix-rest2ldap'

xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>REST LDAP Configuration</title>

<indexterm><primary>REST</primary></indexterm>

<indexterm><primary>HTTP</primary></indexterm>

<itemizedlist>

<para>OpenDJ offers two alternatives for RESTful access to directory

data.</para>

<listitem>

<para>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

<filename>/path/to/opendj/config/http-config.json</filename>.</para>

</listitem>

<listitem>

<para>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 <filename>opendj-rest2ldap-servlet.json</filename> where you

deploy the gateway web application.</para>

</listitem>

</itemizedlist>

<variablelist>

<para>The JSON format configuration can hold the following configuration

objects. Some of the configuration settings are available only in the REST

LDAP gateway configuration. The order here is the order shown in the default

configuration file.</para>

<para>Interface stability: <link xlink:href="reference#interface-stability"

xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"

>Evolving</link></para>

<varlistentry>

<term>"ldapConnectionFactories" (required, gateway only)</term>

<listitem>

<para>Configures how the gateway connects to LDAP servers. This entire

configuration object applies only to the REST LDAP gateway.</para>

<variablelist>

<para>Configures at least a connection factory for unauthenticated

connections that are used for bind requests. By default, also configures a

factory for authenticated connections that are used for searches during

authentication and for proxied authorization operations.</para>

<para>The default configuration is set to connect to a local directory

server listening for LDAP connections on port 1389, authenticating as the

root DN user <literal>cn=Directory Manager</literal>, with the password

<literal>password</literal>.</para>

<varlistentry>

<term>"default"</term>

<listitem>

<para>Configures the unauthenticated connection factory for bind

operations.</para>

<variablelist>

<varlistentry>

<term>"connectionPoolSize" (optional)</term>

<listitem>

<para>The gateway creates connection pools to the primary and

secondary LDAP servers that maintain up to

<literal>connectionPoolSize</literal> connections to the

servers.</para>

<para>Default: 24</para>

<programlisting language="javascript">"connectionPoolSize": 24</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term>"connectionSecurity" (optional)</term>

<listitem>

<para>Whether connections to LDAP servers should be secured by using

SSL or StartTLS. The following values are supported.</para>

<itemizedlist>

<listitem>

<para>"none" (default) means connections use plain LDAP and are

not secured.</para>

</listitem>

<listitem>

<para>"ssl" means connections are secured using LDAPS.</para>

</listitem>

<listitem>

<para>"startTLS" means connections are secured using LDAP and

StartTLS.</para>

</listitem>

</itemizedlist>

<para>If you set "connectionSecurity", also review the

"trustManager" and "fileBasedTrustManager*" settings.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"heartBeatIntervalSeconds" (optional)</term>

<listitem>

<para>The gateway tests its connections every

<literal>heartBeatIntervalSeconds</literal> to detect whether

the connection is still alive. The first test is performed

immediately when the gateway gets a connection. Subsequent tests

follow every <literal>heartBeatIntervalSeconds</literal>.</para>

<para>Default: 30 (seconds)</para>

<programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term>"heartBeatTimeoutMilliSeconds" (optional)</term>

<listitem>

<para>When the gateway tests a connection, if the heartbeat does not come back after

<literal>heartBeatTimeoutMilliSeconds</literal> the connection is marked as closed.</para>

<para>Default: 500 (milliseconds)</para>

<programlisting language="javascript">"heartBeatTimeoutMilliSeconds": 500</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term>"fileBasedTrustManagerFile" (optional)</term>

<listitem>

<para>If "trustManager" is set to "file", then this setting

configures the location of the trust store file.</para>

<para>Default: "/path/to/truststore"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"fileBasedTrustManagerPassword" (optional)</term>

<listitem>

<para>If "trustManager" is set to "file", then this setting

specifies the trust store password.</para>

<para>Default: "password"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"fileBasedTrustManagerType" (optional)</term>

<listitem>

<para>If "trustManager" is set to "file", then this setting

configures the format for the data in the trust store file specified

by the "fileBasedTrustManagerFile" setting. Formats include the

following, though other implementations might be supported as well

depending on the Java environment.</para>

<itemizedlist>

<listitem>

<para>"JKS" (default) specifies Java Key Store format.</para>

</listitem>

<listitem>

<para>"PKCS12" specifies Public-Key Cryptography Standards 12

format.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"primaryLDAPServers" (required)</term>

<listitem>

<para>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.</para>

<programlisting language="javascript">{

"primaryLDAPServers": [

{

"hostname": "local1.example.com",

"port": 1389

},

{

"hostname": "local2.example.com",

"port": 1389

}

]

}</programlisting>

<para>By default, the gateway connects to the directory server

listening on port 1389 on the local host.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"secondaryLDAPServers" (optional)</term>

<listitem>

<para>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.</para>

<programlisting language="javascript">{

"secondaryLDAPServers": [

{

"hostname": "remote1.example.com",

"port": 1389

},

{

"hostname": "remote2.example.com",

"port": 1389

}

]

}</programlisting>

<para>No secondary LDAP servers are configured by default.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"trustManager" (optional)</term>

<listitem>

<para>If "connectionSecurity" is set to "ssl" or "startTLS", then

this setting configures how the LDAP servers are trusted. This

setting is ignored if "connectionSecurity" is set to "none".</para>

<itemizedlist>

<listitem>

<para>"file" means trust the LDAP server certificate if it is

signed by a Certificate Authority (CA) trusted according to the

file-based trust store configured with the "fileBasedTrustManager*"

settings.</para>

</listitem>

<listitem>

<para>"jvm" means trust the LDAP server certificate if it is signed

by a CA trusted by the Java environment.</para>

</listitem>

<listitem>

<para>"trustAll" (default) means blindly trust all LDAP server

certificates.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

<varlistentry>

<term>"root"</term>

<listitem>

<para>Configures the authenticated connection factory.</para>

<variablelist>

<varlistentry>

<term>"inheritFrom" (optional)</term>

<listitem>

<para>Identifies the unauthenticated connection factory from which

to inherit settings. If this connection factory does not inherit from

another configuration object, then you must specify the configuration

here.</para>

<para>Default: "default"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"authentication" (required)</term>

<listitem>

<para>The gateway authenticates by simple bind using the credentials

specified.</para>

<programlisting language="javascript">{

"authentication": {

"bindDN": "cn=Directory Manager",

"password": "password"

}

}</programlisting>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

<varlistentry>

<term>"authenticationFilter" (required)</term>

<listitem>

<para>Configures the REST LDAP authentication filter. If the configuration

is not present, the filter is disabled.</para>

<para>The default configuration allows HTTP Basic authentication where user

entries are <literal>inetOrgPerson</literal> entries expected to have

<literal>uid=<replaceable>username</replaceable></literal>, and to be found

under <literal>ou=people,dc=example,dc=com</literal>. The default

configuration also allows alternative, HTTP header based authentication in

the style of OpenIDM.</para>

<para>By default, authentication is required both for the gateway and for

the HTTP connection handler. When the HTTP connection handler property

<literal>authentication-required</literal> is set to

<literal>false</literal> (default: <literal>true</literal>), the HTTP

connection handler accepts both authenticated and unauthenticated requests.

All requests are subject to access control and resource limit settings in

the same way as LDAP client requests to the directory server. The

<literal>authentication-required</literal> setting can be overridden by the

global configuration property

<literal>reject-unauthenticated-requests</literal> (default:

<literal>false</literal>), described in the section on <link

xlink:show="new" xlink:href="admin-guide#restrict-clients"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Restricting

Client Access</citetitle></link>.</para>

<para>To protect passwords, configure HTTPS for the HTTP connection handler

or for the container where the REST LDAP gateway runs.</para>

<variablelist>

<para>The filter has the following configuration fields.</para>

<varlistentry>

<term>"supportHTTPBasicAuthentication"</term>

<listitem>

<para>Whether to support HTTP Basic authentication. If this is set to

<literal>true</literal>, then the entry corresponding to the user name

is found using the "searchBaseDN", "searchScope", and

"searchFilterTemplate" settings.</para>

<para>Default: <literal>true</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>"supportAltAuthentication"</term>

<listitem>

<para>Whether to allow alternative, HTTP header based authentication. If

this is set to <literal>true</literal>, then the headers to use are

specified in the "altAuthenticationUsernameHeader" and

"altAuthenticationPasswordHeader" values, and the bind DN is resolved

using the "searchFilterTemplate" value.</para>

<para>Default: <literal>true</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>"altAuthenticationUsernameHeader"</term>

<listitem>

<para>Specifies the HTTP header containing the username for

authentication when alternative, HTTP-header based authentication is

allowed.</para>

<para>Default: "X-OpenIDM-Username"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"altAuthenticationPasswordHeader"</term>

<listitem>

<para>Specifies the HTTP header containing the password for

authentication when alternative, HTTP-header based authentication is

allowed.</para>

<para>Default: "X-OpenIDM-Password"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"reuseAuthenticatedConnection" (gateway only)</term>

<listitem>

<para>Whether to use authenticated LDAP connections for subsequent LDAP

operations. If this is set to <literal>true</literal>, the gateway does

not need its own connection factory, nor does it need to use proxied

authorization for LDAP operations. Instead, it performs the operations

as the user on the authenticated connection.</para>

<para>Default: <literal>true</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>"method" (gateway only)</term>

<listitem>

<para>Specifies the authentication method used by the gateway. The

following values are supported.</para>

<itemizedlist>

<listitem>

<para>"search-simple" (default) means the user name is resolved to

an LDAP bind DN by a search using the "searchFilterTemplate" value.</para>

</listitem>

<listitem>

<para>"sasl-plain" means the user name is resolved to an

authorization ID (authzid) using the "saslAuthzIdTemplate" value.</para>

</listitem>

<listitem>

<para>"simple" means the user name is the LDAP bind DN.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"bindLDAPConnectionFactory" (gateway only)</term>

<listitem>

<para>Identifies the factory providing connections used for bind

operations to authenticate users to LDAP servers.</para>

<para>Default: "default"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"saslAuthzIdTemplate" (gateway only)</term>

<listitem>

<para>Sets how to resolve the authorization ID when the authentication

"method" is set to "sasl-plain", substituting <literal>%s</literal>

in the template with the user name provided. The user name provided by

is DN escaped before the value is returned.</para>

<para>Default: "dn:uid=%s,ou=people,dc=example,dc=com"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"searchLDAPConnectionFactory" (gateway only)</term>

<listitem>

<para>Identifies the factory providing connections used to find

user entries in the directory server when the "method" is set to

"search-simple".</para>

<para>Default: "root"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"searchBaseDN"</term>

<listitem>

<para>Sets the base DN to search for user entries. For the gateway,

this applies when the "method" is set to "search-simple". This always

applies for the HTTP connection handler.</para>

<para>Default: "ou=people,dc=example,dc=com"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"searchScope"</term>

<listitem>

<para>Sets the search scope below the base DN such as "sub" (subtree

search) or "one" (one-level search) to search for user entries. For the

gateway, this applies when the "method" is set to "search-simple". This

always applies for the HTTP connection handler.</para>

<para>Default: "sub"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"searchFilterTemplate"</term>

<listitem>

<para>Sets the search filter used to find the user entry, substituting

<literal>%s</literal> in the template with the user name provided. The

user name provided by is DN escaped before the value is returned. For

the gateway, this applies when the "method" is set to "search-simple".

This always applies for the HTTP connection handler.</para>

<para>Default: "(&amp;(objectClass=inetOrgPerson)(uid=%s))"</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

<varlistentry>

<term>"servlet" (required)</term>

<listitem>

<para>Configures how HTTP resources map to LDAP entries, and for the gateway

how to connect to LDAP servers and how to use proxied authorization.</para>

<para>The default gateway configuration tries to reuse authenticated

connections for LDAP operations, falling back to a connection authenticated

as root DN using proxied authorization for LDAP operations.</para>

<variablelist>

<varlistentry>

<term>"ldapConnectionFactory" (gateway only)</term>

<listitem>

<para>Specifies the connection factory used by the gateway to perform

LDAP operations if an authenticated connection is not passed from the

authentication filter according to the setting for

"reuseAuthenticatedConnection".</para>

<para>Default: "root"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"authorizationPolicy" (gateway only)</term>

<listitem>

<para>Specifies how to handle LDAP authorization. The following values

are supported.</para>

<itemizedlist>

<listitem>

<para>"proxy" (default) means use proxied authorization when no

authenticated connection is provided for reuse, resolving the

authorization ID according to the setting for

"proxyAuthzIdTemplate".</para>

</listitem>

<listitem>

<para>"none" means do not use proxied authorization and do not reuse

authenticated connections, but instead use connections from the

factory specified in "ldapConnectionFactory".</para>

</listitem>

<listitem>

<para>"reuse" means reuse an authenticated connection passed by the

filter, and fail if no connection was passed by the filter.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"proxyAuthzIdTemplate" (gateway only)</term>

<listitem>

<para>Specifies the template to derive the authorization ID from the

security context created during authentication. Use

<literal>{dn}</literal> to indicate the user's bind DN or

<literal>{id}</literal> to indicate the user name provided for

authentication.</para>

<para>Default: "dn:{dn}"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"mappings"</term>

<listitem>

<para>For each collection URI such as <literal>/users</literal> and

<literal>/groups</literal>, you configure a mapping between the JSON

resource returned over HTTP, and the LDAP entry returned by the

directory service.</para>

<variablelist>

<para>Each mapping has a number of configuration elements.</para>

<varlistentry>

<term>"baseDN" (required)</term>

<listitem>

<para>The base DN where LDAP entries are found for this mapping.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"readOnUpdatePolicy" (optional)</term>

<listitem>

<para>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.</para>

<itemizedlist>

<listitem>

<para>"controls": (default) use RFC 4527 read-entry controls to

reflect the state of the resource at the time the update was

performed.</para>

<para>The directory service must support RFC 4527.</para>

</listitem>

<listitem>

<para>"disabled": do not read the entry or return the resource on

update.</para>

</listitem>

<listitem>

<para>"search": perform an LDAP search to retrieve the entry before

deletion or after it is added or modified.</para>

<para>The JSON resource returned might differ from the LDAP entry

that was updated.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"useSubtreeDelete" (required)</term>

<listitem>

<para>Whether to use the LDAP Subtree Delete Request Control (OID:

<literal>1.2.840.113556.1.4.805</literal>) for LDAP delete operations

resulting from delete operations on resources.</para>

<para>Default: <literal>false</literal>. The default configuration

uses <literal>false</literal>.</para>

<para>Set this to <literal>true</literal> if you want this behavior,

if your directory server supports the control, and if clients that

request delete operations have access to use the control.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"usePermissiveModify" (required)</term>

<listitem>

<para>Whether to use the LDAP Permissive Modify Request Control (OID:

<literal>1.2.840.113556.1.4.1413</literal>) for LDAP modify operations

resulting from patch and update operations on resources.</para>

<para>Default: <literal>false</literal>. The default configuration

uses <literal>true</literal>.</para>

<para>Set this to <literal>false</literal> when using the gateway if

your directory server does not support the control.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"etagAttribute" (optional)</term>

<listitem>

<para>The LDAP attribute to use for multi-version concurrency control

(MVCC).</para>

<para>Default: "etag"</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"namingStrategy" (required)</term>

<listitem>

<para>

The approach used to map LDAP entry names to JSON resources.

</para>

<para>

LDAP entries mapped to JSON resources

must be immediate subordinates of the mapping's "baseDN".

</para>

<para>

The following naming strategies are supported.

</para>

<itemizedlist>

<listitem>

<para>RDN and resource ID are both derived from a single user

attribute in the LDAP entry, as in the following example, where the

<literal>uid</literal> attribute is the RDN and its value is the

JSON resource ID.</para>

<programlisting language="javascript">{

"namingStrategy": {

"strategy": "clientDNNaming",

"dnAttribute": "uid"

}

}</programlisting>

</listitem>

<listitem>

<para>RDN and resource ID are derived from separate user attributes

in the LDAP entry, as in the following example where the RDN

attribute is <literal>uid</literal> but the JSON resource ID is the

value of the <literal>mail</literal> attribute.</para>

<programlisting language="javascript">{

"namingStrategy": {

"strategy": "clientNaming",

"dnAttribute": "uid",

"idAttribute": "mail"

}

}</programlisting>

</listitem>

<listitem>

<para>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 <literal>uid</literal> but the

JSON resource ID is the value of the <literal>entryUUID</literal>

operational attribute.</para>

<programlisting language="javascript">{

"namingStrategy": {

"strategy": "serverNaming",

"dnAttribute": "uid",

"idAttribute": "entryUUID"

}

}</programlisting>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"additionalLDAPAttributes" (optional, but necessary)</term>

<listitem>

<para>LDAP attributes to include during LDAP add operations as an

array of type-value lists, such as the following example.</para>

<programlisting language="javascript">{

"additionalLDAPAttributes": [

{

"type": "objectClass",

"values": [

"top",

"person",

"organizationalPerson",

"inetOrgPerson"

]

}

]

}</programlisting>

<para>This configuration element is useful to set LDAP object classes

for example, which are not present in JSON resources.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"attributes" (required)</term>

<listitem>

<para>How the JSON resource fields map to attributes on LDAP

entries, each taking the form "<replaceable>field-name</replaceable>":

<replaceable>mapping-object</replaceable>. A number of

<replaceable>mapping-object</replaceable>s are supported.</para>

<variablelist>

<varlistentry>

<term>"constant"</term>

<listitem>

<para>Maps a single JSON attribute to a fixed value.</para>

<para>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.</para>

<programlisting language="javascript">{

"schemas": {

"constant": [

"urn:scim:schemas:core:1.0"

]

}

}</programlisting>

</listitem>

</varlistentry>

<varlistentry>

<term>"simple"</term>

<listitem>

<para>Maps a JSON field to an LDAP attribute.</para>

<para>Simple mappings are used where the correspondence between

JSON fields and LDAP attributes is one-to-one.</para>

<programlisting language="javascript">{

"userName": {

"simple": {

"ldapAttribute": "mail",

"isSingleValued": true,

"writability": "readOnly"

}

}

}</programlisting>

<itemizedlist>

<para>Simple mappings can take a number of fields.</para>

<listitem>

<para>(Required) "ldapAttribute": the name of LDAP attribute.</para>

</listitem>

<listitem>

<para>(Optional) "defaultJSONValue": the JSON value if no LDAP

attribute is available on the entry.</para>

<para>No default is set if this is omitted.</para>

</listitem>

<listitem>

<para>(Optional) "isBinary": true means the LDAP attribute is

binary and the JSON field gets the base64-encoded value.</para>

<para>Default: <literal>false</literal></para>

</listitem>

<listitem>

<para>(Optional) "isRequired": true means the LDAP attribute is

mandatory and must be provided to create the resource; false

means it is optional.</para>

<para>Default: <literal>false</literal></para>

</listitem>

<listitem>

<para>(Optional) "isSingleValued": true means represent a

possibly multi-valued LDAP attribute as a single value; false

means represent it as an array of values.</para>

<para>Default: determine the representation based on the LDAP

schema, so SINGLE-VALUE attributes take single values, and

multi-valued attributes take arrays.</para>

</listitem>

<listitem>

<para>(Optional) "writability": indicates whether the LDAP

attribute supports updates. This field can take the following

values.</para>

<itemizedlist>

<listitem>

<para>"createOnly": This attribute can be set only when the

entry is created. Attempts to update this attribute thereafter

result in errors.</para>

</listitem>

<listitem>

<para>"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.</para>

</listitem>

<listitem>

<para>"readOnly": This attribute cannot be written. Attempts to

write this attribute result in errors.</para>

</listitem>

<listitem>

<para>"readOnlyDiscardWrites": This attribute cannot be written.

Attempts to write this attribute do not result in errors.

Instead the value to write is discarded.</para>

</listitem>

<listitem>

<para>"readWrite": (default) This attribute can be set at

creation and updated thereafter.</para>

</listitem>

</itemizedlist>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

<varlistentry>

<term>"object"</term>

<listitem>

<para>Maps a JSON object to LDAP attributes.</para>

<para>This mapping lets you create JSON objects whose fields

themselves have mappings to LDAP attributes.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>"reference"</term>

<listitem>

<para>Maps a JSON field to an LDAP entry found by reference.</para>

<para>This mapping works for LDAP attributes whose values reference

other entries. This is shown in the following example from the

default configuration. The LDAP <literal>manager</literal>

attribute values are user entry DNs. Here, the JSON

<literal>manager</literal> field takes the user ID and name from

the entry referenced by the LDAP attribute. On updates, changes

to the JSON manager <literal>_id</literal> 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.</para>

<programlisting language="javascript">{

"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"

}

}

}

}

}

}

}</programlisting>

<para>Babs Jensen's manager in the sample LDAP data is Torrey

Rigden, who has user ID <literal>trigden</literal>. Babs's entry has

<literal>manager: uid=trigden,ou=People,dc=example,dc=com</literal>.

With this mapping, the resulting JSON field is the following.</para>

<programlisting language="javascript">{

"manager": [

{

"_id": "trigden",

"displayName": "Torrey Rigden"

}

]

}</programlisting>

<itemizedlist>

<para>Reference mapping objects have the following fields.</para>

<listitem>

<para>(Required) "baseDN": indicates the base LDAP DN under which

to find entries referenced by the JSON resource.</para>

</listitem>

<listitem>

<para>(Required) "ldapAttribute": specifies the LDAP attribute in

the entry underlying the JSON resource whose value points to the

referenced entry.</para>

</listitem>

<listitem>

<para>(Required) "mapper": describes how the referenced entry

content maps to the content of this JSON field.</para>

</listitem>

<listitem>

<para>(Required) "primaryKey": indicates which LDAP attribute in

the mapper holds the primary key to the referenced entry.</para>

</listitem>

<listitem>

<para>(Optional) "isRequired": true means the LDAP attribute is

mandatory and must be provided to create the resource; false

means it is optional.</para>

<para>Default: <literal>false</literal></para>

</listitem>

<listitem>

<para>(Optional) "isSingleValued": true means represent a

possibly multi-valued LDAP attribute as a single value; false

means represent it as an array of values.</para>

<para>Default: <literal>false</literal></para>

</listitem>

<!-- Not used.

<listitem>

<para>(Optional) "searchFilter": specifies the LDAP filter to

use to search for the referenced entry. The default is

<literal>"(objectClass=*)"</literal>.</para>

</listitem>

<listitem>

<para>(Optional) "writability": indicates whether the mapping

supports updates, as described above for the simple mapping. The

default is "readWrite".</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

<para>The default mappings expose a SCIM view of user and group

data.</para>

<programlisting language="javascript">{

"/users": {

"baseDN": "ou=people,dc=example,dc=com",

"readOnUpdatePolicy": "controls",

"useSubtreeDelete": false,

"usePermissiveModify": true,

"etagAttribute": "etag",

"namingStrategy": {

"strategy": "clientDNNaming",

"dnAttribute": "uid"

},

"additionalLDAPAttributes": [

{

"type": "objectClass",

"values": [

"top",

"person",

"organizationalPerson",

"inetOrgPerson"

]

}

],

"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",

"useSubtreeDelete": false,

"usePermissiveModify": true,

"etagAttribute": "etag",

"namingStrategy": {

"strategy": "clientDNNaming",

"dnAttribute": "cn"

},

"additionalLDAPAttributes": [

{

"type": "objectClass",

"values": [

"top",

"groupOfUniqueNames"

]

}

],

"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"

}

}

}

}

}

}

}</programlisting>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

</appendix>