--- title: SaaS REST Connector description: You can only use SaaS REST connector version 1.5.20.29 and later with: component: openicf page_id: openicf:connector-reference:rest canonical_url: https://docs.pingidentity.com/openicf/connector-reference/rest.html section_ids: install_the_saas_rest_connector: Install the SaaS REST connector configure_the_saas_rest_connector: Configure the SaaS REST connector RestOperations: OPERATIONS test_the_saas_rest_connector: Test the SaaS REST connector SAAS_REST_CRUD: Create user update_user: Update user get_user: Get user list_users: List users implemented-interfaces-org-forgerock-openicf-connectors-rest-RestConnector-1.5.20.34: OpenICF Interfaces Implemented by the Rest Connector config-properties-org-forgerock-openicf-connectors-rest-RestConnector-1.5.20.34: Rest Connector Configuration basic-configuration-properties-org-forgerock-openicf-connectors-rest-RestConnector-1.5.20.34: Basic Configuration Properties --- # SaaS REST Connector | | | | - | ------------------------------------------------------------ | | | This is a [SaaS common connector](preface.html#saas-common). | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can only use SaaS REST connector version 1.5.20.29 and later with:- Connector framework 1.5.20.24 or later - RCS 1.5.20.24 or laterLearn more in [Changed functionality](../connector-release-notes/changed-functionality.html#_1-5-20-29-min-versions-map-config). | The SaaS REST Connector allows you to interact with most REST APIs. ## Install the SaaS REST connector | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To check for an Advanced Identity Cloud application for this connector, refer to:- [Application management](https://docs.pingidentity.com/pingoneaic/latest/app-management/applications.html) - [App catalog](https://docs.pingidentity.com/pingoneaic/latest/app-management/app-catalog.html) | You can download any connector from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors), but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration. **Connector included in default deployment** | Connector | IDM | RCS | | ---------------------- | ----------------------- | ----------------------- | | [SaaS REST](rest.html) | [icon: times, set=fa]No | [icon: times, set=fa]No | Download the connector .jar file from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors). * If you're running the connector locally, place it in the `/path/to/openidm/connectors` directory, for example: ``` mv ~/Downloads/rest-connector-1.5.20.34.jar /path/to/openidm/connectors/ ``` * If you're using a remote connector server (RCS), place it in the `/path/to/openicf/connectors` directory on the RCS. ## Configure the SaaS REST connector You cannot configure the SaaS REST connector through the UI. Configure the connector over REST, as described in [Configure Connectors Over REST](configure-connector.html#connector-wiz-REST). > **Collapse: Connection Details** > > * `serviceUri`: The service endpoint URI. > > * `useBasicAuthForOauthTokenNeg`: The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header). `true` | `false` > > * `tokenEndpoint`: Your URL to get the token. > > * `authenticationMethod`: Defines which method is to be used to authenticate on the remote server. Options are BASIC (username/password), OAUTH (Client id/secret) or TOKEN (static token). > > * `authorizationTokenPrefix`: The prefix to be used in the Authorization HTTP header for Token authentication. > > * `clientId`: The client identifier for OAuth2. > > * `clientSecret`: Secure client secret for OAuth2. > > * `refreshToken`: Used by the `refresh_token` grant type. > > * `authToken`: Static authentication token. > > * `grantType`: Your grant type. `client_credentials` | `refresh_token` | `jwt_bearer` > > * `login`: Your service login name. > > * `password`: Your service user password. > > * `scope`: The OAuth2 scope to use. > > * `defaultHeaders:` Http headers sent by default. > > * `maximumConnections`: Defines the max size of the http connection pool used. Defaults to `10`. > > * `connectionTimeout`: Defines a timeout for the underlying http connection in seconds. Defaults to `30`. > > * `disableHttpCompression:` Content compression is enabled by default. Set this property to true to disable it. > > Certification Details > > * `clientCertAlias:` If TLS Mutual Auth is needed, set this to the certificate alias from the keystore. > > * `clientCertPassword:` If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password. > > Proxy Connection Details > > * `httpProxyHost`: Defines the Hostname if an HTTP proxy is used between the connector and the service. > > * `httpProxyPort`: Defines the Port if an HTTP proxy is used between the connector and the service. > > * `httpProxyUsername`: Defines Proxy Username if an HTTP proxy is used between the connector and the service. > > * `httpProxyPassword`: Defines Proxy Password if an HTTP proxy is used between the connector and the service. > > JWT signer > > * `jwtkey`: The Jwt data structure that represents a cryptographic key. > > * `jwtExpiration`: Jwt Expiration. > > * `jwtClaims`: Jwt Claims to be included in the payload. > > * `jwtAlgorithm`: The Algorithm type to sign payload. If configuring the connector over REST or through the filesystem, specify the connection details to the SasS Rest resource provider in the `configurationProperties` for the connector. If you are using OAuth for your connection, the minimum required property is `serviceUri`. > **Collapse: Sample Configuration** > > ```json > { > "configurationProperties": { > "objectTypes": { > "__ACCOUNT__": { > "schema": [ > { > "fieldName": null, > "type": null, > "flags": [] > } > ], > "operations": { > "GET": { > "path": null, > "method": null, > "idPath": null, > "namePath": null, > "headers": {}, > "queryParams": {}, > "responseMapping": {}, > "requestBody": {}, > "additionalStep": [ > { > "resourceName": null, > "method": null, > "path": null, > "valuePath": null > } > ] > }, > "QUERY": { > "path": null, > "method": null, > "idPath": null, > "namePath": null, > "headers": {}, > "queryParams": {}, > "responseMapping": {}, > "pagination": { > "offSetPagination": { > "type": null, > "param": null, > "path": null, > "requestBody": null > }, > "cookiePagination": { > "type": null, > "param": null, > "path": null, > "requestBody": null > }, > "pageSizePagination": { > "type": null, > "param": null, > "path": null, > "requestBody": null > }, > "pagedResultsCookie": { > "type": null, > "path": null, > "regularExpression": null > } > }, > "additionalStep": [ > { > "resourceName": null, > "method": null, > "path": null, > "valuePath": null > } > ] > }, > "CREATE": { > "path": null, > "method": null, > "idPath": null, > "headers": {}, > "queryParams": {}, > "requestMapping": {}, > "unflattenAttributes": [], > "additionalStep": { > "method": null, > "path": null, > "requestMapping": null, > "requestBody": null > } > }, > "UPDATE": { > "path": null, > "method": null, > "idPath": null, > "headers": {}, > "queryParams": {}, > "requestMapping": {}, > "unflattenAttributes": [ > { > "attributeName": null, > "attributeValue": null > }, > { > "attributeName": null, > "attributeValue": null > } > ], > "additionalStep": [ > { > "method": null, > "path": null, > "requestMapping": {}, > "requestBody": {} > } > ] > }, > "DELETE": { > "path": null, > "method": null, > "headers": {}, > "queryParams": {}, > "requestBody": {}, > "additionalStep": {} > } > }, > "exceptions": { > "BAD_REQUEST": [ > { > "code": null, > "regularExpression": null, > "messageErrorPath": null > }, > { > "code": null, > "regularExpression": null, > "messageErrorPath": null > } > ] > }, > "attrToGetKey": null, > "filters": { > "quotes": null, > "separator": null, > "queryParamKey": null, > "operators": {} > } > } > }, > "tokenExpiration": null, > "accessToken": null, > "serviceUri": "https://api.exampleapi.com/v1", > "login": null, > "password": null, > "authenticationMethod": "OAUTH", > "tokenEndpoint": "https://api.exampleapi.com/oauth2/token", > "clientId": "k3..........5g", > "clientSecret": "xxxxxxxxxxxxxxxxxx", > "refreshToken": "xxxxxxxxxxxxxxxxxx", > "authToken": null, > "acceptSelfSignedCertificates": false, > "disableHostNameVerifier": false, > "disableHttpCompression": false, > "clientCertAlias": null, > "clientCertPassword": null, > "maximumConnections": "10", > "httpProxyHost": null, > "httpProxyPort": null, > "httpProxyUsername": null, > "httpProxyPassword": null, > "connectionTimeout": "30", > "grantType": "refresh_token", > "scope": null, > "authorizationTokenPrefix": "Bearer", > "useBasicAuthForOauthTokenNeg": true, > "jwtKey": null, > "jwtExpiration": null, > "customGrantType": null, > "jwtClaims": null, > "defaultHeader": null > } > } > ``` | | | | - | --------------------------------------------------------- | | | On startup, IDM encrypts the value of the `clientSecret`. | * `SCHEMA` ```json { "schema": [ { "fieldName": null, "type": null, "flags": [] } ] } ``` For the creation of the schemas it is necessary to provide name and type of value. `fieldName:` The attribute name. `type:` The type of value for the attribute. Available values: * `BINARY` * `BOOLEAN` * `COMPLEX` * `DECIMAL` * `INTEGER` * `REFERENCE` * `STRING` * `DATETIME` `flags:` determines if is required, readable, writable, updatable, multivalued, or nullable. * `NOT_UPDATEABLE` * `NOT_CREATABLE` * `NOT_READABLE` * `NOT_RETURNED_BY_DEFAULT` * `MULTIVALUED` * `REQUIRED` ## OPERATIONS * `GET` ```json { "GET": { "path": null, "method": null, "idPath": null, "namePath": null, "headers": {}, "responseMapping": {}, "requestBody": {}, "additionalStep": [ { "resourceName": null, "method": null, "path": null, "valuePath": null } ] } } ``` * `path:` Resource Path. If you want to include the uid in the path, you must set the variable {uid}. Required. * `method:` HTTP method. Required. * `idPath:` Path of the response to assign the resource UID. Required. * `namePath:` Path of the response to assign the resource \_\_NAME\_\_. Required. * `headers:` HTTP headers sent in the request, indicated by key-value. Optional. * `queryParams:` Query parameters to add to the request url. Optional. * `responseMapping:` It should be configured based on the API response if the response is complex. The keys represent the attributes of the schemas, while the values indicate the paths to the resources within the response. If the object is embedded, the key represents part of the path. If no mapping is required, you should set both the key and value as "/\*" : "/\*". If the attributes are embedded in an object, you should map the attributes individually. * `requestBody:` Represents the JSON structure of the request for the query. You must provide the body required by the API. If no body is needed, you don't need to send one. The \`requestBody\` defines where the attributes are to be assigned within the request body. Optional. If you want to insert the `uid` in the body, you must insert the variable `{uid}` as the value of a field. * `additionalStep:` If you need to make additional queries, you can add them to the schema attributes. To make an extra query, you must include the following properties. Optional. * `path:` Required. * `method:` Required. * `requestBody:` Must be specified if necessary Optional. * `resourceName:` Attribute name, must be in the schema. Required. * `valuePath:` Path of the attribute to retrieve from the response. If you want to get an array of elements at the end of the path, you must specify \[\*]. The square brackets indicate that it is an array, and the asterisk indicates that all the elements will be fetched. If the elements are a list of objects and you only want to fetch a particular field from each one, you must use \[\*].fieldName. If the element is an object and you only want to get a specific field from that object, you must indicate the object's name followed by fieldName. Required. - `QUERY` ```json { "QUERY": { "path": null, "method": null, "idPath": null, "namePath": null, "headers": {}, "responseMapping": {}, "pagination": { "offSetPagination": { "type": null, "param": null, "path": null, "requestBody": null }, "cookiePagination": { "type": null, "param": null, "path": null, "requestBody": null }, "pageSizePagination": { "type": null, "param": null, "path": null, "requestBody": null }, "pagedResultsCookie": { "type": null, "path": null, "regularExpression": null } }, "additionalStep": [ { "resourceName": null, "method": null, "path": null, "valuePath": null, "requestBody": null } ] } } ``` * `path:` Resource Path. If you want to include the uid in the path, you must set the variable {uid}. Required. * `method:` HTTP method. Required. * `idPath:` Path of the response to assign the resource UID. Required. * `namePath:` Path of the response to assign the resource \_\_NAME\_\_. Required. * `headers:` HTTP headers sent in the request, indicated by key-value. Optional. * `queryParams:` Query parameters to add to the request url. Optional. * `responseMapping:` It should be configured based on the API response if the response is complex. The keys represent the attributes of the schemas, while the values indicate the paths to the resources within the response. If the object is embedded, the key represents part of the path. If no mapping is required, you should set both the key and value as "/\*" : "/\*". If the attributes are embedded in an object, you should map the attributes individually. Optional. * `requestBody:` Represents the JSON structure of the request for the query. You must provide the body required by the API. If no body is needed, you don't need to send one. The \`requestBody\` defines where the attributes are to be assigned within the request body. Optional. In case you want a body in the API, you can specify it. * `additionalStep:` If you need to make additional queries, you can add them to the schema attributes. To make an extra query, you must include the following properties. Optional. * `path:` Required. * `method:` Required. * `requestBody:` must be specified if necessary Optional. * `resourceName:` Attribute name, must be in the schema. Required. * `valuePath:` Path of the attribute to retrieve from the response. If you want to get an array of elements at the end of the path, you must specify \[\*]. The square brackets indicate that it is an array, and the asterisk indicates that all the elements will be fetched. If the elements are a list of objects and you only want to fetch a particular field from each one, you must use \[\*].fieldName. If the element is an object and you only want to get a specific field from that object, you must indicate the object's name followed by fieldName. Required. `pagination:` There are 3 types of pagination: `CookiePagination`, `OffSetPagination`, `PageSizePagination`. * `type:` An HTTP method. Can be body or param. Optional. * `param:` To set the params is a key-value string, where you must provide the key followed by an equal sign '=' and the available values of the following 3 variables `_pagedResultsCookie`, `_pagedResultsOffSet`, `_pageSize` if you want to add more than one key-value set, they must be separated by a `&`. Optional. * `requestBody:` In case you need to perform pagination through the body, you need to specify the content required by the API. To insert the pagination values, you must use variables inside the requestBody. Available variables are `_pagedResultsCookie`, `_pagedResultsOffSet`, or `_pageSize`. * `path:` In case you need a different URL than the one in the operation. Optional. * `regularExpression:` Extracts the value of the cookie. Optional. `pagedResultsCookie:` Indicates how to get the cookie or cursor for the next page of results. * `type:` Pagination type. Available values are `body` or `header`. Required. * `path:` Indicates the path or name of the header containing the cookie. Required. * `regularExpression:` Extracts the value of the cookie. The `path` and `method` must be specified. The `requestBody` and `requestMapping` are optional. | | | | - | ------------------------------------------------------------------------------------------- | | | It is important to make sure that you use the exact variable name and enclose it in braces. | * `CREATE` ```json { "CREATE": { "idPath": null, "path": null, "method": null, "headers": {}, "queryParams": {}, "requestMapping": {}, "unflattenAttributes": [], "additionalStep": [ { "method": null, "path": null, "requestMapping": null, "requestBody": null } ] } } ``` * `idPath:` Path of the response to assign the resource UID. Required. * `path:` Resource Path. If you want to include the uid in the path, you must set the variable {uid}. Required. * `method:` HTTP method. Required. * `headers:` HTTP headers sent in the request, indicated by key-value. Optional. * `queryParams:` Query parameters to add to the request url. Optional. * `requestMapping:` The keys correspond to the attribute names, and the values represent how they will be sent in the request. If you need a complex \`requestBody\`, you must define the \`requestBody\`, property using the appropriate API format . The \`requestMapping\` values will then be mapped to this \`requestBody\`. Required. * `requestBody:` Represents the JSON structure of the request for the query. You must provide the body required by the API. If no body is needed, you don't need to send one. The \`requestBody\` defines where the attributes are to be assigned within the request body. Optional. * `unflattenAttributes` It is used to transform multivalued attributes into an array of objects. The \`attributeName\` represents the name of the attribute, and \`attributeValue\` represents the value of the field that the object will have. Optional. * `additionalStep:` If you need to make additional queries, you can add them to the schema attributes. To make an extra query, you must include the following properties. Optional. The `path` and `method` must be specified. The `requestBody` and `requestMapping` are optional. - `UPDATE` ```json { "UPDATE": { "path": null, "method": null, "idPath": null, "headers": {}, "queryParams": {}, "requestMapping": {}, "unflattenAttributes": [], "additionalStep": [ { "method": null, "path": null, "requestMapping": null, "requestBody": null } ] } } ``` * `path:` Resource Path. If you want to include the uid in the path, you must set the variable {uid}. Required. * `method:` HTTP method. Required. * `idPath:` Path of the response to assign the resource UID. Required. * `headers:` HTTP headers sent in the request, indicated by key-value. Optional. * `queryParams:` Query parameters to add to the request url. Optional. * `requestMapping:` The keys correspond to the attribute names, and the values represent how they will be sent in the request. If you need a complex \`requestBody\`, you must define the \`requestBody\`, property using the appropriate API format . The \`requestMapping\` values will then be mapped to this \`requestBody\`. Required. * `requestBody:` Represents the JSON structure of the request for the query. You must provide the body required by the API. If no body is needed, you don't need to send one. The \`requestBody\` defines where the attributes are to be assigned within the request body. Optional. * `unflattenAttributes:` It is used to transform multivalued attributes into an array of objects. The \`attributeName\` represents the name of the attribute, and \`attributeValue\` represents the value of the field that the object will have. Optional. * `additionalStep:` If you need to make additional queries, you can add them to the schema attributes. To make an extra query, you must include the following properties. Optional. The `path` and `method` must be specified. The `requestBody` and `requestMapping` are optional. * `DELETE` ```json { "DELETE": { "path": null, "method": null, "queryParams": null, "headers": {}, "requestBody": {}, "additionalStep": {} } } ``` * `path:` Resource Path. If you want to include the uid in the path, you must set the variable {uid}. Required. * `method:` HTTP method. Required. * `headers:` HTTP headers sent in the request, indicated by key-value. Optional. * `QueryParams:` Query parameters to add to the request url. Optional. * `requestBody:` Represents the JSON structure of the request for the query. You must provide the body required by the API. If no body is needed, you don't need to send one. The \`requestBody\` defines where the attributes are to be assigned within the request body. Optional. The `path` and `method` must be specified. The `requestBody` and `requestMapping` are optional. * `Exceptions` This JSON represents a configuration structure for an exception and its standardized error types. ```json { "exceptions": { "BAD_REQUEST": [ { "code": null, "regularExpression": null, "messageErrorPath": null }, { "code": null, "regularExpression": null, "messageErrorPath": null } ] } } ``` Exceptions types: * `BAD_REQUEST` * `NOT_FOUND` * `ALREADY_EXIST` * `FORBIDDEN` * `UNAUTHORIZED` Each element of the array has the following fields: * `code`: Error code (String). Required. * `messageErrorPath`: Path where the error field is contained in the response. Required. * `regularExpression`: Value contained in `messageErrorPath`. Optional. * `Filters` This JSON defines the configuration structure for search filters. ```json { "filters": { "quotes": null, "separator": null, "queryParamKey": null, "operators": {} } } ``` * `quotes`: Delimiter character. * `separator`: Separator character. * `queryParamKey`: Query parameter that initiates the filtering expression. * `operators`: Indicates the value of each operator. Accepted operators: * `equals` * `contains` * `startswith` * `endswith` * `lessoreq` * `lessthan` * `greateroreq` * `greaterthan` * `not` * `presence` * `and` * `or` * `attrToGetKey` This config defines the name of the parameter to obtain the selected fields. ```json { "attrToGetKey": null } ``` * `Examples` Example with unflatten attributes: ```json { "unflattenAttributes": [ { "attributeName": "role_ids", "attributeValue": "id" }, { "attributeName": "group_ids", "attributeValue": "id" } ] } ``` Example with response mapping: ```json { "responseMapping": { "roles": "roles[*].role_id", "first_name": "first_name", "created_at": "created_at", "active": "active" } } ``` ```json { "responseMapping": { "users": { "roles": "roles[*].role_id", "first_name": "first_name", "created_at": "created_at", "active": "active" } } } ``` ```json { "responseMapping": { "/*": "/*" } } ``` ```json { "responseMapping": { "users": { "/*": "/*" } } } ``` Example with Request mapping: ```json { "requestMapping": { "userName": "userName", "sn": "sn", "givenName": "givenName", "mail": "mail", "telephoneNumber": "telephoneNumber", "description": "description" } } ``` Example with request mapping and request body: ```json { "requestMapping": { "userName": "users[0].userName", "sn": "users[0].sn", "givenName": "users[0].givenName" }, "requestBody": { "users": [ { "active": true } ] } } ``` Example with request body pagination: ```json { { "limit": "{_pageSize}" } } ``` ```json { { "limit": "{_pageSize}", "offset": "{_pagedResultsOffSet}" } } ``` ```json { { "cookie": "{_pagedResultsCookie}" } } ``` Example with param pagination: ``` limit={_pageSize}&offSet={_pagedResultsOffSet} cursor={_pagedResultsCookie} ``` Example with filters ```json { "filters": { "quotes": "%22", "separator": "%20", "queryParamKey": "filter", "operators": { "equals": "eq", "contains": "co", "startswith": "sw", "lessoreq": "le", "lessthan": "lt", "greateroreq": "ge", "greaterthan": "gt", "not": "!", "presence": "pr", "and": "and", "or": "or" } } } ``` ## Test the SaaS REST connector Test that the connector was configured correctly: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header 'Accept-API-Version: resource=1.0' \ --request POST 'http://localhost:8080/system/rest?_action=test' { "name": "rest", "enabled": true, "config": "config/provisioner.openicf/rest", "connectorRef": { "bundleVersion": "1.5.20.34", "bundleName": "org.forgerock.openicf.connectors.rest-connector", "connectorName": "org.forgerock.openicf.connectors.rest.RestConnector" }, "displayName": "Rest Connector", "objectTypes": [ "__ACCOUNT__", "__ALL__" ], "ok": true } ``` ## Create user Example of Advanced Identity Cloud ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header 'Content-Type: application/json' \ --request POST \ --data '{ "userName": "johndoe", "sn": "doe", "givenName": "john", "mail": "john.doe@example.com", "telephoneNumber": "0101010101", "description": "some description" }' \ 'http://localhost:8080/openidm/system/rest/__ACCOUNT__?_action=create' { "_id": "user_ID", "_rev": "rev_ID", "__NAME__": "john", "sn": "doe", "givenName": "john", "mail": "john.doe@example.com", "telephoneNumber": "0101010101", "description": "some description", "accountStatus": "active" } ``` ## Update user ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header 'Content-Type: application/json' \ --request PUT \ --data '{ "userName": "updatedUsername", "sn": "updatedSn", "givenName": "updatedGivenName", "mail": "john.doe123@example.com", "telephoneNumber": "11110000", "description": "updated description" }' \ 'http://localhost:8080/openidm/system/rest/__ACCOUNT__/USER_ID' { "_id": "ID", "_rev": "redID", "__NAME__": "updatedUsername", "sn": "updatedSn", "givenName": "updatedGivenName", "mail": "john.doe123@example.com", "telephoneNumber": "11110000", "description": "updated description", "accountStatus": "active" } ``` ## Get user ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header 'Content-Type: application/json' \ --request GET \ 'http://localhost:8080/openidm/system/rest/__ACCOUNT__/USER_ID' { "_id": "user_ID", "_rev": "rev_ID", "__NAME__": "john", "sn": "doe", "givenName": "john", "mail": "john.doe@example.com", "telephoneNumber": "0101010101", "description": "some description", "accountStatus": "active" } ``` ## List users ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header 'Content-Type: application/json' \ --request GET \ 'http://localhost:8080/openidm/system/rest/__ACCOUNT__?_queryFilter=true' { "result": [ { "_id": "user_ID_1", "_rev": "rev_ID_1", "__NAME__": "johndoe", "accountStatus": "active", "mail": "john.doe@example.com", "givenName": "john", "sn": "doe", "description": "some description" }, { "_id": "user_ID_2", "_rev": "rev_ID_2", "__NAME__": "testuser", "accountStatus": "active", "mail": "test.user@example.com", "givenName": "test", "sn": "user", "description": "some description" } ... ], "resultCount": 999, "pagedResultsCookie": "Cookie", "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` ## OpenICF Interfaces Implemented by the Rest Connector The Rest Connector implements the following OpenICF interfaces. For additional details, see [ICF interfaces](interfaces.html): * Create Creates an object and its `uid`. * Delete Deletes an object, referenced by its `uid`. * Schema Describes the object types, operations, and options that the connector supports. * Script on Connector Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics: * The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access. * The script has access to a `connector` variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. * The script has access to any script arguments passed in by the application. * Search Searches the target resource for all objects that match the specified object class and filter. * Test Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid. This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out). You can invoke the test operation before a connector configuration has been validated. * Update Updates (modifies or replaces) objects on a target resource. []() ## Rest Connector Configuration The Rest Connector has the following configurable properties: ### Basic Configuration Properties | Property | Type | Default | Encrypted(1) | Required(2) | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------- | ------------------------ | ------------------------- | | `serviceUri` | `String` | `null` | | [icon: check, set=fas]Yes | | The service endpoint URI. | | | | | | `login` | `String` | `null` | | [icon: check, set=fas]Yes | | The service login name. | | | | | | `password` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | The service user password. | | | | | | `authenticationMethod` | `String` | `OAUTH` | | [icon: check, set=fas]Yes | | Defines which method is to be used to authenticate on the remote server. Options are `BASIC` (username/password), `OAUTH` (Client id/secret), `JWT_TOKEN` (jwt token), or `TOKEN` (static token). | | | | | | `tokenEndpoint` | `String` | `null` | | [icon: times, set=fas]No | | When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (). | | | | | | `clientId` | `String` | `null` | | [icon: check, set=fas]Yes | | The client identifier for OAuth2. | | | | | | `clientSecret` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | Secure client secret for OAuth2. | | | | | | `authToken` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | Static authentication token. | | | | | | `acceptSelfSignedCertificates` | `boolean` | `false` | | [icon: check, set=fas]Yes | | To be used for debug/test purposes. To be avoided in production. | | | | | | `disableHostNameVerifier` | `boolean` | `false` | | [icon: check, set=fas]Yes | | To be used for debug/test purposes. To be avoided in production. | | | | | | `disableHttpCompression` | `boolean` | `false` | | [icon: check, set=fas]Yes | | Set this property to `true` to disable content compression. | | | | | | `clientCertAlias` | `String` | `null` | | [icon: check, set=fas]Yes | | If TLS Mutual Auth is needed, set this to the certificate alias from the keystore. | | | | | | `clientCertPassword` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password. | | | | | | `maximumConnections` | `Integer` | `10` | | [icon: check, set=fas]Yes | | Defines the max size of the HTTP connection pool used. | | | | | | `httpProxyHost` | `String` | `null` | | [icon: check, set=fas]Yes | | Defines the Hostname if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyPort` | `Integer` | `null` | | [icon: check, set=fas]Yes | | Defines the Port if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyUsername` | `String` | `null` | | [icon: check, set=fas]Yes | | Defines Proxy Username if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyPassword` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Defines Proxy Password if an HTTP proxy is used between the connector and the service. | | | | | | `connectionTimeout` | `int` | `30` | | [icon: times, set=fas]No | | Defines a timeout for the underlying HTTP connection in seconds. | | | | | | `refreshToken` | `GuardedString` | `null` | | [icon: times, set=fas]No | | Used by the refresh\_token grant type. | | | | | | `grantType` | `String` | `null` | | [icon: times, set=fas]No | | The OAuth2 grant type to use (`client_credentials`, `refresh_token`, or `jwt_bearer`). | | | | | | `scope` | `String` | `null` | | [icon: times, set=fas]No | | The OAuth2 scope to use. | | | | | | `authorizationTokenPrefix` | `String` | `Bearer` | | [icon: times, set=fas]No | | The prefix to be used in the Authorization HTTP header for Token authentication. | | | | | | `useBasicAuthForOauthTokenNeg` | `boolean` | `true` | | [icon: check, set=fas]Yes | | The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header). | | | | | | `jwtKey` | `String` | `null` | | [icon: times, set=fas]No | | The JWT data structure that represents a cryptographic key. | | | | | | `jwtExpiration` | `Integer` | `null` | | [icon: times, set=fas]No | | Defines the JWT expiration time in seconds. | | | | | | `jwtAlgorithm` | `String` | `null` | | [icon: times, set=fas]No | | The Algorithm type to sign payload. | | | | | | `jwtClaims` | `Map` | `null` | | [icon: times, set=fas]No | | JWT Claims to be included in the payload | | | | | | `jwtPem` | `String` | `null` | | [icon: times, set=fas]No | | The contents of the private key of the PEM file | | | | | | `jwtCert` | `String` | `null` | | [icon: times, set=fas]No | | The contents of the certificate of the PEM file | | | | | | `objectTypes` | `Map` | `{ACCOUNT={schema=[], operations={}, exceptions={}}}` | | [icon: check, set=fas]Yes | | Defines the configuration for operations(GET/QUERY/CREATE/UPDATE/DELETE) and schemas. | | | | | | `keyAlgorithm` | `String` | `null` | | [icon: times, set=fas]No | | Indicates the type of key (such as RSA, DSA or EC) used to sign from the PEM. | | | | | | `defaultHeaders` | `Map` | `null` | | [icon: check, set=fas]Yes | | Headers to be sent by default. | | | | | (1) Whether the property value is considered confidential, and is therefore encrypted in IDM. (2) A list of operations in this column indicates that the property is required for those operations.