Previous     Contents     Index     Next     
iPlanet Directory Access Router Administrator's Guide



Chapter 16   Groups Configuration


iPlanet Directory Access Router (iDAR) groups describe how to identify an LDAP client, and the restrictions to enforce for clients that match that group. Clients are initially identified into a group based on the network address from which they connect. They may change their group after a successful bind. (See sections ids-proxy-sch-OnBindSuccessRule Object Class and ids-proxy-sch-ChangeGroupAction Object Class for more details.)

Groups are tested in the descending order of priority, specified by the ids-proxy-con-priority attribute. The order of evaluation of groups with equal priority is undefined. If no groups are found to match a client, the client's request will be rejected. There must be at least one group entry in the configuration specification.

This chapter contains the following sections:



ids-proxy-sch-Group Object Class

This object class contains the group object attributes.


ids-proxy-con-Name

The ids-proxy-con-Name attribute specifies the name of the group or property. This attribute value must be unique within the set of groups. This attribute must be present as it forms the RDN of entries of this class.


ids-proxy-con-Priority

The ids-proxy-con-Priority attribute specifies the order of evaluation. It takes an integer value greater than or equal to zero. If this attribute is not present its value is assumed to be 0. If the priority of two objects are the same, their order of evaluation is undefined. The object with the highest value is evaluated first. Thus, for example, the most generic group should have the lowest ids-proxy-con-Priority value. This is a single valued attribute.


ids-proxy-sch-Enable

The ids-proxy-sch-Enable attribute specifies if this object entry is part of the configuration or not. For an entry to be part of iDAR configuration, the ids-proxy-sch-Enable attribute must be present with the value TRUE. If the ids-proxy-sch-Enable attribute is not present or has the value FALSE, the object entry is ignored. This is a single valued attribute.


ids-proxy-sch-belongs-to

This is a multi-valued attribute that specifies which server configuration this object entry belongs to. The value of this attribute should be the value of the ids-proxy-con-server-name attribute in the ids-proxy-sch-LDAPProxy object entry. If it does not match, the entry is ignored.



ids-proxy-sch-NetworkGroup Object Class


This object class is sub-classed from the ids-proxy-sch-Group object class. Clients are identified to belong to this object class based on their IP address and/or domain name. Each of the ids-proxy-sch-NetworkGroup object entries must have at least one value for the ids-proxy-con-Client attribute.


ids-proxy-con-Client

The ids-proxy-con-Client attribute specifies the domain names or IP addresses of the hosts that match the ids-proxy-sch-NetworkGroup object entry. If a group is used only for clients to switch to when they bind, this attribute should be present with value 0.0.0.0.

The value of the ids-proxy-con-Client attribute can be one of the following:

  • A domain name, for example, foo.iplanet.com. Note that iDAR does not assume any domain suffix by default; therefore, complete domain names must be provided.

  • A domain name suffix with a leading period, for example, .iplanet.com. All hosts with domain names that end in that suffix are considered to match.

  • A single IP address in dotted decimal form, e.g., 198.214.11.1.

  • An IP network mask, in the form of <network number>/<mask bits>, for example, 198.241.11.0/24. The first half is the network number and the second half indicates the number of bits of the network number necessary for matching.

  • An IP network mask, in the form of a pair of dotted decimal quads, for example, 198.241.11.0/255.255.255.128. The first half is a network number, the second half indicates the bits of the network number necessary for matching. For example, 198.214.11.0/255.255.255.128 will match a host with IP address 198.214.11.63 but not one with IP address 198.214.11.191.

  • If a group is only used for clients to switch to when they bind, this attribute should be present with value 0.0.0.0.

  • The string ALL (must be in all caps) matches all hosts.

Since the groups are checked in the order of priority, the most specific group should have the highest value. Generic groups, such as those with the attribute ids-proxy-con-Client: ALL, should have the lowest value, as no further groups will be checked.


Note Use of domain names or domain name suffixes requires ids-proxy-con-reverse-dns-lookup to be set to TRUE.



ids-proxy-con-include-property

The ids-proxy-con-include-property attribute is used to specify the property object entry to include in a group. The value of this attribute should be the value of the ids-proxy-con-Name attribute in the property object you want to include. This attribute is used to include more specialized configuration properties into a group.

For example, to include a property with ids-proxy-con-Name:Load-Balance you must specify the following:

ids-Proxy-con-include-property:Load-Balance


ids-proxy-con-include-rule

The ids-proxy-con-include-rule attribute is used to specify the rule object entry to include in a group. The value of this attribute should be the value of the ids-proxy-con-Name attribute in the rule object you want to include.

This attribute is used to include rules that can be evaluated upon completion of predetermined processes and actions that can be taken on the outcome of the evaluation.

For example, the ids-proxy-sch-OnSuccessfulBindRule is evaluated on the successful completion of a bind operation. If the rule evaluates to true, then a client may be able to change its group. For more information see Chapter 18 "Events Configuration."


ids-proxy-con-ssl-policy

The ids-proxy-con-ssl-policy attribute can have one of the following three values: ssl_required, ssl_optional, or ssl_unavailable. If ssl_optional is specified, then a TLS/SSL connection will be established if the client requests TLS/SSL. If ssl_required is specified, then the client must establish a TLS/SSL session before performing any operation. iDAR will not permit a TLS/SSL session if ssl_unavailable is specified. This is the default.

For example, to make sure that all clients in a group establish a TLS/SSL session before performing any operation, specify the following:

ids-proxy-con-ssl-policy: ssl_required

For more information on setting up TLS, see Chapter 12 "Configuring Security."


ids-proxy-con-tcp-no-delay

If the value of this option is set to TRUE, then iDAR will disable the Nagle Algorithm for connections between itself and clients that fall into this group. This option should only be set to FALSE if the network bandwidth between iDAR and clients is small. Setting this option to FALSE may create substantial performance degradation. The default is TRUE.


ids-proxy-con-allow-multi-ldapv2-bind

If this attribute is set to TRUE, iDAR will allow a LDAP v2 client to bind multiple times over a single session. The LDAP v2 specification (RFC 1777) does not allow a client to bind multiple times in one session. However, some clients expect this functionality, so this attribute can be used to interoperate with these clients. If you do set ids-proxy-con-allow-multi-ldapv2-bind to TRUE, you should set
ids-proxy-con-use-version attribute in the ids-proxy-sch-LDAPServer objectclass to the value 3. This will prevent iDAR from sending any illegal operations to the backend server(s). The default value for this attribute is FALSE.


ids-proxy-con-reverse-dns-lookup

If ids-proxy-con-reverse-dns-lookup is set to FALSE, then iDAR will not perform a reverse DNS lookup to find the domain name of the connecting client. Setting this attribute to FALSE can sometimes significantly improve iDAR's performance. If you have used a domain name or a domain name suffix as a value to ids-proxy-con-client attribute, you must not set ids-proxy-con-reverse-dns-lookup to FALSE, otherwise iDAR will not function properly. The default is TRUE.


ids-proxy-con-timeout

The ids-proxy-con-timeout attribute in an ids-proxy-sch-NetworkGroup defines a period of client inactivity, after which iDAR may close the connection to the client. The value is a number of seconds, typically 600 or more. The default, if this attribute is not present in an ids-proxy-sch-NetworkGroup object entry, is to not timeout connections. If TCP keepalives are not enabled, this attribute must be present to keep iDAR from being clogged by lost client connections.



Forwarding Binds


Once iDAR has accepted a connection from the client and matched a group, it will wait for the client to send the LDAP bind request. iDAR uses the ids-proxy-con-bind-name, ids-proxy-con-permit-auth-none, ids-proxy-con-permit-auth-simple and ids-proxy-con-permit-auth-sasl attributes to determine whether to pass the bind request to the server, or reject the bind request and close the client's connection.

If the client's bind passes these tests, iDAR will forward it to the server. If the server accepts the bind, the connection is established. If, however, the server returns an error indication for the bind request, iDAR will forward the error indication to the client, and then close the connection to the client, if the client was using LDAPv2.


ids-proxy-con-bind-name

The ids-proxy-con-bind-name attribute takes as a value a distinguished name. If a client provides a distinguished name in its bind that is not subordinate to a value in a ids-proxy-con-bind-name attribute, the bind will be rejected. This attribute must be present at least once in a group in order to allow any access. To allow all access for clients that match the ids-proxy-con-client attribute/value pair, regardless of bind name, this attribute should be present, with a zero-length value, as in

ids-proxy-con-bind-name:

This attribute has the dn syntax.


ids-proxy-con-permit-auth-none

The ids-proxy-con-permit-auth-none attribute specifies whether anonymous binds, when the client has not supplied a password, are permitted. The default is TRUE, if this attribute is not present in a group. This attribute may be changed to FALSE to forbid anonymous bind requests.


ids-proxy-con-permit-auth-simple

The ids-proxy-con-permit-auth-simple attribute specifies whether simple binds are permitted, when the client has supplied a password in the clear. The default is TRUE, if this attribute is not present in a group. This attribute may be changed to FALSE to forbid clear text password authenticated bind requests.


ids-proxy-con-permit-auth-sasl

The ids-proxy-con-permit-auth-sasl attribute specifies whether SASL binds are permitted. The default is TRUE, if this attribute is not present in a group. This attribute may be changed to FALSE to forbid SASL authentication.



Controlling Which Operations Are Forwarded


After a successful bind, iDAR by default forwards search and compare requests. iDAR also recognizes the unbind request, and closes the connection to the server.


ids-proxy-con-permit-op-search

If the ids-proxy-con-permit-op-search attribute is present in a group, with the value FALSE, iDAR will not forward search requests to the server. The default is TRUE.


ids-proxy-con-permit-op-compare

If the ids-proxy-con-permit-op-compare attribute is present in a group, with the value FALSE, iDAR will not forward compare requests to the server. The default is TRUE; however, few clients use this operation.


ids-proxy-con-permit-op-add, ids-proxy-con-permit-op-delete, ids-proxy-con-permit-op-modify, ids-proxy-con-permit-op-modrdn, ids-proxy-con-permit-op-extended

By default, iDAR does not forward Add, Modify, Delete, ModifyRDN, or Extended Operations requests. To permit forwarding of these operations, the attributes ids-proxy-con-permit-op-add, ids-proxy-con-permit-op-delete, ids-proxy-con-permit-op-modify, ids-proxy-con-permit-op-modrdn, and ids-proxy-con-permit-op-extended must be present in the ids-proxy-sch-NetworkGroup object entry, with the value TRUE for the appropriate operation to be allowed.


Note You must set ids-proxy-con-permit-op-extended to TRUE if you want your clients to be able to negotiate Start TLS.




Hiding a Subtree of Entries With ids-proxy-con-forbidden-subtree


The ids-proxy-con-forbidden-subtree attribute specifies the distinguished name of the base of a subtree of entries to be excluded. This is a multi-valued attribute. The default, if this attribute is not present in a group, is to allow access to all entries in the directory.

Operations that request entries at or below a forbidden subtree will be rejected with an insufficient access error. Entries that match a search filter and are inside a forbidden subtree are dropped. Note that this option does not remove DN syntax attributes whose values fall under the subtree from entries that are being returned as part of the result.

This attribute has dn syntax.



Attributes Controlling Search Requests


The ids-proxy-con-filter-inequality and ids-proxy-con-min-substring-size attributes are used to prevent certain kinds of searches from reaching the LDAP server. If the client's search request falls under either restriction, iDAR will return an insufficient access error to the client.


ids-proxy-con-filter-inequality

The ids-proxy-con-filter-inequality attribute specifies whether clients are permitted to request searches that contain inequality filters (attr>=value) and (attr<=value). The default is TRUE if this attribute is not present. This attribute should be present in the ids-proxy-sch-NetworkGroup object entry with the value FALSE if you do not wish to permit inequality searches to be performed.


ids-proxy-con-min-substring-size

The ids-proxy-con-min-substring-size attribute specifies the minimum permissible length of a substring in a search filter. The value is a number greater than one. The default, if this attribute is not present, is to allow any size of substring in a search filter. This attribute should be present in the ids-proxy-sch-NetworkGroup object entry if you wish to restrict the kinds of searches that may be performed by web robots, etc. For example, a value of 2 will block searches like(cn=A*).



Controlling Search and Compare Requests


The ids-proxy-con-forbidden-compare and ids-proxy-con-permitted-compare attributes are used to prevent certain kinds of search and compare operations from reaching the LDAP server. If the client's request falls under this restriction, iDAR will return an insufficient access error to the client.


ids-proxy-con-forbidden-compare

The ids-proxy-con-forbidden-compare attribute specifies the name of an attribute that cannot be used by a client in a search filter or compare request. This is a multi-valued attribute. The default, if this attribute is not present in a group, and the ids-proxy-con-permitted-compare attribute is not present in the group either, is to permit all attributes to be used for search filters and comparisons.

For example, to allow clients to search on all attributes except telephoneNumber and payrollCode, add the following:

ids-proxy-con-forbidden-compare: telephoneNumber
ids-proxy-con-forbidden-compare: payrollCode


ids-proxy-con-permitted-compare

The ids-proxy-con-permitted-compare attribute specifies the name of an attribute that may be used in a search filter or compare request. This is a multi-valued attribute.

If there is one or more ids-proxy-con-permitted-compare attributes values present in an ids-proxy-sch-NetworkGroup object entry, and a compare does not match one of these, the request will be rejected by iDAR. If there are no ids-proxy-con-permitted-compare attributes present in a group, and an attribute does not match any ids-proxy-con-forbidden-compare attributes, then it may be used by clients.

For example, if you only want the cn, dn, and mail attributes to be searchable by the client, add the following to that ids-proxy-sch-NetworkGroup object entry:

ids-proxy-con-permitted-compare: cn
ids-proxy-con-permitted-compare: dn
ids-proxy-con-permitted-compare: mail



Attributes Modifying Search Requests


The ids-proxy-con-minimum-base, ids-proxy-con-max-scope, and ids-proxy-con-max-timelimit attributes may modify the search request before it is forwarded to the server.


ids-proxy-con-minimum-base

The ids-proxy-con-minimum-base attribute specifies the base of a subtree for all operations. This is a single valued attribute and has dn syntax. If this attribute is not present, then there is no restriction to a minimum base.

Operations whose target entry is at or below the minimum base entry are not affected by this attribute. If the target entry is superior to the minimum base entry, and the operation is a subtree search, then the query will be rewritten before being sent to the server, to change the target entry to be the minimum base. If the target entry is not below the minimum base or a superior of it, the request will be rejected with a no such object error.

For example, if the ids-proxy-con-minimum-base is set as:

ids-proxy-con-minimum-base: o=iPlanet, st=California, c=US

and a subtree search of st=California, c=US is received, the search will be rewritten such that the server performs a subtree search of
o=iPlanet, st=California, c=US.


ids-proxy-con-max-scope

The ids-proxy-con-max-scope attribute specifies the maximum scope that a client may specify in a search request. This attribute may take one of the following values:

0: only baseObject searches may be requested
1: baseObject and oneLevel searches may be requested
2: baseObject, oneLevel and subtree may be requested

The default, if this attribute is not present, is to permit all search scopes.


ids-proxy-con-max-timelimit

The ids-proxy-con-max-timelimit attribute specifies a maximum time limit in seconds for search operations. If the client specifies a time limit that is larger than the value given in this attribute, this attribute will override the client's request. The default, if this attribute is not present in a group, is to allow the client to set any time limit, including no limit.



Attributes Restricting Search Responses


The ids-proxy-con-max-result-size, ids-proxy-con-forbidden-return, ids-proxy-con-permitted-return, and ids-proxy-con-search-reference attributes in a group describe restrictions that are applied to search results being returned by the server, before they are forwarded to the client.


ids-proxy-con-max-result-size

The ids-proxy-con-max-result-size attribute specifies the maximum number of result entries that may be returned to a client at one time from a single search operation. The value may be any number greater than zero, and if reached, will cause an administrativeLimitExceeded error to be indicated to the client and subsequent entries will be discarded. The default, if this attribute is not present, is to not discard entries.


ids-proxy-con-forbidden-return

The ids-proxy-con-forbidden-return attribute specifies the name of an attribute that is to be excluded from search result entries. This is a multi-valued attribute. The default, if this attribute is not present in the ids-proxy-sch-NetworkGroup object entry, and the ids-proxy-con-permitted-return attribute (discussed next) is not present in the group, is to permit all attributes to be returned.

For example, if you do not want the homePhone attribute to be returned in the search result, add the following attribute/value pair to the ids-proxy-sch-NetworkGroup object entry:

ids-proxy-con-forbidden-return: homePhone


ids-proxy-con-permitted-return

The ids-proxy-con-permitted-return attribute specifies the name of an attribute that may be returned from a search result, if present. This is a multi-valued attribute.

If there are ids-proxy-con-permitted-return attributes values present in an ids-proxy-sch-NetworkGroup object entry, and an attribute does not match one of those listed, it is not returned. If there are no ids-proxy-con-permitted-return attributes values present in an ids-proxy-sch-NetworkGroup object entry, and no value matches any ids-proxy-con-forbidden-return attribute values, then it is returned.


ids-proxy-con-search-reference

The ids-proxy-con-search-reference attribute specifies what to do if a search continuation reference is generated during a search. It can be one of the following values: forward (forward the reference to the client), follow (follow the reference and return the result to the client), or discard. The default is discard.

A search continuation referral is a special case of a referral whereby part of the query has been satisfied by the original directory server queried but that directory server has a reference to another directory server with more data satisfying the query.

This attribute can be used to hide the part of your Directory Information Tree whose naming context is mastered by another LDAP server. It also prevents clients from finding out the network address and port on which this server runs.



Controlling the Return of Referrals



ids-proxy-con-reference

Each group can have an attribute ids-proxy-con-reference that specifies whether to forward, follow, or discard referrals returned by the server. It takes the following values: forward, follow, or discard. The default is forward. It should be noted that a client that does not implement LDAPv3 will not understand forwarded referrals.

The use of this attribute is similar to the ids-proxy-con-search-reference attribute. This attribute applies to all referrals except for search continuation referrals.


ids-proxy-con-referral-ssl-policy

This attribute is similar to ids-proxy-con-ssl-policy. If ssl_required is specified, and an operation is referred, then a TLS/SSL session will be initiated before the operation is forwarded to the referred server. If ssl_unavailable is specified, TLS/SSL will not be initiated. If ssl_optional is specified, TLS/SSL will be initiated only if the client already has TLS/SSL session established with iDAR. The default, if this attribute is not present, is ssl_unavailable.


ids-proxy-con-referral-bind-policy

The ids-proxy-con-referral-bind-policy controls the bind policy when an operation is referred and the referral is being followed. The following three values can be specified: bind_anonymous (always bind anonymous), bind_any (use simple bind if the client had used password-based bind; or else bind as anonymous), or bind_required (reject the referred operation if the client is not password-based bound). The default is bind_any.

Note that iDAR cannot replay binds for clients bound using a SASL mechanism. Thus, the referral operation will be rejected if bind_required is specified and the client used a SASL mechanism to bind.


ids-proxy-con-max-refcount

The ids-proxy-con-max-refcount takes an integer value greater or equal to zero. It limits the maximum number of references that will be followed for a single operation. The default is 15. A value of zero indicates that no limit will be applied.



Controlling Server Load


The ids-proxy-con-max-simultaneous-operations-per-connection and ids-proxy-con-max-operations-per-connection attributes can be used to control the number of simultaneous operations and total number of operations a client can request on one connection. The ids-proxy-con-max-conns and ids-proxy-con-max-simultaneous-conns-from-ip can be used to restrict the number of connections for a group.


ids-proxy-con-max-simultaneous-operations-per-connection

The ids-proxy-con-max-simultaneous-operations-per-connection attribute limits the number of simultaneous operations iDAR will process per connection in that group. The value is an integer greater than zero. If this attribute is not present then no limit is enforced. For example, if you set

ids-proxy-con-max-simultaneous-operations-per-connection: 1

all the clients in that group will be forced to perform synchronous LDAP operations. Additional simultaneous requests, except for requests to abandon an operation, will fail with Server Busy error.


ids-proxy-con-max-operations-per-connection

The ids-proxy-con-max-operations-per-connection limits the total number of operations that iDAR will allow per connection in a group. The value is an integer greater than zero. If a client exceeds the maximum number of operations allowed for its group on one connection, that connection will be closed by iDAR. If this attribute is not present, then no limit is set.


ids-proxy-con-max-conns

This ids-proxy-con-max-conns attribute is the same attribute as the global attribute described in ids-proxy-con-max-conns on page 204. If specified within an ids-proxy-sch-NetworkGroup, then this attribute applies only to that group entry.


ids-proxy-con-max-simultaneous-conns-from-ip

The ids-proxy-con-max-simultaneous-conns-from-ip attribute can be used to restrict the number of simultaneous connections clients can make from a single IP address. The default is 0, which means any number of connections are allowed.


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated July 26, 2001