Directory REST API HTTP Servlet Extension

The Directory REST API HTTP Servlet Extension provides a general-purpose REST API for directory data.

Parent Component Relations from This Component Properties dsconfig Usage

Parent Component

The Directory REST API HTTP Servlet Extension component inherits from the HTTP Servlet Extension

Relations from This Component

The following components have a direct aggregation relation from Directory REST API HTTP Servlet Extensions:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  None
 cross-origin-policy
 response-header
 correlation-id-response-header
 basic-auth-enabled
 identity-mapper
 access-token-validator
 access-token-scope
 audience
 max-page-size
 schemas-endpoint-objectclass
 default-operational-attribute
 reject-expansion-attribute
 always-use-permissive-modify
 allowed-control

Basic Properties

description

Description
A description for this HTTP Servlet Extension
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

cross-origin-policy

Description
The cross-origin request policy to use for the HTTP Servlet Extension. A cross-origin policy is a group of attributes defining the level of cross-origin request supported by the HTTP Servlet Extension.
Default Value
No cross-origin policy is defined and no CORS headers are recognized or returned.
Allowed Values
The DN of any HTTP Servlet Cross Origin Policy.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

response-header

Description
Specifies HTTP header fields and values added to response headers for all requests. Values specified here must specify both the header field name and the value in conformance with RFC 2616. Fields may only be specified once; multiple values for the same header should be comma-separated. See RFC 7231 for a standard set of field names.
Any response headers configured for this HTTP Servlet Extension will be combined with response headers configured on the corresponding Connection Handler. In the case of duplicates, the headers configured on this HTTP Servlet Extension will be used instead of the headers configured on the Connection Handler.
Default Value
None
Allowed Values
Colon-separated header field name and value
Multi-Valued
Yes
Required
No
Admin Action Required
HTTP Connection Handlers hosting this HTTP Servlet Extension must be disabled and then re-enabled, or the server restarted, in order for this change to take effect.

correlation-id-response-header

Description
Specifies the name of the HTTP response header that will contain a correlation ID value. Example values are "Correlation-Id", "X-Amzn-Trace-Id", and "X-Request-Id". This property can be used to specify a custom response header name for correlation IDs. The value specified here will override the correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension.

If the use-correlation-id-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension is not enabled, then this property will be ignored.

Default Value
The correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension will be used.
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

basic-auth-enabled

Description
Enables HTTP Basic authentication, using a username and password. The Identity Mapper specified by the identity-mapper property will be used to map the username to a DN.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
The Directory REST API HTTP Servlet Extension must be disabled and re-enabled for changes to this setting to take effect. For this modification to take effect, you must either restart the server or else disable and then re-enable any HTTP Connection Handler referencing this component.

identity-mapper

Description
Specifies the Identity Mapper that is to be used for associating user entries with basic authentication usernames.
Default Value
Requests must specify a fully qualified DN. No attempt will be made to map a user name to a DN.
Allowed Values
The DN of any Identity Mapper.
Multi-Valued
No
Required
No
Admin Action Required
For this modification to take effect, you must either restart the server or else disable and then re-enable any HTTP Connection Handler referencing this component.

access-token-validator

Description
If specified, the Access Token Validator(s) that may be used to validate access tokens for requests submitted to this Directory REST API HTTP Servlet Extension.
Default Value
If no validators are specified, then any of the Access Token Validators configured for this server may be used to validate an access token.
Allowed Values
The DN of any Access Token Validator.
Multi-Valued
Yes
Required
No
Admin Action Required
For this modification to take effect, you must either restart the server or else disable and then re-enable any HTTP Connection Handler referencing this component.

access-token-scope

Description
The name of a scope that must be present in an access token accepted by the Directory REST API HTTP Servlet Extension.
Default Value
If this property is not specified, then the Directory REST API HTTP Servlet Extension will not permit bearer token authentication.
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

audience

Description
A string or URI that identifies the Directory REST API HTTP Servlet Extension in the context of OAuth2 authorization. If present, this value must be present in the audience claim of any access tokens accepted by the Directory REST API HTTP Servlet Extension. Providing an audience value is recommended, as it ensures that the Directory REST API HTTP Servlet Extension does not accept access tokens intended for another service.
Default Value
If this property is not specified, then the Directory REST API HTTP Servlet Extension will ignore the audience claim of any access tokens that it accepts.
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

max-page-size

Description
The maximum number of entries to be returned in one page of search results. The actual size of a page returned from the search endpoint will be the minimum of: this attribute, the `limit` parameter on the request (if provided), and the actual number of available results.
Default Value
100
Allowed Values
An integer value. Lower limit is 1. Upper limit is 1000 .
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

schemas-endpoint-objectclass

Description
The list of object classes which will be returned by the schemas endpoint.
Default Value
The Directory REST API HTTP Servlet Extension will return an empty list of schemas.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

default-operational-attribute

Description
A set of operational attributes that will be returned with entries by default.
Default Value
Only user attributes will be returned, unless the client explicitly requests operational attributes.
Allowed Values
The name or OID of an attribute type defined in the server schema.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

reject-expansion-attribute

Description
A set of attributes which the client is not allowed to provide for the expand query parameters. This should be used for attributes that could either have a large number of values or that reference entries that are very large like groups.
Default Value
All attributes can be provided as an expansion parameter.
Allowed Values
The name or OID of an attribute type defined in the server schema.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

always-use-permissive-modify

Description
Indicates whether to always use permissive modify behavior for PATCH requests, even if the request did not include the permissive modify request control. By default, permissive modify is disabled, which means that attempts to modify an entry to add an attribute value that already exists, or to remove an attribute value that does not exist, will be rejected. If this property is set to true, then those types of modifications will be allowed, as if the permissive modify request control had been included in the PATCH request.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

allowed-control

Description
Specifies the names of any request controls that should be allowed by the Directory REST API. Any request that contains a critical control not in this list will be rejected. Any non-critical request control which is not supported by the Directory REST API will be removed from the request.
Default Value
access-log-field
assertion
assured-replication
exclude-branch
generate-password
get-effective-rights
get-password-policy-state-issues
get-recent-login-history
get-user-resource-limits
ignore-no-user-modification
intermediate-client
join
manage-dsa-it
matched-values
matching-entry-count
name-with-entryuuid
no-op
operation-purpose
password-update-behavior
password-validation-details
permissive-modify
permit-unindexed-search
post-read
pre-read
proxied-authorization-v1
proxied-authorization-v2
purge-password
real-attributes-only
reject-unindexed-search
retire-password
suppress-referential-integrity
uniqueness
virtual-attributes-only
Allowed Values
access-log-field - The access log field request control (OID 1.3.6.1.4.1.30221.2.5.66) as used in the Ping Identity Directory Server.

assertion - The LDAP assertion request control (OID 1.3.6.1.1.12) as defined in RFC 4528.

assured-replication - The assured replication request control (OID 1.3.6.1.4.1.30221.2.5.28) as used in the Ping Identity Directory Server.

exclude-branch - The exclude branch request control (OID 1.3.6.1.4.1.30221.2.5.17) as used in the Ping Identity Directory Server.

generate-password - The generate password request control (OID 1.3.6.1.4.1.30221.2.5.58) as used in the Ping Identity Directory Server.

get-effective-rights - The get effective rights request control (OID 1.3.6.1.4.1.42.2.27.9.5.2) as used in the Ping Identity Directory Server.

get-password-policy-state-issues - The get password policy states issues request control (OID 1.3.6.1.4.1.30221.2.5.46) as used in the Ping Identity Directory Server.

get-recent-login-history - The get recent login history request control (OID 1.3.6.1.4.1.30221.2.5.61) as used in the Ping Identity Directory Server.

get-user-resource-limits - The get user resource limits request control (OID 1.3.6.1.4.1.30221.2.5.25) as used in the Ping Identity Directory Server.

ignore-no-user-modification - The ignore NO-USER-MODIFICATION request control (OID 1.3.6.1.4.1.30221.2.5.5) as used in the Ping Identity Directory Server.

intermediate-client - The intermediate client request control (OID 1.3.6.1.4.1.30221.2.5.2) as used in the Ping Identity Directory Server.

join - The join request control (OID 1.3.6.1.4.1.30221.2.5.9).

manage-dsa-it - The ManageDsaIT request control (OID 2.16.840.1.113730.3.4.2) as defined in RFC 3296.

matched-values - The matched values request control (OID 1.2.826.0.1.3344810.2.3) as defined in RFC 3876.

matching-entry-count - The matching entry count request control (OID 1.3.6.1.4.1.30221.2.5.36).

name-with-entryuuid - The name with entryUUID request control (OID 1.3.6.1.4.1.30221.2.5.44).

no-op - The LDAP no-op request control (OID 1.3.6.1.4.1.4203.1.10.2) as used in the Ping Identity Directory Server.

operation-purpose - The operation purpose request control (OID 1.3.6.1.4.1.30221.2.5.19).

password-update-behavior - The password update behavior request control (OID 1.3.6.1.4.1.30221.2.5.51), which may be used to control some of the server's behavior for a password update.

password-validation-details - The password validation details request control (OID 1.3.6.1.4.1.30221.2.5.40), which may be used to obtain information about why a proposed password was rejected.

permissive-modify - The permissive modify request control (OID 1.2.840.113556.1.4.1413), which can be used to allow a modify operation to attempt to add attribute values which already exist or remove values which do not exist.

permit-unindexed-search - The permit unindexed search request control (OID 1.3.6.1.4.1.30221.2.5.55), which can be used to indicate that the associated search operation should be processed even if it is unindexed, as long as the requester also has the unindexed-search-with-control privilege.

post-read - The post-read request control (OID 1.3.6.1.1.13.2) as defined in RFC 4527.

pre-read - The pre-read request control (OID 1.3.6.1.1.13.1) as defined in RFC 4527.

proxied-authorization-v1 - The proxied authorization v1 request control (OID 2.16.840.1.113730.3.4.12) as defined in draft-weltman-ldapv3-proxy.

proxied-authorization-v2 - The proxied authorization v2 request control (OID 2.16.840.1.113730.3.4.18) as defined in RFC 4370.

purge-password - The purge password request control (OID 1.3.6.1.4.1.30221.2.5.32), which may be used to indicate that the user's current password should be purged rather than retired.

real-attributes-only - The real attributes only request control (OID 2.16.840.1.113730.3.4.17) as used in the Ping Identity Directory Server.

reject-unindexed-search - The reject unindexed search request control (OID 1.3.6.1.4.1.30221.2.5.54), which can be used to indicate that the server should reject the search operation if it is unindexed, even if the requester has the unindexed-search privilege.

retire-password - The retire password request control (OID 1.3.6.1.4.1.30221.2.5.31), which may be used to indicate that the user's current password should be retired.

suppress-referential-integrity - The suppress referential integrity updates request control (OID 1.3.6.1.4.1.30221.2.5.30), which may be used to indicate that the server should skip referential integrity processing.

uniqueness - The uniqueness request control (OID 1.3.6.1.4.1.30221.2.5.52), as used in the Ping Identity Directory Server.

virtual-attributes-only - The virtual attributes only request control (OID 2.16.840.1.113730.3.4.19) as used in the Ping Identity Directory Server.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured HTTP Servlet Extensions:

dsconfig list-http-servlet-extensions
     [--property {propertyName}] ...

To view the configuration for an existing HTTP Servlet Extension:

dsconfig get-http-servlet-extension-prop
     --extension-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing HTTP Servlet Extension:

dsconfig set-http-servlet-extension-prop
     --extension-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...