PingAuthorize Server Documentation Index
Configuration Reference Home

File Server HTTP Servlet Extension

The File Server HTTP Servlet Extension may be used to serve arbitrary files to HTTP clients, including images, HTML files, and other static content located in a specified location on the PingAuthorize Server filesystem.

When a request is received, the portion of the request URL up to and including this base context path will be removed and replaced with the path specified in the document-root-directory property in order to determine the path to the corresponding file on the local filesystem.

For example, if the configured base-context-path is "/files", the configured document-root-directory is "/www/files/htdocs", and a client requests "http://server.example.com/files/index.html", the "http://server.example.com/files" portion of the URL will be removed and replaced with "/www/files/htdocs" so that the actual file to be served will be "/www/files/htdocs/index.html".

Parent Component
Relations from This Component
Properties
dsconfig Usage

Parent Component

The File Server HTTP Servlet Extension component inherits from the HTTP Servlet Extension

Relations from This Component

The following components have a direct aggregation relation from File Server 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
↓ base-context-path
↓ document-root-directory
↓ enable-directory-indexing
↓ index-file
↓ mime-types-file
↓ default-mime-type
↓ require-authentication
↓ require-file-servlet-access-privilege
↓ require-group
↓ identity-mapper

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

base-context-path

Description
Specifies the base context path that should be used by HTTP clients to reference content. The value must start with a forward slash and must represent a valid HTTP context path.
Default Value
None
Allowed Values
The value must start with a forward slash and must represent a valid HTTP context path.
Multi-Valued
No
Required
Yes
Admin Action Required
The File Server HTTP Servlet Extension must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

document-root-directory

Description
Specifies the path to the directory on the local filesystem containing the files to be served by this File Server HTTP Servlet Extension. The path must exist, and it must be a directory.
Default Value
None
Allowed Values
A filesystem path
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

enable-directory-indexing

Description
Indicates whether to generate a default HTML page with a listing of available files if the requested path refers to a directory rather than a file, and that directory does not contain an index file. If the value is true, then a generated HTML page will be returned for a request targeting a directory with no index file. If the value is false, then an error response will be returned for such requests.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

index-file

Description
Specifies the name of a file whose contents may be returned to the client if the requested path refers to a directory rather than a file. If multiple values are specified, then values will be tried in the order in which they are listing. For example, if index files of "index.html" and "index.htm" are specified (in that order), and the directory targeted by the request contains both index.html and index.htm files, then the content of the index.html file will be returned. If the target directory does not contain index.html but does have index.htm, then the content of the index.htm file will be returned.

If a targeted directory does not contain any of the files specified as index files, then the enable-directory-indexing property will be used to determine whether to generate a default HTML page listing the files in that directory, or to return an error response.

Default Value
index.html
index.htm
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

mime-types-file

Description
Specifies the path to a file that contains MIME type mappings that will be used to determine the appropriate value to return for the Content-Type header based on the extension of the requested file. If a MIME types file is specified, then it may take one of two forms. It may either use the de-facto standard form in which the MIME type is followed by one or more spaces or tabs, which are then followed by a list of space and/or tab-delimited file extensions (e.g., "text/html html htm" indicates that any file with an extension of "html" or "htm" should have a Content-Type value of "text/html"), or it may use a Java properties file format in which an extension should be followed by an equal sign and the MIME type for that extension (e.g., "html=text/html" indicates that a Content-Type value of "text/html" should be used for files with an extension of "html". Note that even if the properties file format is used, line wrapping is not supported so each definition must be given on one line.
Default Value
A default set of MIME type definitions will be used.
Allowed Values
A filesystem path
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

default-mime-type

Description
Specifies the default MIME type to use for the Content-Type header when a mapping cannot be found.
Default Value
application/octet-stream
Allowed Values
The value must represent a valid Internet media type consisting of a type, subtype and optional parameters.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

require-authentication

Description
Indicates whether the servlet extension should only accept requests from authenticated clients. If authentication is required, then the servlet extension will reject any request from a client that does not present authentication credentials. If the require-file-servlet-access-privilege property is set to true, then only users who have the file-servlet-access privilege will be allowed. If the require-group property is defined, then only members of one of the configured groups will be allowed; otherwise, any authenticated client will be granted access.

At the present time, only HTTP basic authentication is supported. The authenticating user may be identified with either a DN or a username. If the user is identified with a username, then the configured identity mapper (if any) will be used to map that username to the corresponding entry.

Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

require-file-servlet-access-privilege

Description
Indicates whether the servlet extension should only accept requests from authenticated clients that have the file-servlet-access privilege. This property only applies if the require-authentication property is set to true.
If this property is set to true, then only requesters who have this privilege will be permitted to access content provided by this File Server HTTP Servlet Extension.
If any require-group values are also specified, then only users who have the necessary privilege and are a member of at least one of the listed groups will be granted access.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

require-group

Description
The DN of a group whose members will be permitted to access to the associated files. If multiple group DNs are configured, then anyone who is a member of at least one of those groups will be granted access. This property will only be considered if the require-authentication property has a value of true. If authentication is required and one or more group DNs are configured, then only users that are members of at least one of those groups will be granted access. If no group DNs are configured, then any authenticated user will be granted access.
Default Value
None
Allowed Values
A valid DN.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

identity-mapper

Description
The identity mapper that will be used to identify the entry with which a username is associated. This property will only be used if the require-authentication property is true and the authentication credentials include a username rather than a DN. If no identity mapper is configured, then users may only be identified with DNs and not with usernames.
Default Value
Users may only be identified with DNs.
Allowed Values
The DN of any Identity Mapper.
Multi-Valued
No
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}] ...

To create a new File Server HTTP Servlet Extension:

dsconfig create-http-servlet-extension
     --extension-name {name}
     --type file-server
     --set base-context-path:{propertyValue}
     --set document-root-directory:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing HTTP Servlet Extension:

dsconfig delete-http-servlet-extension
     --extension-name {name}