DS 7.1.7

REST to LDAP Reference

DS software offers these alternatives for HTTP access to directory data:

REST to LDAP Gateway DS Server

Implementation

The gateway is a servlet that connects to remote LDAP server(s).

The DS server exposes RESTful HTTP APIs to its directory data.

Base Configuration Directory

WEB-INF/classes

opendj/config

Connection Configuration

A single configuration file defines how the gateway connects and authenticates to LDAP servers.

For details, see Gateway LDAP Connections.

The server uses an internal connection.

Identity mappers define how HTTP user identities map to LDAP user identities. For details, see Identity Mappers.

Gateway Configuration

A single configuration file defines which LDAP features the gateway uses.

For details, see Gateway LDAP Features.

The server configuration defines which LDAP features are enabled.

API Configuration

In both cases, one or more configuration files define the HTTP APIs that map JSON resources to LDAP entries.

For details, see API Configuration.

Unlike standard JSON, REST to LDAP JSON configuration files permit //-style comments.

Gateway LDAP Connections

A single config.json file defines how the gateway connects and authenticates to LDAP servers. The top-level fields are:

{
  // Secure connections to remote LDAP servers.
  "security": {},
  // Connect and authenticate to remote LDAP servers.
  "ldapConnectionFactories": {},
  // Set authorization policies for access to directory data.
  "authorization": {}
}

Security

The "security" field covers the parameters for secure connections to remote servers:

More information
{
  "security": {
    // Specifies the policy for trusting server certificates exchanged
    // during SSL/StartTLS negotiation. This setting and the following
    // trust policy settings will be ignored if there is no connection
    // security. Acceptable values are:
    //
    // "trustAll" - blindly trust all server certificates (not secure)
    // "jvm"      - only certificates signed by the authorities
    //              associated with the host JVM will be accepted (default)
    // "file"     - use a file-based trust store for validating
    //              certificates. This option requires the following
    //              "fileBasedTrustManager*" settings to be configured.
    //
    "trustManager": "jvm",

    // File based trust manager configuration (see above).
    "fileBasedTrustManagerType": "JKS",
    "fileBasedTrustManagerFile": "/path/to/truststore",
    "fileBasedTrustManagerPasswordFile": "/path/to/pinfile",

    // Specifies the key-manager for TLS client authentication
    // (mutual TLS, mTLS) against the remote server.
    // Acceptable values are:
    //
    // "none"     - disables TLS client authentication,
    //              no client certificates will be used. (default)
    // "jvm"      - use the JVM's default keystore
    //              for retrieving client certificates.
    // "file"     - use a file-based key store
    //              for retrieving client certificates.
    // "pkcs11"   - use a PKCS#11 token
    //              for retrieving client certificates.
    "keyManager": "none",

    // Keystore based key manager configuration (see above).
    "fileBasedKeyManagerType": "JKS",
    "fileBasedKeyManagerFile": "/path/to/keystore",
    "fileBasedKeyManagerPasswordFile": "/path/to/pinfile",

    // PKCS11 based key manager configuration
    "pkcs11KeyManagerPasswordFile": "/path/to/pinfile"
  }
}

LDAP Connection Factories

The "ldapConnectionFactories" field configures connection and authentication to remote servers:

More information
{
  "ldapConnectionFactories": {
    // Unauthenticated connections used for performing bind requests.
    "bind": {
      // Indicates whether LDAP connections should be secured using
      // SSL or StartTLS. Acceptable values are:
      //
      // "none"     - use plain LDAP connections (default)
      // "ssl"      - secure connection using LDAPS
      // "startTLS" - secure connection using LDAP+StartTLS
      //
      "connectionSecurity": "none",

      // This alias references a client SSL key-pair which will be used
      // for performing client authentication (mutual TLS or mTLS) between
      // between this gateway and the remote LDAP server.
      "sslCertAlias": "client-cert",

      // Re-usable pool of 24 connections per server.
      "connectionPoolSize": 24,

      // Check pooled connections are alive every 30 seconds with a 500ms
      // heart beat timeout.
      "heartBeatIntervalSeconds": 30,
      "heartBeatTimeoutMilliSeconds": 500,

      // The preferred load-balancing pool.
      "primaryLdapServers": [{
          "hostname": "localhost",
          "port": 1389
      }],
      // The fail-over load-balancing pool (optional).
      "secondaryLdapServers": [
          // Empty.
      ]
    },

    // Authenticated connections which will be used for searches during
    // authentication and proxied operations (if enabled). This factory
    // will re-use the server "bind" configuration.
    "root": {
      "inheritFrom": "bind",

      // Defines how authentication should be performed. Only simple
      // and SASL/External authentication are supported at the moment.
      // If the OAuth 2.0 authorization policy is configured below,
      // then the directory service must be configured
      // to allow the user configured here to perform proxied authorization.
      "authentication": {
        // The type of LDAP bind request to use, which must be "simple"
        // (the default), "sasl-scram" or "sasl-external".
        "policy": "simple",

        "simple": {
            "bindDn": "uid=admin",
            "bindPassword": "password"
        },

        // SASL SCRAM mechanisms require the user's password
        // to be stored using a compatible storage scheme.
        "sasl-scram": {
            // The SCRAM mechanism name, which defaults to SCRAM-SHA-256.
            "scramMechanism": "SCRAM-SHA-256",
            "bindDn": "uid=admin",
            "bindPassword": "password"
            // Optionally: "scramMinIterations": 2048
            // to reduce the accepted minimum number of iterations.
        }

        // SASL/External does not have any configurable parameters.
      }
    }
  }
}

Authorization

The "authorization" field sets authorization policies for access to directory data. It has the following top-level fields:

{
  "authorization": {
    // Authorization policies to use. One of "anonymous", "basic", or "oauth2".
    "policies": [],
    // Perform all operations using a pre-authorized connection.
    "anonymous": {},
    // Use HTTP Basic authentication's information to bind to the LDAP server.
    "basic": {},
    // Use an OAuth2 authorization method.
    "oauth2": {}
  }
}

The "anonymous" object has the following settings:

More information
{
  "anonymous": {
    // Specify the connection factory to use to perform LDAP operations.
    // If missing, the "root" factory will be used.
    "ldapConnectionFactory": "root"
  }
}

The "basic" object has the following settings:

More information
{
  "basic": {
    // Indicates whether the filter should allow alternative authentication
    // and, if so, which HTTP headers it should obtain the username and
    // password from.
    "supportAltAuthentication": true,
    "altAuthenticationUsernameHeader": "X-OpenIDM-Username",
    "altAuthenticationPasswordHeader": "X-OpenIDM-Password",

    // Define which LDAP bind mechanism to use
    // Supported mechanisms are "simple", "sasl-plain", "sasl-scram", or "search"
    "bind": "search",

    // Bind to the LDAP server using the DN built from the HTTP Basic's username
    "simple": {
      // Connection factory used to perform the bind operation.
      // If missing, "bind" factory will be used.
      "ldapConnectionFactory": "bind",

      // The Bind DN Template containing a single {username},
      // which will be replaced by the authenticating user's name.
      // (For example: uid={username},ou=People,dc=example,dc=com)
      // If missing, "{username}" is used.
      "bindDnTemplate": "uid={username},ou=People,dc=example,dc=com"
    },

    // Bind to the LDAP server using a SASL Plain bind request
    "sasl-plain": {
      // Connection factory used to perform the bind operation.
      // If missing, "bind" factory will be used.
      "ldapConnectionFactory": "bind",

      // Authorization identity template containing a single {username},
      // which will be replaced by the authenticating user's name.
      // (For example: u:{username})
      "authzIdTemplate": "u:{username}"
    },

    // Bind to the LDAP server using a SASL SCRAM bind request.
    // SASL SCRAM mechanisms require the user's password to be stored
    // using a compatible storage scheme.
    "sasl-scram": {
      // Connection factory used to perform the bind operation.
      // If missing, "bind" factory will be used.
      "ldapConnectionFactory": "bind",

      // The SCRAM mechanism name, which defaults to SCRAM-SHA-256.
      "scramMechanism": "SCRAM-SHA-256",

      // Authorization identity template containing a single {username}
      // which will be replaced by the authenticating user's name.
      // (For example: u:{username})
      "authzIdTemplate": "u:{username}"
    },

    // Bind to the LDAP server using the resulting DN of a search request.
    "search": {
      // Connection factory used to perform the search operation.
      // If missing, "root" factory will be used.
      "searchLdapConnectionFactory": "root",

      // Connection factory used to perform the bind operation.
      // If missing, "bind" factory will be used.
      "bindLdapConnectionFactory": "bind",

      // The {username} filter format parameters will be substituted
      // with the client-provided username,
      // using LDAP filter string character escaping.
      "baseDn": "ou=people,dc=example,dc=com",
      "scope": "sub", // Or "one".
      "filterTemplate": "(&(uid={username})(objectClass=inetOrgPerson))"
    }
  }
}

The "oauth2" object has the following settings:

More information
{
  "oauth2": {
    // Access tokens associated realm.
    // This attribute is optional and has a string syntax.
    "realm": "myrealm",

    // Defines the list of required scopes required to access the service.
    // This field is required and cannot be empty.
    "requiredScopes": [ "read", "write", "uid" ],

    // Specify the resolver to use to resolve OAuth2 access token.
    // This attribute is required and its value must be one of "openam", "rfc7662", "cts".
    // Note that the JSON object corresponding to this attribute value must be present
    // and well formed in the "oauth2" JSON attribute.
    "resolver": "openam",

    // Configures caching of access token introspection results.
    // This attribute is optional, if it is not present, no token caching
    // will be performed.
    "accessTokenCache": {
      // Indicates whether the access token caching should be used.
      // This attribute is optional (default value is false)
      // and must have a boolean syntax.
      "enabled": false,

      // Specifies the maximal caching duration for an access token.
      // Once this delay is over, token will be refreshed from an access token resolver
      // (see "oauth2/resolver").
      // This attribute is optional, its default value is "5 minutes".
      // The duration syntax supports all human readable notations from day
      // ("days", "day", "d") to nanosecond ("nanoseconds", "nanosecond", "nanosec",
      // "nanos", "nano", "ns")
      // Any negative or zero values are incorrect.
      "cacheExpiration": "5 minutes"
    },

    // The OpenAM access token resolver configuration.
    // This attribute must be present if the "oauth2/resolver" is equal to "openam".
    // If "oauth2/resolver" is set to another resolver, this attribute will be ignored.
    "openam": {
      // Defines the OpenAM endpoint URL where the request should be sent.
      // This attribute is required and must have a string syntax.
      "endpointUrl": "http://openam.example.com:8080/openam/oauth2/tokeninfo",

      // This alias points at an existing certificate that is used for TLS authentication
      // for secure communication between this gateway
      // and the OpenAM access-token resolver.
      "sslCertAlias": "client-cert",

      // The default authzIdTemplate demonstrates how an authorization DN
      // may be constructed from the "uid" field in the following example
      // OpenAM tokeninfo response:
      // {
      //     "scope":["uid"],
      //     "realm":"/",
      //     "expires_in":45,
      //     "uid" : "bjensen",
      // }
      // This attribute is required and has a string syntax.
      // It must start with either 'dn:' or 'u:'.
      "authzIdTemplate": "dn:uid={uid},ou=People,dc=example,dc=com"
    },

    // The RFC-7662 (see https://tools.ietf.org/html/rfc7662)
    // access token resolver configuration.
    // This attribute must be present if the "oauth2/resolver" is equal to "rfc7662".
    // If "oauth2/resolver" is set to another resolver, this attribute will be ignored.
    "rfc7662": {
      // Defines the token introspection endpoint URL where the request should be sent.
      // This attribute is required and must have a string syntax.
      "endpointUrl": "http://openam.example.com:8080/openam/oauth2/myrealm/introspect",

      // This alias points at an existing certificate that is used for TLS authentication
      // for secure communication between this gateway and the introspection
      // access-token resolver.
      "sslCertAlias": "client-cert",

      // Token introspect endpoint requires authentication.
      // It should support HTTP basic authorization
      // (a base64-encoded string of clientId:clientSecret)
      // These attributes are mandatory.
      "clientId": "client_id",
      "clientSecret": "client_secret",

      // The default authzIdTemplate demonstrates how an authorization DN
      // may be constructed from the "username" field in the following example
      // introspect response:
      // {
      //     "active": true,
      //     "token_type": "access_token",
      //     "exp": 3524,
      //     "username" : "bjensen",
      // }
      // This attribute is required and has a string syntax.
      // It must start with either 'dn:' or 'u:'.
      "authzIdTemplate": "dn:uid={username},ou=People,dc=example,dc=com"
    },

    // The CTS access token resolver.
    // This attribute must be present if the "oauth2/resolver" is equal to "cts".
    // If "oauth2/resolver" is set to another resolver, this attribute will be ignored.
    // Note: You can use {userName/0} in authzIdTemplate configuration to access
    // user id from the default CTS access token content config.
    "cts": {
      // The connection factory to use to access CTS.
      // This attribute must reference a connection factory
      // defined in the "ldapConnectionFactories" section.
      // Default value: "root"
      // (That is, the "root" connection factory will be used to access the CTS).
      "ldapConnectionFactory": "root",

      // The access token base DN.
      // This attribute is required and must have a string syntax.
      "baseDn": "ou=famrecords,ou=openam-session,ou=tokens,dc=example,dc=com",

      // The default authzIdTemplate demonstrates how an authorization DN
      // may be constructed from the "userName" field in the following example
      // CTS access token entry:
      // {
      //     "active": true,
      //     "tokenName": ["access_token"],
      //     "exp": [3524],
      //     "userName" : ["bjensen"],
      // }
      // This attribute is required and has a string syntax.
      // It must start with either 'dn:' or 'u:'.
      "authzIdTemplate": "dn:uid={userName/0},ou=People,dc=example,dc=com"
    },

    // ONLY FOR TESTING: A file-based access token resolver.
    // This attribute must be present if the "oauth2/resolver" is equal to "file".
    // If "oauth2/resolver" is set to another resolver, this attribute will be ignored.
    "file": {
      // Directory containing token files.
      // You can test the rest2ldap OAuth2 authorization support
      // by providing JSON token files under
      // the directory set in the configuration below.
      // File names must be equal to the token strings.
      // The file content must a JSON object with the following attributes:
      // 'scope', 'expireTime' and all the field(s) needed to resolve the authzIdTemplate.
      "folderPath": "/path/to/test/folder",

      // The default authzIdTemplate demonstrates an authorization DN constructed
      // from the "uid" field in a fake token file:
      // {
      //     "scope": ["read", "uid", "write"],
      //     "expireTime": 1961336698000,
      //     "uid": "bjensen"
      // }
      // This attribute is required and has string syntax.
      // It must start with either 'dn:' or 'u:'.
      "authzIdTemplate": "dn:uid={uid},ou=People,dc=example,dc=com"
    }
  }
}

Gateway LDAP Features

A single rest2ldap/rest2ldap.json file defines the LDAP features that the gateway uses. The settings have the following defaults:

{
  "useMvcc": true,
  "mvccAttribute": "etag",
  "readOnUpdatePolicy": "controls",
  "useSubtreeDelete": true,
  "usePermissiveModify": true,
  "useServerSideSortForJson": true,
  "returnNullForMissingProperties": false,
  "localSortMaxEntries" : 1000
}
More information
Field Description

"useMvcc"

Whether the gateway supports multi-version concurrency control (MVCC).

If true, specify the "mvccAttribute".

"mvccAttribute"

The LDAP attribute to use for MVCC.

This lets a client application check whether this is the correct version of the resource with the header:

If-Match: mvcc-value

"readOnUpdatePolicy"

Specifies the policy for reading an entry after addition, after modification, and before deletion.

One of the following:

  • "controls": Use RFC 4527 read-entry controls to reflect the state of the resource on update.

    The remote LDAP servers must support RFC 4527.

  • "disabled": Do not read the entry or return the resource on update.

  • "search": Perform an LDAP search to retrieve the entry after addition, after modification, and before deletion.

    The JSON resource returned might differ from the updated LDAP entry.

"useSubtreeDelete"

Whether to use the LDAP Subtree Delete request control (OID: 1.2.840.113556.1.4.805) for LDAP delete operations resulting from delete operations on resources.

Client applications deleting resources with children must have access to use the control.

When true, the gateway attempts to use the control. It falls back to searching for and deleting children if the server rejects the request.

"usePermissiveModify"

Whether to use the LDAP Permissive Modify request control (OID: 1.2.840.113556.1.4.1413) for the LDAP modifications corresponding to PATCH and PUT requests.

Set this to false when remote LDAP servers do not support the control.

"useServerSideSortForJson"

Whether to use the LDAP Server-Side Sort request control (OID: 1.2.840.113556.1.4.473) to request that the server sort the results before returning them.

When false, the gateway sorts search results locally. In this case, set localSortMaxEntries, which effectively limits the maximum _pageSize that the gateway accepts.

"returnNullForMissingProperties"

Whether missing (unmapped) JSON properties should be included in JSON resources. By default, a REST to LDAP mapping omits JSON fields for LDAP attributes that have no values.

"localSortMaxEntries"

The maximum number of entries supported by the local sort mechanism.

When a request includes a _sortKey parameter, the gateway does the following. If the _sortKey parameter targets:

  • A normal LDAP attribute, the gateway includes a server-side sort request to the LDAP server.

  • A JSON syntax LDAP attribute, the action depends on the useServerSideSortForJson setting.

  • An attribute that is in a referenced entry, the gateway sorts the results locally.

API Configuration

Mapping files define APIs by defining how JSON resources map to LDAP entries. REST to LDAP lets you define multiple APIs, and multiple versions for each API.

A mapping file name has the form rest2ldap/endpoints/base-path/root-resource.json:

  • The base-path must match the Rest2ldap endpoint base-path setting in the DS server configuration.

  • The root-resource matches the root resource name in the API’s "resourceTypes".

  • Each file defines a single version of the API.

The sample API file rest2ldap/endpoints/api/example-v1.json has the following structure:

{
  "version": "1.0",         // (Optional) version for this API.
  "resourceTypes": {        // (Required) resources for this API.
    "example-v1": {         // (Required) root resource type. Name must match file basename.
      "subResources": {     // (Required) The base path, /api, is implicit.
        "users": {},        // All resource collections, such as /api/users/ and
        "groups": {}        // /api/groups/ are explicitly defined here.
      }
    },

    // The sample also defines the resource types used by the root's "subResources".
    // This is optional, but critical to readability of the "subResources" definition.
    // Keep resource type names unique to avoid clashes with definitions elsewhere.
    // See the full text of the sample to view how inheritance works.
    "frapi:opendj:rest2ldap:object:1.0": {},    // Parent type of all objects.
    "frapi:opendj:rest2ldap:user:1.0": {},      // Basic user type, parent of
    "frapi:opendj:rest2ldap:posixUser:1.0": {}, // user with uid, gid, home dir.
    "frapi:opendj:rest2ldap:group:1.0": {}      // Basic group type.
  }
}

The example API defines the following resource collections:

  • "users"

  • "groups"

For reference information, see Subresources.

The example API defines the following resource types:

  • "frapi:opendj:rest2ldap:object:1.0"

  • "frapi:opendj:rest2ldap:user:1.0"

  • "frapi:opendj:rest2ldap:posixUser:1.0"

  • "frapi:opendj:rest2ldap:group:1.0"

For reference information, see Resource Types.

Version

The optional "version" field specifies the version of the root resource of the API. For multiple versions of the same API, use multiple mapping files.

More information

Valid version strings include:

  • "*" (Default, no version specified.)

  • "integer"

  • "integer.integer"

Each integer is a positive decimal integer.

A client application requests a specific version by setting the request header:

Accept-API-Version: resource=version

If more than one version of the API is available, but the client does not specify a version header, REST to LDAP uses the latest version of the API.

Subresources

The "subResources" object specifies the API under the current path.

A "subResources" object has the following fields, shown with their default values:

{
  "name": {
    "type": "collection || singleton",  // Required
    "dnTemplate": "",
    "glueObjectClasses": [],
    "isReadOnly": false,
    "namingStrategy": {},
    "resource": ""
  }
}
More information
Field Description

"type"

The type, either "collection" or "singleton".

A collection is a container for other resources that clients can create, read, update, delete, patch, and query. When "type": "collection", the definition has these settings:

{
  "type": "collection",
  "namingStrategy": {},    // Required
  "resource": "",          // Required
  "dnTemplate": "",        // Optional
  "glueObjectClasses": [], // Optional
  "isReadOnly": false      // Optional
}

A singleton is a resource with no children. When "type": "singleton", the definition has these settings:

{
  "type": "singleton",
  "resource": "",          // Required
  "dnTemplate": "",        // Optional
  "isReadOnly": false      // Optional
}

"dnTemplate"

The relative DN template where the LDAP entries are located.

If this is an empty string, the LDAP entries are located directly beneath the parent LDAP entry.

DN templates can use variables in braces {}. REST to LDAP substitutes DN template variables with values extracted from the URL template.

"glueObjectClasses"

One or more LDAP object classes associated with intermediate "glue" entries forming the DN template.

Required if the DN template contains one or more RDNs.

"isReadOnly"

Whether this resource is read-only.

"namingStrategy"

How to map LDAP entry names to JSON resources.

LDAP entries mapped to JSON resources must be immediate subordinates of the "baseDn".

REST to LDAP supports the following naming strategies:

  • "type": "clientDnNaming": The RDN and resource ID are both derived from a single user attribute.

    In the following example, the uid attribute is the RDN. Its value is the JSON resource ID:

    {
      "namingStrategy": {
        "type": "clientDnNaming",
        "dnAttribute": "uid"
      }
    }
  • "type": "clientNaming": The RDN and resource ID are derived from separate user attributes.

    In the following example, the RDN attribute is uid. The JSON resource ID is the value of the mail attribute:

    {
      "namingStrategy": {
        "type": "clientNaming",
        "dnAttribute": "uid",
        "idAttribute": "mail"
      }
    }
  • "type": "serverNaming": The RDN is derived from a user attribute and the resource ID from an operational attribute.

    In the following example, the RDN attribute is uid. The JSON resource ID is the value of the entryUUID operational attribute:

    {
      "namingStrategy": {
        "type": "serverNaming",
        "dnAttribute": "uid",
        "idAttribute": "entryUUID"
      }
    }

"resource"

The resource type name of the subresource.

A collection can contain objects of different types as long as all types inherit from the same super type. In that case, set resource to the super type name.

Resource Types

The required "resourceTypes" object maps resource type names to resource type definitions.

One of the resource type names must match the basename of the mapping file. This resource is referred to as the root resource of the API.

More information

You can reuse a resource type name when specifying the same definition in different mapping files. For example, all mapping files might define the abstract base type frapi:opendj:rest2ldap:object:1.0, and use this everywhere as the superType for other resource types.

If the definitions differ, however, you must use a different resource type name for the changed resource type. For example, if you add a new user type in another API based on frapi:opendj:rest2ldap:user:1.0, but with a different definition. If you still use the original resource type in your APIs, you must also use a different name for your new user type.

Examples in the sample mapping file use the namespace prefix frapi:opendj:rest2ldap:. You may use any string allowed in JSON.

REST to LDAP does not provide a mechanism for inheriting resource types between mapping files. To reuse a resource type from another mapping file, manually copy its name and definition, taking care to change the name if you change the definition.

A resource type definition object has the following fields. All fields are optional, and have the default values shown here:

{
  "unique-name": {
    "properties": {},
    "subResources": {},
    "isAbstract": false,
    "superType": "",
    "objectClasses": [],
    "supportedActions": [],
    "includeAllUserAttributesByDefault": false,
    "excludedDefaultUserAttributes": []
  }
}
More information
Field Description

"properties"

Map of property names to property definitions.

For details, see Properties.

"subResources"

Map of subresource names to subresource definitions.

The names are URL path templates, setting the relative path where the subresources are located. URL path templates can set variables in braces {}. For example, suppose LDAP entries for devices are under the following base DNs:

  • ou=others,ou=devices,dc=example,dc=com

  • ou=pcs,ou=devices,dc=example,dc=com

  • ou=phones,ou=devices,dc=example,dc=com

  • ou=tablets,ou=devices,dc=example,dc=com

You can define a DN template, ou={type},ou=devices,dc=example,dc=com.

Given the paths relative paths:

  • devices/others

  • devices/pcs

  • devices/phones

  • devices/tablets

REST to LDAP substitutes {type} with the last path element to resolve the DN template and locate the entries in the correct LDAP organizational unit.

For details, see Subresources.

"isAbstract"

Whether this is an abstract resource type used only for inheritance.

"superType"

The resource type that this resource type extends.

Resource types that extend another type inherit properties and subresource definitions.

"objectClasses"

LDAP object classes names for the LDAP entries underlying the JSON resource.

On creation, REST to LDAP adds these to the object classes on the LDAP entry.

The LDAP object classes are never visible in the JSON resource.

"supportedActions"

Names of the DS-specific ForgeRock® Common REST actions that this resource type supports.

Action names must match the actions allowed on the resource in the underlying implementation:

  • "accountUsability": Return account usability information.

    For an example, see Account Usability Action.

  • "create": Create a resource by HTTP POST.

    This action is implicitly supported. Do not include it in the list.

    For an example, see Create (HTTP POST).

  • "modifyPassword": Change one’s own password given the old and new password.

    For an example, see Change Your Password.

  • "resetPassword": Reset a user’s password to a generated value.

    For an example, see Reset a Password.

"includeAllUserAttributesByDefault"

Whether to include all LDAP user attributes as properties of the JSON resource.

When true, the JSON field names match the LDAP attribute names.

"excludedDefaultUserAttributes"

LDAP user attributes to exclude when "includeAllUserAttributesByDefault": true.

Properties

The "properties" object specifies how the JSON resource maps to the underlying LDAP entries.

A "properties" object has the following fields, shown with their default values:

{
  "name": {
    "type": "See the list below.", // Required
    "baseDn": "",
    "defaultJsonValue": "",
    "extensibleJsonOrderingMatchingRule": "",
    "isBinary": false,
    "isMultiValued": false,
    "isRequired": false,
    "jsonQueryEqualityMatchingRule": "caseIgnoreJsonQueryMatch",
    "ldapAttribute": "name",
    "mapper": {},
    "optionalJsonPropertyName": "",
    "primaryKey": "",
    "propertyName": "",
    "resourcePath": "",
    "schema": "",
    "searchFilter": "(objectClass=*)",
    "value": "",
    "writability": "readWrite"
  }
}

The "type" must be one of the following:

  • "constant"

  • "json"

  • "object"

  • "reference"

  • "reverseReference"

  • "resourceType"

  • "simple"

More information
Field Description

"type"

The type, which determines the fields the object has:

"constant"

A fixed value:

{
  "name": {
    "type": "constant",
    "value": "A valid JSON value."
  }
}
"json"

A Json syntax LDAP attribute:

{
  "type": "json",
  "ldapAttribute": "name", // Required
  "baseDn": "",
  "defaultJsonValue": "",
  "extensibleJsonOrderingMatchingRule": "",
  "isBinary": false,
  "isMultiValued": false,
  "isRequired": false,
  "jsonQueryEqualityMatchingRule": "caseIgnoreJsonQueryMatch",
  "schema": "",
  "writability": "readWrite"
}

The "ldapAttribute" must be a Json syntax LDAP attribute.

"object"

An object with its own mapping:

{
  "type": "object",
  "properties": {}
}
"reference"

An LDAP entry found by reference.

This is useful with LDAP attributes that take another entry’s DN, such as manager, and (group) member.

The mapping can define the location of the reference by:

  • Resource path, the path to another JSON resource:

    {
      "type": "reference",
      "resourcePath": "", // Required
      "isMultiValued": false,
      "isRequired": false,
      "ldapAttribute": "name",
      "optionalJsonPropertyName": "",
      "searchFilter": "(objectClass=*)",
      "writability": "readWrite"
    }

    When REST to LDAP reads the reference, it returns the _id and _rev fields by default.

  • Base DN, the LDAP base DN under which to find entries referenced by the JSON resource:

    {
      "type": "reference",
      "baseDn": "",     // Required
      "mapper": {},     // Required
      "primaryKey": "", // Required
      "isMultiValued": false,
      "isRequired": false,
      "ldapAttribute": "name",
      "optionalJsonPropertyName": "",
      "searchFilter": "(objectClass=*)",
      "writability": "readWrite"
    }

    When REST to LDAP reads the reference, it returns all fields by default.

REST to LDAP follows these rules to determine field types for references:

  • If the LDAP attribute is defined in the LDAP schema, then the REST to LDAP mapping uses the most appropriate type in JSON.

    For example, numbers appear as JSON numbers, and booleans as booleans.

  • If the LDAP attribute only has one value, it maps to a scalar.

  • If the LDAP attribute has multiple values, it maps to an array.

"reverseReference"

An LDAP entry that references this one:

{
  "type": "reverseReference",
  // Required:
  "resourcePath": "",
  // Required:
  "propertyName": "",
  // Optional:
  "searchFilter": "(objectClass=*)"
}

The "propertyName" is the name of the property that references this resource.

When REST to LDAP reads the resource, it does not return reverse references by default. Use the _fields parameter to explicitly request reverse reference fields.

"resourceType"

The name of a resource type defined elsewhere in this mapping file.

"simple"

An LDAP attribute:

{
  "type": "simple",
  "ldapAttribute": "name", // Required
  "defaultJsonValue": "",
  "isBinary": false,
  "isMultiValued": false,
  "isRequired": false,
  "writability": "readWrite"
}

Use simple mappings where the correspondence between JSON properties and LDAP attributes is one-to-one.

"baseDn"

The base LDAP DN where REST to LDAP finds entries referenced by the JSON resource.

Base DN values can be literal values, such as dc=example,dc=com. Alternatively, they can use the following notation:

{url-template}

REST to LDAP replaces this with the literal value used in the request.

For example, if the path resource path is /{tenant}/users, and the base DN is ou=people,dc={tenant},dc=com, a request for /example/users, references ou=people,dc=example,dc=com.

".."

This is like .. in a path, meaning "the parent directory."

Paths are big-endian, whereas DNs are little-endian. To reference a "resourcePath", you write ../../groups. To reference a "baseDn", you write ou=groups,..,...

Notice a limitation in this reference to group member entries: all group members must be people. The configuration does not support nested groups and members in other locations.

"defaultJsonValue"

A JSON value to return if no corresponding LDAP attribute is present.

"extensibleJsonOrderingMatchingRule"

The JSON ordering matching rule to use when requesting an extensible server-side sort.

The default rule will ignore case and whitespace when sorting values of JSON fields.

For a description of the extended server-side sort syntax, see Server-Side Sort.

"isBinary"

Whether the underlying LDAP attribute holds a binary value, such as a JPEG photo or a digital certificate.

When "isBinary": true, the JSON resource holds the base64-encoded value. For details, see Binary Resources.

"isMultiValued"

Whether the field can take an array value.

Most LDAP attributes are multi-valued. A literal-minded mapping from LDAP to JSON would be full of array properties, many with only one value.

To minimize inconvenience, REST to LDAP returns single value scalars by default, even when the underlying LDAP attribute is multi-valued. By default, the JSON resource gets the first value returned for a multi-valued LDAP attribute.

When "isMultiValued": true, a single value is still returned as a scalar. If the LDAP attribute has multiple values, REST to LDAP returns an array.

"isRequired"

Whether the LDAP attribute is mandatory and must be provided to create the resource.

"jsonQueryEqualityMatchingRule"

When a query filter in the HTTP request uses a JSON path that points to a field in a JSON attribute value, it uses the matching rule specified by this property to compare the query filter with attribute values:

  • "caseIgnoreJsonQueryMatch": Ignore case when finding matches (default).

  • "caseExactJsonQueryMatch": Respect case when finding matches.

"ldapAttribute"

The attribute in the LDAP entry underlying the JSON resource.

By default, REST to LDAP assumes the JSON field name matches the LDAP attribute name.

"mapper"

How the referenced entry content maps to the content of this JSON field.

A mapper object can have all the fields described in this table.

"optionalJsonPropertyName"

Use this when creating a reference for an attribute that has NameAndOptionalJSON syntax.

REST to LDAP returns optional JSON from the attribute as the value of a property having the name you specify. For example, if you configure "optionalJsonPropertyName": "_refProperties", then the "_refProperties" field of the reference contains the optional JSON.

Suppose the LDAP entry contains an attribute with this syntax, relationship: {"optional": "JSON"}cn=Some relationship,dc=example,dc=com. The configuration specifies "optionalJsonPropertyName": "_refProperties" in the relationship reference. The JSON resource has a relationship field like the following:

{
  "relationship": {
    "_id": "Some relationship",
    "_refProperties": {"optional": "JSON"}
  }
}

"primaryKey"

Indicates which LDAP attribute in the mapper holds the primary key to the referenced entry.

"propertyName"

Name of another field of the JSON resource.

"resourcePath"

A path to another JSON resource.

Resource path values use the following notation:

{url-template}

REST to LDAP replaces this with the literal value used in the request.

/path

The absolute path to the resource.

..

The .. refers to the relative parent path. Use .. to reference an arbitrary resource in the same collection.

For example, according to the default sample API, /api/users/bjensen refers to a user, and /api/groups/Directory Administrators refers to a group. To refer to Babs Jensen’s manager from her account, the resource path is to some other user, ... To refer to groups Babs belongs to, the resource path is to some group, ../../groups.

The following example shows how .. references a manager entry next to the current entry:

{
  "manager": {
    "type": "reference",
    "resourcePath": ".."
  }
}

The following example shows a reference to group member entries:

{
  "members": {
    "type": "reference",
    "resourcePath": "../../users",
    "ldapAttribute": "uniqueMember",
    "isMultiValued": true
  }
}

Notice a limitation in this reference to group member entries: all group members must be people. The configuration does not handle nested groups and members in other locations.

The following example uses a resource path to define a manager’s reports. All users, managers and their reports, are under users/:

{
  "reports": {
    "type": "reverseReference",
    "resourcePath": "..",
    "propertyName": "manager"
  }
}

"schema"

Specifies a JSON Schema that applies values of type "json".

When no schema is specified, REST to LDAP accepts arbitrary JSON values.

"searchFilter"

The LDAP filter to use when searching for a referenced entry.

"value"

Use with "type": "constant" to specify the constant value.

"writability"

Whether the mapping supports updates:

  • "createOnly": This attribute can be set only when the entry is created. Attempts to update this attribute thereafter result in errors.

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

  • "readOnly": This attribute cannot be written. Attempts to write this attribute result in errors.

  • "readOnlyDiscardWrites": This attribute cannot be written. Attempts to write this attribute do not result in errors. Instead, the value to write is discarded.

  • "readWrite": This attribute can be set at creation and updated thereafter.

Copyright © 2010-2023 ForgeRock, all rights reserved.