From 656f8f5a55b4a329afb1acabf11c2b0e118186da Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Wed, 05 Jun 2013 15:49:47 +0000
Subject: [PATCH] CR-1768 Fix for OPENDJ-956: Finish documenting HTTPS for HTTP connection handler
---
opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml | 1097 ++++++++++++++++++++++++++++++++++++++-------------------
1 files changed, 724 insertions(+), 373 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml b/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
index da2822a..0206eb2 100644
--- a/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
+++ b/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
@@ -55,19 +55,75 @@
</listitem>
</itemizedlist>
- <!-- To be updated, pending OPENDJ-828 -->
<variablelist>
<para>The JSON format configuration can hold the following configuration
- objects.</para>
+ 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="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
<varlistentry>
- <term>"primaryLDAPServers" (required)</term>
+ <term>"ldapConnectionFactories" (required, gateway only)</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>
+ <para>Configures how the gateway connects to LDAP servers. This entire
+ configuration object applies only to the REST LDAP gateway.</para>
- <programlisting language="javascript">{
+ <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: 10</para>
+
+ <programlisting language="javascript">"connectionPoolSize": 10</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"heartBeatIntervalSeconds" (optional)</term>
+ <listitem>
+ <para>The gateway tests its connections every
+ <literal>heartBeatIntervalSeconds</literal> seconds to detect whether
+ the connection is still alive.</para>
+
+ <para>Default: 30 (seconds)</para>
+
+ <programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>
+ </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",
@@ -80,82 +136,534 @@
]
}</programlisting>
- <para>By default, the gateway connects to the directory server listening
- on port 1389 on the local host.</para>
- </listitem>
- </varlistentry>
+ <para>By default, the gateway connects to the directory server
+ listening on port 1389 on the local host.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <!-- TODO: change when we get more authentication options. -->
- <term>"authentication" (required)</term>
- <listitem>
- <para>The gateway authenticates by simple bind using the credentials
- specified.</para>
+ <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">{
+ <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>
+ </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>"mappings"</term>
+ <term>"authenticationFilter" (required)</term>
<listitem>
- <para>For each gateway collection URI such as <literal>/users</literal> and
- <literal>/groups</literal>, you configure a mapping between the JSON
- resource returned by the gateway, and the LDAP entry returned by the
- directory service.</para>
+ <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>Each mapping has a number of configuration elements.</para>
+ <para>The filter has the following configuration fields.</para>
<varlistentry>
- <term>"baseDN" (required)</term>
- <listitem>
- <para>The base DN where LDAP entries are found for this mapping.</para>
- </listitem>
+ <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>"attributes" (required)</term>
+ <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: "(&(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>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>
+ <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>"constant"</term>
- <listitem>
- <para>Maps a single JSON attribute to a fixed value.</para>
+ <term>"baseDN" (required)</term>
+ <listitem>
+ <para>The base DN where LDAP entries are found for this mapping.</para>
+ </listitem>
+ </varlistentry>
- <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>
+ <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>
- <programlisting language="javascript">{
+ <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. 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>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>"simple"</term>
- <listitem>
- <para>Maps a JSON field to an LDAP attribute.</para>
+ <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>
+ <para>Simple mappings are used where the correspondence between
+ JSON fields and LDAP attributes is one-to-one.</para>
- <programlisting language="javascript">{
+ <programlisting language="javascript">{
"userName": {
"simple": {
"ldapAttribute": "mail",
@@ -165,97 +673,108 @@
}
}</programlisting>
- <itemizedlist>
- <para>Simple mappings can take a number of fields.</para>
+ <itemizedlist>
+ <para>Simple mappings can take a number of fields.</para>
- <listitem>
- <para>(Required) "ldapAttribute": the name of LDAP attribute.</para>
- </listitem>
+ <listitem>
+ <para>(Required) "ldapAttribute": the name of LDAP attribute.</para>
+ </listitem>
- <listitem>
- <para>(Optional) "defaultValue": the JSON value if no LDAP attribute
- is available on the entry.</para>
- </listitem>
+ <listitem>
+ <para>(Optional) "defaultValue": the JSON value if no LDAP
+ attribute is available on the entry.</para>
- <listitem>
- <para>(Optional) "isBinary": true means the LDAP attribute is
- binary and the JSON field gets the base64-encoded value.</para>
- </listitem>
+ <para>No default is set if this is omitted.</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>
- </listitem>
+ <listitem>
+ <para>(Optional) "isBinary": true means the LDAP attribute is
+ binary and the JSON field gets the base64-encoded value.</para>
- <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>
- </listitem>
+ <para>Default: <literal>false</literal></para>
+ </listitem>
- <listitem>
- <para>(Optional) "writability": indicates whether the LDAP attribute
- supports updates. This field can take the following values.</para>
+ <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>
- <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 updated. Attempts to
- update this attribute result in errors.</para>
- </listitem>
- <listitem>
- <para>"readOnlyDiscardWrites": This attribute cannot be updated.
- Attempts to update this attribute do not result in errors. Instead
- the update value is discarded.</para>
- </listitem>
- <listitem>
- <para>"readWrite": This attribute can be set at creation and
- updated thereafter.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
+ <para>Default: <literal>false</literal></para>
+ </listitem>
- <varlistentry>
- <term>"object"</term>
- <listitem>
- <para>Maps a JSON object to LDAP attributes.</para>
+ <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>This mapping lets you create JSON objects whose fields themselves
- have mappings to LDAP attributes.</para>
- </listitem>
- </varlistentry>
+ <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>
- <varlistentry>
- <term>"reference"</term>
- <listitem>
- <para>Maps a JSON field to an LDAP entry found by reference.</para>
+ <listitem>
+ <para>(Optional) "writability": indicates whether the LDAP
+ attribute supports updates. This field can take the following
+ values.</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>
+ <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>
- <programlisting language="javascript">{
+ <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",
@@ -283,12 +802,12 @@
}
}</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>
+ <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">{
+ <programlisting language="javascript">{
"manager": [
{
"_id": "trigden",
@@ -297,193 +816,86 @@
]
}</programlisting>
- <itemizedlist>
- <para>Reference mapping objects have the following fields.</para>
+ <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) "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) "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) "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>(Required) "primaryKey": indicates which LDAP attribute in
+ the mapper holds the primary key to the referenced entry.</para>
+ </listitem>
- <listitem>
- <para>(Optional) "filter": specifies the LDAP filter to use to
- search for the referenced entry. The default is
- <literal>"(objectClass=*)"</literal>.</para>
- </listitem>
+ <listitem>
+ <para>(Optional) "filter": specifies the LDAP filter to use to
+ search for the referenced entry. The default is
+ <literal>"(objectClass=*)"</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>
- </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>
- <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>
- </listitem>
+ <para>Default: <literal>false</literal></para>
+ </listitem>
- <listitem>
- <para>(Optional) "scope": indicates the scope of the LDAP search to
- find the referenced entry. The default is
- <literal>"SearchScope.WHOLE_SUBTREE"</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>
- <listitem>
- <para>(Optional) "writability": indicates whether the mapping
- supports updates, as described above for the simple mapping. The
- default is "readWrite".</para>
- </listitem>
- </itemizedlist>
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "scope": indicates the scope of the LDAP search
+ to find the referenced entry. The default is
+ <literal>"SearchScope.WHOLE_SUBTREE"</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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>"namingStrategy" (required)</term>
- <listitem>
- <para>The approach used to map LDAP entry names to JSON resources. One
- of the following.</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>
+ <para>The default mappings expose a SCIM view of user and group
+ data.</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>"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>"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": 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>
- <para>This is the default if no policy is specified.</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>
- </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",
@@ -495,11 +907,6 @@
]
}
],
- "namingStrategy": {
- "strategy": "clientDNNaming",
- "dnAttribute": "uid"
- },
- "etagAttribute": "etag",
"attributes": {
"schemas": {
"constant": [
@@ -634,6 +1041,13 @@
"/groups": {
"baseDN": "ou=groups,dc=example,dc=com",
"readOnUpdatePolicy": "controls",
+ "useSubtreeDelete": false,
+ "usePermissiveModify": true,
+ "etagAttribute": "etag",
+ "namingStrategy": {
+ "strategy": "clientDNNaming",
+ "dnAttribute": "cn"
+ },
"additionalLDAPAttributes": [
{
"type": "objectClass",
@@ -643,11 +1057,6 @@
]
}
],
- "namingStrategy": {
- "strategy": "clientDNNaming",
- "dnAttribute": "cn"
- },
- "etagAttribute": "etag",
"attributes": {
"schemas": {
"constant": [
@@ -723,67 +1132,9 @@
}
}
}</programlisting>
- </listitem>
- </varlistentry>
-
- <!--
- <varlistentry>
- <term>"useSSL" (optional)</term>
- <listitem>
- <para>If the gateway connects with StartTLS or SSL to the directory
- service, then you must specify how it uses SSL.</para>
- <para>TODO: Not yet implemented.</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>"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: 10</para>
-
- <programlisting language="javascript">"connectionPoolSize": 10</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>"heartBeatIntervalSeconds" (optional)</term>
- <listitem>
- <para>The gateway tests its connections every
- <literal>heartBeatIntervalSeconds</literal> seconds to detect whether the
- connection is still alive.</para>
-
- <para>Default: 30 (seconds)</para>
-
- <programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
--
Gitblit v1.10.0