HCL Domino REST API Connector

The Java-based HCL Domino REST API connector runs inside the Identity Java Connector Integration Framework. It manages users and groups as documents of a Domino Directory (names.nsf) through the Domino REST API, following a Directory-as-a-Data-Source approach.

Overview

The connector is implemented in the class DominoConnector in the package solutions.dirx.identity.connector.domino. It communicates with the Basis API (/api/v1) of the HCL Domino REST API and manages users and groups as documents of the Domino Directory (names.nsf), supporting add, modify, delete and search operations translated from SPMLv1 requests.

The admin API (/api/admin-v1/access/*) of the Domino REST API is read oriented and does not provide a complete CRUD interface. The connector therefore uses the generic document endpoints instead:

Table 1. Operations and Requests
Operation	Request
search (no search base)	`POST /api/v1/query?dataSource=<scope>&action=execute` with a DQL query restricted to the configured form
search (search base = universal id)	`GET /api/v1/document/\{unid}?dataSource=<scope>`
add	`POST /api/v1/document?dataSource=<scope>` with the mandatory `Form` item
modify	`PATCH /api/v1/document/\{unid}?dataSource=<scope>` - a partial update; items that are not part of the request keep their current value
delete	`DELETE /api/v1/document/\{unid}?dataSource=<scope>`

The universal id (@meta.unid) of a document is used as the connector side identifier of the managed user or group.

Authentication against the Domino REST API uses a username/password token request against the configured authPath endpoint (JWT bearer token); the connector transparently refreshes the access token whenever a request is rejected as unauthorized.

All communication can be secured via SSL/TLS.

Prerequisites

The restapi task has to be running on the Domino server.
names.nsf has to be published as a data source (scope) of the Domino REST API.
The KeepConfig of that scope has to expose the Person and Group forms together with every item the connector has to read or write. Items that are not configured in the scope are silently ignored by the Domino REST API.
Substring search filters are translated to the DQL contains operator, which requires a full text index on the database.
The technical user used by the connector needs the corresponding rights in the ACL of names.nsf (author/editor plus the [UserCreator], [UserModifier], [GroupCreator] and [GroupModifier] roles).

Only user and group objects are supported. Any other requested object type is rejected with an error, since the Domino REST API Connector currently manages exclusively Person and Group documents.

Configuration

The connector receives its configuration from the Connector Framework in a format that is specified there and reflects an XML document. Note that DirX Identity Manager presents configuration options in a more convenient way; for example, bind credentials and service addresses are typically collected from the connected directory and bind profile. Domino specific options are edited on the Domino Directory property page of the connector.

These options are either specified as attributes in the XML schema of the <connection> element (standard properties) or as <property> subelements of the <connection> element (non-standard properties).

Table 2. Standard Properties
Property	Type	Description
`server`	String	Required. Host name or IP address of the Domino REST API server.
`ssl`	Boolean	Required. Enables SSL/TLS and secures the communication line.
`port`	String	Required. Port of the Domino REST API server.
`user`	String	Required. User name used to obtain the access token (JWT) from the Domino REST API.
`password`	String	Required. Password of the technical user, used together with `user` to obtain the access token.
`type`	String	Required. Directory type of the connected directory.

Table 3. Non-standard Properties
Property	Type	Description
`path`	String	Required. Base path of the Basis API, has to be `/api/v1`. Taken from the REST Endpoints property page of the connected directory.
`authPath`	String	Required. Path of the JWT token endpoint, typically `/api/v1/auth`. Taken from the REST Endpoints property page of the connected directory.
`proxyHost`	String	(Optional) Host name or IP address of an HTTP proxy server. Do not use authenticated proxy servers; deploy a local transparent proxy instead if authentication is required.
`proxyPort`	String	(Optional) Port number of the HTTP proxy server. See `proxyHost`.
`dataSource`	String	Name of the Domino REST API data source (scope) publishing `names.nsf`. Default: `dominodirectory`.
`userForm`	String	Domino form used for user documents. Default: `Person`.
`groupForm`	String	Domino form used for group documents. Default: `Group`.
`groupMemberItem`	String	Item of a group document holding the member names. Default: `Members`.
`multiValuedItems`	String	Comma separated list of items that are always written as JSON arrays, regardless of the number of values in the request. Default: `FullName,LastName,MailAddress,ShortName,Owner,Administrator,Owners,Administrators,Members,Certificate,Location,Comment`.
`documentMode`	String	Access mode of the scope used for document operations. Default: the server default is used, no `mode` query parameter is sent.
`computeWithForm`	Boolean	Let Domino compute the document with its form on read (adds computed and default field values). Default: `FALSE`.
`requireRevision`	Boolean	Set to `TRUE` if the scope is configured with `requireRevisionToUpdate`; the connector then reads the current document revision before every modify request and passes it as the `revision` query parameter. Default: `FALSE`.

Sample Configuration

<connector className="solutions.dirx.identity.connector.domino.DominoConnector" name="TS" role="connector">
    <connection server="domino.example.com" ssl="TRUE" port="443" type="Domino" user="dirxidentity">
        <property name="path" value="/api/v1"/>
        <property name="authPath" value="/api/v1/auth"/>
        <property name="dataSource" value="dominodirectory"/>
        <property name="userForm" value="Person"/>
        <property name="groupForm" value="Group"/>
        <property name="groupMemberItem" value="Members"/>
        <property name="multiValuedItems" value="FullName,LastName,MailAddress,ShortName,Owner,Administrator,Owners,Administrators,Members,Certificate,Location,Comment"/>
        <property name="documentMode" value=""/>
        <property name="computeWithForm" value="FALSE"/>
        <property name="requireRevision" value="FALSE"/>
    </connection>
</connector>

Managing Users and Groups

Users and groups are read, created, modified and deleted as documents of the configured Domino forms (userForm/groupForm, Person/Group by default). All operations use the generic document endpoints of the Basis API; only the Domino form used differentiates users from groups.

Add: a POST /api/v1/document request is sent, the mandatory Form item is set to the configured form.
Modify: a PATCH /api/v1/document/\{unid}?dataSource=<scope> request is sent. Since PATCH is a partial update, items that are not part of the request keep their current value.
Delete: a DELETE /api/v1/document/\{unid}?dataSource=<scope> request is sent.
Search: without a search base, a DQL query restricted to the configured form is executed via POST /api/v1/query; with a search base (the universal id of a document), a single document is read via GET /api/v1/document/\{unid}?dataSource=<scope>.

Group Members

The Domino REST API document endpoints have no operation to append or remove single values of a multi valued item. Member modifications are therefore applied as a read-modify-write:

the current group document is read to obtain the existing members of the item configured via groupMemberItem,
the requested additions and removals are merged into that list (Domino name comparison is case-insensitive, duplicates are suppressed),
the resulting list is written back with a PATCH request.

When a group is newly created, the requested members can be written directly as part of the add request, no additional read is necessary.

Document Revision

Depending on the configuration of the data source (scope), Domino may require a document revision on updates:

If requireRevision is TRUE, the connector reads the current document before every modify request and passes its revision as the revision query parameter. If the document does not carry a revision, the modify request fails.
If requireRevision is FALSE, the connector still passes the revision as an If-Match header on a best effort basis whenever the current document could be read beforehand (this happens automatically for group member modifications, which always read the document first).

HTTPPassword is written as provided. Domino does not hash a password that is written through the REST API, so either write an already hashed value or maintain the password by other means.

Filtering Domino Documents

SPML/DSML search filters are translated into a DQL (Domino Query Language) snippet used as the query of a POST /api/v1/query request. DQL is considerably less expressive than an LDAP filter:

there is no unary not - negated terms are rendered as (@All and not <term>), and negations of nested and/or groups are pushed down to the leaves using De Morgan’s laws,
there is no inequality operator - <> is expressed via not,
there is no presence operator - presence is rendered as a Formula Language term, @formula('@IsAvailable(<item>)'),
contains only supports trailing wildcards (backed by the full text index); filters that would require a leading wildcard are rejected instead of silently returning a wrong result set,
approxMatch filters are translated the same way as an equality match, since Domino text comparison is case and accent insensitive, which is the closest available semantic,
extensibleMatch filters cannot be expressed in DQL and are rejected.

Filters that cannot be translated into a valid DQL snippet (a leading wildcard substring filter, an extensibleMatch filter, or a filter item name that is not a valid Domino item identifier) are rejected with an error rather than silently returning an incomplete or incorrect result set.

Paging

The Domino REST API does not report the total number of results of a DQL query. Paging is therefore driven by the page size: the connector requests start/count query parameters and stops as soon as a page smaller than the requested page size is returned.

Known Issues

HTTPPassword is written as provided; Domino does not hash a password written through the REST API (see Document Revision).
Objects other than users and groups are not supported by this connector.