The ldap database requires a few dedicated configuration lines. The initial syntax allowed a "server" directive for the host name the operations are redirected to:

        server <list of server[:port] entries>

    uri ldap://host[:port]/
    uri ldaps://host[:port]/
    uri ldapi:///

    server <hostname>

The server and the uri directives can contain a whitespace or comma separated list of values, that are passed to the underlying client library. The library tries to connect to each member of the list until one succeeds.

The directives binddn and bindpw are used by an internal operation related to ACLs, that checks if the dn related to an operation is member of a groupOfNames. As this attribute might be read-protected on the target server, a pair "bind dn/credentials" can be supplied to gain read privileges on the attribute. The syntax is:

    binddn "dn"
    bindpw "credentials"

Note: since the name of the above directives led many users to believe they would be used by back-ldap as bind DN/cred to proxy anonymous requests, their name from 2.3 will change into acl-authcDN and acl-passwd which better describes the fact that they are only used internally by the proxy to perform searches related to the application of local ACLs.

A recent feature is the suffixmassage directive. It allows to rewrite the naming context of requests from a virtual naming context, i.e. the naming context recognized by the local server as related to the LDAP database, to a real naming context, i.e. the naming context that is accepted by the target server. Multiple lines are allowed, to allow the same database to handle requests for different naming contexts that must reside on the same target server. The suffixmassage directive is tightly related to the suffix directive. Search results have the real naming context rewritten back to the virtual naming context as well, so the client does is not directly aware of the real naming context of the server it is contacting. Its syntax is

    suffixmassage <virtual naming context> <real naming context>

    suffix  <virtual naming context>

Note: the suffixmassage directive is currently (2.2) emulated in back-ldap by means of the rewrite feature. See slapd-meta(5) for details on how to write custom rewrite rules.

Note: in 2.3 the rewrite/remap features moved into the rwm overlay (see slapo-rwm(5) for details). Back-ldap does no longer recognize the rewrite/remap related statements. The migration should be very smooth: simply make sure the rwm overlay is built (configure --help for details); the add

    overlay rwm

Note: with the 2.3 release, many deprecated config directives will be obsoleted and thus will no longer be available. Also, note that the syntax of some directives changed, although backwards compatibility will be preserved for a while. See the man page slapd-ldap(5) for an up-to-date description of the configuration syntax.

About "lastmod" config directive

This backend does not own the information it contains, so the "lastmod" config statement is meaningless; however, if it is on (or undefined, defaulting to the global "lastmod on"), an add/modify operation will result in the addition of the lastmod operational attributes (modifiersName, modifyTimeStamp, ...) to the desired adds/changes. When they're passed to the target directory server, an error may arise, preventing modifications through the ldap backend. To avoid this problem, it is recommended to always force "lastmod off" when using the ldap backend.

Note: by default, lastmod is off in back-ldap and back-meta; the above comment is correct, but no action is required any longer (at least since 2.2) to obtain the default behavior.

About virtual backends

Usually virtual backends are used when proxying a remote server; however, another use is that of presenting data in a DSA under a modified form; to this purpose, the uri directive is set to

    uri ldap:///

    suffixmassage "<virtual naming context> <real naming context>

More powerful rules can be written if using the rewrite engine (see slapd-meta(5) for further details). AttributeTypes and objectClasses are mapped by means of the map statement (see slapd-ldap(5) for further details). Note that if the virtual and the real backend are on the same machine, slapd(8) must be compiled with threads; in general, twice the threads required by a normal operatin will be actually used, so be careful when determining the appropriate value of threads; see slapd.conf(5) for details.

Note: with 2.3, virtual databases that are managed by the same DSA can be implemented more efficiently using the relay backend. See slapd-relay(5) for details.
ando@sys-net.it

Identity Assertion

Introduction

The simplest scenario is that of a remote server which is proxied by a DSA. The proxy is being used by users whose identity is not present on the remote server, and thus cannot authenticate on it, nor their bind operation is even proxied; however, the remote server requires authentication to disclose data.

As soon as the local users can somehow authenticate, e.g. because their identity is stored locally, the proxy backend can be instructed to assert their identity, or even some derived identity, to the remote server on their behalf, by using an administrative identity that is stored on the remote server and is granted appropriate authorization privileges.

The scenario is summarized in this schematic proxy-side slapd.conf:

    # local naming context
    database bdb
    suffix   "dc=local,dc=example,dc=com"

    # remote server
    database ldap
    suffix   "dc=remote,dc=example,dc=com"
    uri      ldap://remote.naming.context/

Identity assertion configuration

    idassert-bind bindmethod=<method>
        [binddn=<simple DN>]
        [credentials=<simple password>]
        [saslmech=<SASL mech>]
        [secprops=<properties>]
        [realm=<realm>]
        [authcID=<authentication ID>]
        [authzID=<authorization ID>]
        [mode=<mode>]
        [authz=<how>]
        [flags=<flags>]

    idassert-authzFrom <authzRule>

    mode={anonymous|none|self}

    authzID=<Authorization ID>

    idassert-bind mode=anonymous

    idassert-bind mode=self

    idassert-bind authzID=u:proxy
    idassert-bind authzID=dn:cn=Proxy,dc=example,dc=com
    idassert-bind authzID=cn=Sandbox,dc=example,dc=com

    idassert-authzFrom "dn.exact:uid=jaj,ou=People,dc=example,dc=com"
    idassert-authzFrom "u:bjorn"

    idassert-authzFrom "dn.children:ou=People,dc=example,dc=com"

    idassert-authzFrom "dn:*"

    bindmethod={none|simple|sasl}

• The method none uses anonymous bind; it seems to be pretty useless
• The method simple instructs the proxy to use simple bind; it is strongly recommended that TLS be used in conjunction with simple bind to allow appropriate confidentiality. It allows the following parameters:
  • binddn=<dn> is used to specify a bind DN;
  • credentials=<cred> is used to specify the bind credentials;

  Example:

      idassert-bind bindmethod=simple
          binddn="cn=Proxy,ou=Admin,dc=remote,dc=example,dc=com"
          credentials=proxy
          authzID="dn:cn=Sandbox,dc=local,dc=example,dc=com"
  

• The method sasl instructs the proxy to use SASL bind; this allows extra parameters to be supplied:
  • saslmech=<mech> is used to select a specific SASL mechanism;
  • realm=<realm> is used to specify a realm for those mechanisms that need it;
  • authcID=<id> is used to specify a bind ID (note that bind ID and bind DN have different purposes in SASL, although it is not clear to me what's the meaning of the bind DN, since the bind ID is what is really used; apparently, what is really used is the bind ID, while the bind DN, if given, is the string that is presented as incoming bind request until the bind succeeds and the DN resulting from the application of the authz-regex rules is used);
  • authz=<how> is used to specify whether native SASL authorization should be used (<how>=native) as an alternative to adding the proxyAuthz control to every proxied operation (<how>=proxyAuthz, the default); see SASL authc/authz for details.

  Example:

      idassert-bind bindmethod=sasl
          saslmech=DIGEST-MD5
          binddn="cn=Proxy,ou=Admin,dc=remote,dc=example,dc=com"
          authcID=proxy
          credentials=proxy
          authzID="dn:cn=Sandbox,dc=local,dc=example,dc=com"
          authz=native
  

    idassert-bind bindmethod=sasl authz=native

    idassert-bind bindmethod=sasl authz=proxyAuthz

• when mode=none is used, no proxyAuthz takes place;
• when native SASL authorization is used at SASL bind, the identity is directly asserted at the connection level, so the proxyAuthz control at the operation level is available.

Remote server requirements

• The administrative identity must exist on the remote server.
• The administrative identity must use a bind mechanism that is supported by the remote server, and that provides a ssf appropriate for authorization (see Admin Guide for details).
• The administrative identity on the remote server must be allowed to authorize as the desired identities; this in general must be obtained by using the authzTo attribute of the administrative identity, because the identities it is authorizing as likely do not exist on the remote server (otherwise there would be no need for the identity assertion feature...). This requires the use of the authz-policy to statement (see slapd.conf(5) for details), which may present security implications that must be carefully understood and counteracted by the remote server's administrator.

Scenarios

• To glue together different remote servers with different branches of the same naming context, to make them transparent to the final user as if they were one database:

      authz-regexp    "^uid=([^,]+),.*"
                      "uid=$1,ou=People,dc=example,dc=com"
      access to *
          by * read
  
      # people branch
      database        ldap
      suffix          "ou=People,dc=example,dc=com"
      uri             "ldap://people.example.com"
      idassert-bind   bindmethod=sasl
                      saslmech=DIGEST-MD5
                      authcID=proxy
                      credentials=proxy
                      mode=self
  
      # groups branch
      database        ldap
      suffix          "ou=Groups,dc=example,dc=com"
      uri             "ldap://groups.example.com"
      idassert-bind   bindmethod=sasl
                      saslmech=DIGEST-MD5
                      authcID=proxy
                      credentials=proxy
                      mode=self
  
      # root
      database        bdb
      suffix          "dc=example,dc=com"
      # other bdb stuff...
  
      overlay         glue
      glue-sub        "ou=People,dc=example,dc=com"
      glue-sub        "ou=Groups,dc=example,dc=com"
  

  The remote servers must contain the proxy identity; the configuration of the first one looks like:

      authz-policy    to
      authz-regexp    "^uid=([^,]+),.*"
                      "uid=$1,ou=People,dc=example,dc=com"
  
      # people branch
      database        bdb
      suffix          "ou=People,dc=example,dc=com"
      # other bdb stuff...
  
      access to attrs=userPassword
          by self =xw
          by * =x
  
      access to *
          by users read
          by * search
  

  the configuration of the second one looks like:

      authz-policy    to
      authz-regexp    "^uid=([^,]+),.*"
                      "uid=$1,ou=Groups,dc=example,dc=com"
  
      # groups branch
      database        bdb
      suffix          "ou=Groups,dc=example,dc=com"
      # other bdb stuff...
  
      access to attrs=userPassword
          by self =xw
          by * =x
  
      access to *
          by users read
          by * search
  

  A local root of the naming context must be provided to glue together the remote servers. Operations that refer to the proxied naming branches of the naming contexts are correctly proxied to the remote servers; all other operations are dealt with by the local root database.

  A complete example is provided as test029 in the distribution.

• To allow (dumb) clients that do not perform bind to access servers that require bind (and some ssf) by asserting some static identity (the dn:<dn>, or even the anonymous mode, to implement the "sandbox" user described above) without any idassert-authzFrom rule in place:

      database        ldap
      suffix          "dc=example,dc=com"
      uri             "ldap://ldap.example.com"
      idassert-bind   bindmethod=simple
                      binddn="cn=Proxy,dc=example,dc=com"
                      credentials=proxy
                      authzID="dn:cn=Sandbox,dc=example,dc=com"
  

  If no authzID is given, and mode is set to none (for instance because the remote server does not support the proxyAuthz control), the clients will be authorized as "cn=Proxy,dc=example,dc=com" even if they actually connected anonymously to the proxy. Beware that this may be a significant security breach, if that identity is granted anything but anonymous read privileges.

Caveats and unresolved issues

• If SASL native authorization is used and anonymous connections are allowed, the proxyAuthz control is still applied to every anonymous operation, because the local connection appears as unbound. This leads to unrequired extra work and, moreover, the proxyAuthz control will be applied on behalf of the authorized identity, which might have insufficient or inappropriate permissions.

Security implications

• the authorization rules in the idassert-authzFrom statement to access the feature at the proxy level; see identity assertion access for details;
• the administrative identity on the remote server;
• the access policy of the administrative identity vs. those of the asserted users, not present on the remote database
• the authz-policy of the remote server; see slapd.conf(5) for details;
• the authzTo values of the administrative identity on the remote server; see slapd.conf(5) for details.