IDM

Upload files to the server

IDM provides a generic file upload service that lets you upload and save files either to the filesystem or to the repository. The service uses the multipart/form-data Content-Type to accept file content, store it, and return that content when it is called over the REST interface.

To configure the file upload service, add one or more file-description.json files to your project’s conf directory, where description provides an indication of the purpose of the upload service. For example, you might create a file-images.json configuration file to handle uploading image files. Each file upload configuration file sets up a separate instance of the upload service. The description in the filename also specifies the endpoint at which the file service will be accessible over REST. In the previous example, file-images.json, the service would be accessible at the endpoint openidm/file/images.

A sample file upload service configuration file is available in the /path/to/openidm/samples/example-configurations/conf directory. The configuration is as follows:

{
    "enabled" : true,
    "fileHandler" : {
        "type" : file handler type,
        "root" : directory
    }
}

The service supports two file handlers—file and repo. The file handlers are configured as follows:

  • "type" : "file" specifies that the uploaded content will be stored in the filesystem. If you use the file type, you must specify a root property to indicate the directory (relative to the IDM installation directory) in which uploaded content is stored. In the following example, uploaded content is stored in the /path/to/openidm/images directory:

    {
    "enabled" : true,
    "fileHandler" : {
        "type" : "file",
        "root" : "images"
    }
}

    You cannot use the file upload service to access any files outside the configured root directory.

    If root is configured to be an empty string, do not grant access to the file upload service to end users. When type is configured as file, ensure that root is configured to be a directory.

  • "type" : "repo" specifies that the uploaded content will be stored in the repository. The root property does not apply to the repository file handler so the configuration is as follows:

    {
    "enabled" : true,
    "fileHandler" : {
        "type" : "repo"
    }
}

The file upload service performs a multi-part CREATE operation. Each upload request includes two --form options. The first option indicates that the uploaded file content will be converted to a base 64-encoded string and inserted into the JSON object as a field named content with the following structure:

{
    "content" : {
        "$ref" : "cid:filename#content"
    }
}

The second --form option specifies the file to be uploaded, and the file type. The request loads the entire file into memory, so file size will be constrained by available memory.

You can upload any mime type using this service; however, you must specify a safelist of mime types that can be retrieved over REST. If you specify a mime type that is not in the safelist during retrieval of the file, the response content defaults to application/json. To configure the list of supported mime types, specify a comma-separated list as the value of the org.forgerock.json.resource.http.safemimetypes property in the conf/system.properties file. For example:

org.forgerock.json.resource.http.safemimetypes=application/json,application/pkix-cert,application/x-pem-file

You can only select from the following list:

  • image/*

  • text/plain

  • text/css

  • text/csv

  • application/json

  • application/pkix-cert

  • application/x-pem-file

The following request uploads an image (PNG) file named test.png to the filesystem. The file handler configuration file provides the REST endpoint. In this case openidm/file/images references the configuration in the file-images.json file:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--form 'json={"content" : {"$ref" : "cid:test#content"}};type=application/json' \
--form 'test=@test.png;type=image/png' \
--request PUT \
"http://localhost:8080/openidm/file/images/test.png"
{
  "_id": "test.png",
  "content": "aW1hZ2UvcG5n"
}

Note that the resource ID is derived directly from the upload filename — system-generated IDs are not supported.

The following request uploads a stylesheet (css) file named test.css to the same location on the filesystem as the previous request:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--form 'json={"content" : {"$ref" : "cid:test#content"}};type=application/json' \
--form '@test.css;type=text/css' \
--request PUT \
"http://localhost:8080/openidm/file/images/test.css"
{
  "_id": "test.css",
  "content": "aW1hZ2UvY3N2"
}

Files uploaded to the repository are stored as JSON objects in the openidm.files table. The following request uploads the same image (PNG) file (test.png) to the repository:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--form 'json={"content" : {"$ref" : "cid:test#content"}};type=application/json' \
--form 'test=@test.png;type=image/png' \
--request PUT \
"http://localhost:8080/openidm/file/repo/test.png"
{
  "_id": "test.png",
  "_rev": "00000000970b4454",
  "content": "aW1hZ2UvcG5n"
}

Note that the preceding example assumes the following file upload service configuration (in file-repo.json:

{
    "enabled" : true,
    "fileHandler" : {
        "type" : "repo"
    }
}

The file type is not stored with the file. By default, a READ on uploaded file content returns the content as a base 64-encoded string within the JSON object. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/file/repo/test.png"
{
  "_id": "test.png",
  "_rev": "00000000970b4454",
  "content": "aW1hZ2UvcG5n"
}

Your client can retrieve the file in the correct format by specifying the content and mimeType parameters in the read request. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/file/repo/test.css?_fields=content&_mimeType=text/css"

To delete uploaded content, send a DELETE request as follows:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/file/repo/test.png"
{
  "_id": "test.png",
  "_rev": "00000000970b4454",
  "content": "aW1hZ2UvcG5n"
}