Preface This reference covers OpenIG configuration. Who Should Use this Reference This reference is for OpenIG designers, developers, and administrators. For API specifications, see the appropriate Javadoc. Reserved Routes OpenIG reserves all paths starting with /openig for administrative use. Resources exposed under /openig are only accessible to local client applications. Reserved Field Names OpenIG reserves all configuration field names that contain only alphanumeric characters. If you must define your own field names, for example, in custom decorators, use names with dots, ., or dashes, -. Examples include my-decorator and com.example.myDecorator. Field Value Conventions OpenIG configuration uses JSON notation. This reference uses the following terms when referring to values of configuration object fields: array JSON array. boolean Either true or false. configuration expression Expression for which no context is available. A configuration expression, described in Expressions(5) is independent of the request, response, and contexts, so do not use expressions that reference their properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions listed in Functions(5). duration A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive. Negative durations are not supported. The following units can be used in durations: indefinite, infinity, undefined, unlimited: unlimited duration zero, disabled: zero-length duration days, day, d: days hours, hour, h: hours minutes, minute, min, m: minutes seconds, second, sec, s: seconds milliseconds, millisecond, millisec, millis, milli, ms: milliseconds microseconds, microsecond, microsec, micros, micro, us: microseconds nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds expression See Expressions(5). lvalue-expression Expression yielding an object whose value is to be set. number JSON number. object JSON object where the content depends on the object’s type. pattern A regular expression according to the rules for the Java Pattern class. pattern-template Template for referencing capturing groups in a pattern by using $n, where n is the index number of the capturing group starting from zero. For example, if the pattern is "\w+\s*=\s*(\w)+", the pattern-template is "$1", and the text to match is "key = value", the pattern-template yields "value". reference Either references an object configured in the heap by the object’s name or uses a local, inline configuration object where the name is optional. string JSON string. About ForgeRock Common REST For many REST APIs that are not defined by external standards, ForgeRock products provide common ways to access web resources and collections of resources. This section covers what is common across products. Adapt the examples to your types of resources and to your deployment. Common REST Resources Servers generally return JSON-format resources, though resource formats can depend on the implementation. Resources in collections can be found by their unique identifiers (IDs). IDs are exposed in the resource URIs. For example, if a server has a user collection under /users, then you can access a user at /users/user-id. The ID is also the value of the _id field of the resource. Resources are versioned using revision numbers. A revision is specified in the resource’s _rev field. Revisions make it possible to figure out whether to apply changes without resource locking and without distributed transactions. Common REST Verbs The common REST APIs use the following verbs, sometimes referred to collectively as CRUDPAQ. For details and HTTP-based examples of each, follow the links to the sections for each verb. Create Add a new resource. This verb maps to HTTP PUT or HTTP POST. For details, see Create. Read Retrieve a single resource. This verb maps to HTTP GET. For details, see Read. Update Replace an existing resource. This verb maps to HTTP PUT. For details, see Update. Delete Remove an existing resource. This verb maps to HTTP DELETE. For details, see Delete. Patch Modify part of an existing resource. This verb maps to HTTP PATCH. For details, see Patch. Action Perform a predefined action. This verb maps to HTTP POST. For details, see Action. Query Search a collection of resources. This verb maps to HTTP GET. For details, see Query. Common REST Parameters Common REST reserved query string parameter names start with an underscore, _. Reserved query string parameters include, but are not limited to, the following names: _action _fields _mimeType _pageSize _pagedResultsCookie _pagedResultsOffset _prettyPrint _queryExpression _queryFilter _queryId _sortKeys _totalPagedResultsPolicy Some parameter values are not safe for URLs, so URL-encode parameter values as necessary. Continue reading for details about how to use each parameter. Common REST Extension Points The action verb is the main vehicle for extensions. For example, to create a new user with HTTP POST rather than HTTP PUT, you might use /users?_action=create. A server can define additional actions. For example, /tasks/1?_action=cancel. A server can define stored queries to call by ID. For example, /groups?_queryId=hasDeletedMembers. Stored queries can call for additional parameters. The parameters are also passed in the query string. Which parameters are valid depends on the stored query. Create There are two ways to create a resource, either with an HTTP POST or with an HTTP PUT. To create a resource using POST, perform an HTTP POST with the query string parameter _action=create and the JSON resource as a payload. Accept a JSON response. The server creates the identifier if not specified: POST /users?_action=create HTTP/1.1 Host: example.com Accept: application/json Content-Length: ... Content-Type: application/json { JSON resource } To create a resource using PUT, perform an HTTP PUT including the case-sensitive identifier for the resource in the URL path, and the JSON resource as a payload. Use the If-None-Match: * header. Accept a JSON response: PUT /users/some-id HTTP/1.1 Host: example.com Accept: application/json Content-Length: ... Content-Type: application/json If-None-Match: * { JSON resource } The _id and content of the resource depend on the server implementation. The server is not required to use the _id that the client provides. The server response to the create request indicates the resource location as the value of the Location header. If you include the If-None-Match header, its value must be . In this case, the request creates the object if it does not exist, and fails if the object does exist. If you include the If-None-Match header with any value other than , the server returns an HTTP 400 Bad Request error. For example, creating an object with If-None-Match: revision returns a bad request error. If you do not include If-None-Match: *, the request creates the object if it does not exist, and updates the object if it does exist. .Parameters You can use the following parameters: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". Read To retrieve a single resource, perform an HTTP GET on the resource by its case-sensitive identifier (_id) and accept a JSON response: GET /users/some-id HTTP/1.1 Host: example.com Accept: application/json Parameters You can use the following parameters: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". _mimeType=mime-type Some resources have fields whose values are multi-media resources such as a profile photo for example. By specifying both a single field and also the mime-type for the response content, you can read a single field value that is a multi-media resource. In this case, the content type of the field value returned matches the mime-type that you specify, and the body of the response is the multi-media resource. The Accept header is not used in this case. For example, Accept: image/png does not work. Use the _mimeType query string parameter instead. Update To update a resource, perform an HTTP PUT including the case-sensitive identifier (_id) for the resource with the JSON resource as a payload. Use the If-Match: _rev header to check that you are actually updating the version you modified. Use If-Match: * if the version does not matter. Accept a JSON response: PUT /users/some-id HTTP/1.1 Host: example.com Accept: application/json Content-Length: ... Content-Type: application/json If-Match: _rev { JSON resource } When updating a resource, include all the attributes to be retained. Omitting an attribute in the resource amounts to deleting the attribute unless it is not under the control of your application. Attributes not under the control of your application include private and read-only attributes. In addition, virtual attributes and relationship references might not be under the control of your application. .Parameters You can use the following parameters: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". Delete To delete a single resource, perform an HTTP DELETE by its case-sensitive identifier (_id) and accept a JSON response: DELETE /users/some-id HTTP/1.1 Host: example.com Accept: application/json Parameters You can use the following parameters: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". Patch To patch a resource, send an HTTP PATCH request with the following parameters: operation field value from (optional with copy and move operations) You can include these parameters in the payload for a PATCH request, or in a JSON PATCH file. If successful, you’ll see a JSON response similar to: PATCH /users/some-id HTTP/1.1 Host: example.com Accept: application/json Content-Length: ... Content-Type: application/json If-Match: _rev { JSON array of patch operations } PATCH operations apply to three types of targets: single-valued, such as an object, string, boolean, or number. list semantics array, where the elements are ordered, and duplicates are allowed. set semantics array, where the elements are not ordered, and duplicates are not allowed. ForgeRock PATCH supports several different operations. The following sections show each of these operations, along with options for the field and value: Patch Operation: Add The add operation ensures that the target field contains the value provided, creating parent fields as necessary. If the target field is single-valued, then the value you include in the PATCH replaces the value of the target. Examples of a single-valued field include: object, string, boolean, or number. An add operation has different results on two standard types of arrays: List semantic arrays: you can run any of these add operations on that type of array: If you add an array of values, the PATCH operation appends it to the existing list of values. If you add a single value, specify an ordinal element in the target array, or use the {-} special index to add that value to the end of the list. Set semantic arrays: The list of values included in a patch are merged with the existing set of values. Any duplicates within the array are removed. As an example, start with the following list semantic array resource: { "fruits" : [ "orange", "apple" ] } The following add operation includes the pineapple to the end of the list of fruits, as indicated by the - at the end of the fruits array. { "operation" : "add", "field" : "/fruits/-", "value" : "pineapple" } The following is the resulting resource: { "fruits" : [ "orange", "apple", "pineapple" ] } Patch Operation: Copy The copy operation takes one or more existing values from the source field. It then adds those same values on the target field. Once the values are known, it is equivalent to performing an add operation on the target. The following copy operation takes the value from the source named /hot/potato, and then runs a replace operation on the target value, /hot/tamale. [ { "operation" : "copy", "field" : "/hot/potato", "value" : "/hot/tamale" } ] If the source and value are configured as arrays, the result depends on whether the array has list semantics or set semantics, as described in Patch Operation: Add. Patch Operation: Increment The increment operation changes the value or values of the target field by the amount you specify. The value that you include must be one number, and may be positive or negative. The value of the target field must accept numbers. The following increment operation adds 1000 to the target value of /user/payment. [ { "operation" : "increment", "field" : "/user/payment", "value" : "1000" } ] Since the value of the increment is a single number, arrays do not apply. Patch Operation: Move The move operation removes existing values on the source field. It then adds those same values on the target field. It is equivalent to performing a remove operation on the source, followed by an add operation with the same values, on the target. The following move operation is equivalent to a remove operation on the source named /hot/potato, followed by a replace operation on the target value, /hot/tamale. [ { "operation" : "move", "field" : "/hot/potato", "value" : "/hot/tamale" } ] To apply a move operation on an array, you need a compatible single-value, list semantic array, or set semantic array on both the source and the target. For details, see the criteria described in Patch Operation: Add. Patch Operation: Remove The remove operation ensures that the target field no longer contains the value provided. If the remove operation does not include a value, the operation removes the field. The following remove deletes the value of the phoneNumber, along with the field. [ { "operation" : "remove", "field" : "phoneNumber" } ] If the object has more than one phoneNumber, those values are stored as an array. A remove operation has different results on two standard types of arrays: List semantic arrays: A remove operation deletes the specified element in the array. For example, the following operation removes the first phone number, based on its array index (zero-based): [ { "operation" : "remove", "field" : "/phoneNumber/0" } ] Set semantic arrays: The list of values included in a patch are removed from the existing array. Patch Operation: Replace The replace operation removes any existing value(s) of the targeted field, and replaces them with the provided value(s). It is essentially equivalent to a remove followed by a add operation. If the arrays are used, the criteria is based on Patch Operation: Add. However, indexed updates are not allowed, even when the target is an array. The following replace operation removes the existing telephoneNumber value for the user, and then adds the new value of +1 408 555 9999. [ { "operation" : "replace", "field" : "/telephoneNumber", "value" : "+1 408 555 9999" } ] A PATCH replace operation on a list semantic array works in the same fashion as a PATCH remove operation. The following example demonstrates how the effect of both operations. Start with the following resource: { "fruits" : [ "apple", "orange", "kiwi", "lime" ], } Apply the following operations on that resource: [ { "operation" : "remove", "field" : "/fruits/0", "value" : "" }, { "operation" : "replace", "field" : "/fruits/1", "value" : "pineapple" } ] The PATCH operations are applied sequentially. The remove operation removes the first member of that resource, based on its array index, (fruits/0), with the following result: [ { "fruits" : [ "orange", "kiwi", "lime" ], } ] The second PATCH operation, a replace, is applied on the second member (fruits/1) of the intermediate resource, with the following result: [ { "fruits" : [ "orange", "pineapple", "lime" ], } ] Patch Operation: Transform The transform operation changes the value of a field based on a script or some other data transformation command. The following transform operation takes the value from the field named /objects, and applies the something.js script as shown: [ { "operation" : "transform", "field" : "/objects", "value" : { "script" : { "type" : "text/javascript", "file" : "something.js" } } }, ] Patch Operation Limitations Some HTTP client libraries do not support the HTTP PATCH operation. Make sure that the library you use supports HTTP PATCH before using this REST operation. For example, the Java Development Kit HTTP client does not support PATCH as a valid HTTP method. Instead, the method HttpURLConnection.setRequestMethod("PATCH") throws ProtocolException. .Parameters You can use the following parameters. Other parameters might depend on the specific action implementation: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". Action Actions are a means of extending common REST APIs and are defined by the resource provider, so the actions you can use depend on the implementation. The standard action indicated by _action=create is described in Create. .Parameters You can use the following parameters. Other parameters might depend on the specific action implementation: _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in the body of the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". Query To query a resource collection (or resource container if you prefer to think of it that way), perform an HTTP GET and accept a JSON response, including at least a _queryExpression, _queryFilter, or _queryId parameter. These parameters cannot be used together: GET /users?_queryFilter=true HTTP/1.1 Host: example.com Accept: application/json The server returns the result as a JSON object including a "results" array and other fields related to the query string parameters that you specify. .Parameters You can use the following parameters: _queryFilter=filter-expression Query filters request that the server return entries that match the filter expression. You must URL-escape the filter expression. The string representation is summarized as follows. Continue reading for additional explanation: Expr = OrExpr OrExpr = AndExpr ( 'or' AndExpr ) * AndExpr = NotExpr ( 'and' NotExpr ) * NotExpr = '!' PrimaryExpr | PrimaryExpr PrimaryExpr = '(' Expr ')' | ComparisonExpr | PresenceExpr | LiteralExpr ComparisonExpr = Pointer OpName JsonValue PresenceExpr = Pointer 'pr' LiteralExpr = 'true' | 'false' Pointer = JSON pointer OpName = 'eq' | # equal to 'co' | # contains 'sw' | # starts with 'lt' | # less than 'le' | # less than or equal to 'gt' | # greater than 'ge' | # greater than or equal to STRING # extended operator JsonValue = NUMBER | BOOLEAN | '"' UTF8STRING '"' STRING = ASCII string not containing white-space UTF8STRING = UTF-8 string possibly containing white-space Note that white space, double quotes ("), parentheses, and exclamation characters need URL encoding in HTTP query strings. A simple filter expression can represent a comparison, presence, or a literal value. For comparison expressions use json-pointer comparator json-value, where the comparator is one of the following: eq (equals) co (contains) sw (starts with) lt (less than) le (less than or equal to) gt (greater than) ge (greater than or equal to) For presence, use json-pointer pr to match resources where the JSON pointer is present. Literal values include true (match anything) and false (match nothing). Complex expressions employ and, or, and ! (not), with parentheses, (expression), to group expressions. _queryId=identifier Specify a query by its identifier. Specific queries can take their own query string parameter arguments, which depend on the implementation. _pagedResultsCookie=string The string is an opaque cookie used by the server to keep track of the position in the search results. The server returns the cookie in the JSON response as the value of pagedResultsCookie. In the request _pageSize must also be set and non-zero. You receive the cookie value from the provider on the first request, and then supply the cookie value in subsequent requests until the server returns a null cookie, meaning that the final page of results has been returned. The _pagedResultsCookie parameter is supported when used with the _queryFilter parameter. The _pagedResultsCookie parameter is not guaranteed to work when used with the _queryExpression and _queryId parameters. The _pagedResultsCookie and _pagedResultsOffset parameters are mutually exclusive, and not to be used together. _pagedResultsOffset=integer When _pageSize is non-zero, use this as an index in the result set indicating the first page to return. The _pagedResultsCookie and _pagedResultsOffset parameters are mutually exclusive, and not to be used together. _pageSize=integer Return query results in pages of this size. After the initial request, use _pagedResultsCookie or _pageResultsOffset to page through the results. _totalPagedResultsPolicy=string When a _pageSize is specified, and non-zero, the server calculates the "totalPagedResults", in accordance with the totalPagedResultsPolicy, and provides the value as part of the response. The "totalPagedResults" is either an estimate of the total number of paged results (_totalPagedResultsPolicy=ESTIMATE), or the exact total result count (_totalPagedResultsPolicy=EXACT). If no count policy is specified in the query, or if _totalPagedResultsPolicy=NONE, result counting is disabled, and the server returns value of -1 for "totalPagedResults". _sortKeys=[-]field[,[-]field…] Sort the resources returned based on the specified field(s), either in + (ascending, default) order, or in - (descending) order. The _sortKeys parameter is not supported for predefined queries (_queryId). _prettyPrint=true Format the body of the response. _fields=field[,field…] Return only the specified fields in each element of the "results" array in the response. The field values are JSON pointers. For example if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value". HTTP Status Codes When working with a common REST API over HTTP, client applications should expect at least the following HTTP status codes. Not all servers necessarily return all status codes identified here: 200 OK The request was successful and a resource returned, depending on the request. 201 Created The request succeeded and the resource was created. 204 No Content The action request succeeded, and there was no content to return. 304 Not Modified The read request included an If-None-Match header, and the value of the header matched the revision value of the resource. 400 Bad Request The request was malformed. 401 Unauthorized The request requires user authentication. 403 Forbidden Access was forbidden during an operation on a resource. 404 Not Found The specified resource could not be found, perhaps because it does not exist. 405 Method Not Allowed The HTTP method is not allowed for the requested resource. 406 Not Acceptable The request contains parameters that are not acceptable, such as a resource or protocol version that is not available. 409 Conflict The request would have resulted in a conflict with the current state of the resource. 410 Gone The requested resource is no longer available, and will not become available again. This can happen when resources expire for example. 412 Precondition Failed The resource’s current version does not match the version provided. 415 Unsupported Media Type The request is in a format not supported by the requested resource for the requested method. 428 Precondition Required The resource requires a version, but no version was supplied in the request. 500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request. 501 Not Implemented The resource does not support the functionality required to fulfill the request. 503 Service Unavailable The requested resource was temporarily unavailable. The service may have been disabled, for example. Formatting Conventions Most examples in the documentation are created in GNU/Linux or Mac OS X operating environments. If distinctions are necessary between operating environments, examples are labeled with the operating environment name in parentheses. To avoid repetition file system directory names are often given only in UNIX format as in /path/to/server , even if the text applies to C:\path\to\server as well. Absolute path names usually begin with the placeholder /path/to/ . This path might translate to /opt/ , C:\Program Files\ , or somewhere else on your system. Command-line, terminal sessions are formatted as follows: $ echo $JAVA_HOME /path/to/jdk Command output is sometimes formatted for narrower, more readable output even though formatting parameters are not shown in the command. Program listings are formatted as follows: class Test { public static void main(String [] args) { System.out.println("This is a program listing."); } } Accessing Documentation Online Open Identity Platform Community publishes comprehensive documentation online: The Open Identity Platform Community Documentation offers a large and increasing number of up-to-date, practical articles that help you deploy and manage Open Identity Platform software. Open Identity Platform product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them. Joining the Open Identity Platform Community Visit the community resource center where you can find information about each project, download nightly builds, browse the resource catalog, ask and answer questions on the forums, find community events near you, and of course get the source code as well. Getting Support and the Contacting Open Identity Platform Community Open Identity Platform Community Approved Vendors provide support services, professional services, trainings, and partner services to assist you in setting up and maintaining your deployments. Configuration Reference Required Configuration