1.2 Driver Concepts

This section contains the following information:

1.2.1 Introduction

The following concepts are associated with the REST driver:

REST

REST is an HTTP-based protocol for exchanging messages over the network. Since REST is built on HTTP protocol, it supports POST, PUT, GET, PATCH, DELETE methods to communicate with the application logic.

JSON

JSON (Java Script Object Notation) is a lightweight data-interchange format. JSON stores information in a Key-Value pair format. The Identity Manager driver for REST uses JSON as a data format for payload transfer. For more information about the JSON format used by the driver, see Section D.0, Supported JSON Format.

Resource

A resource is a user, group, or an object that the driver tries to synchronize with the Subscriber and Publisher channels. To be more precise, a REST resource in the driver is a combination of the REST application schema name and the Resource handler. For example, in the URL http://ipaddress:port/User, User is an example of a REST resource that can be configured to use Default as the Resource Handler. For more information, see Resources. To configure a REST resource, Identity Manager provides Driver Configuration options.

Resource Handler

A Resource handler is the mapping of an Identity Manager operation with the REST method. To configure a Resource handler, Identity Manager provides the Driver Configuration options. For more information, see Resources.

A REST call invokes the REST method mapped with an Identity Manager operation. The REST driver supports two Resource handler modes. They are:

  • Default - Uses the default HTTP methods for configuring handlers and for managing operations on respective resources. In this mode, the REST driver chooses the best possible mapping for the corresponding Identity Manager operation. For example, an Identity Manager ADD operation corresponds to a POST method and a MODIFY operation corresponds to PUT method of the REST application.

    The REST driver generates the complete URL of a REST method by combining the Base URL for REST Resources and the Schema Name. For example, https:url.example.com/users, where https:url.example.com is the base URL and users is the schema name. Table 1-1 lists the Identity Manager operations, their corresponding default REST methods and the URLs.

Table 1-1 Default Resource Handler

Identity Manager Operation

REST Method

URL

ADD

POST

http://ipaddress:port/SchemaName<api-version>

MODIFY

PUT

http://ipaddress:port/SchemaName/<association><api-version>

QUERY

GET

http://ipaddress:port/SchemaName/<association><filter><api-version>

DELETE

DELETE

http://ipaddress:port/SchemaName/<association><api-version>

NOTE:In the GET method, the driver replaces the <filter> placeholder by ?search-attr=<searchAttrName1> eq <value1>' and <searchAttrName2> eq '<value2'>&read-attr='<readAttr1>’ and ‘<readAttr2>’ filter value.

  • Custom - Uses the Resource Handler parameters in the Driver Configuration page to customize the driver to suite your deployment scenario. In this mode, the driver generates the complete URL of the REST method by combining the Base URL for REST Resources and the user specific URL in the URL extension. For example, https:url.example.com/users

URL Placeholder

A URL placeholder is a variable defined in the URL extension within angular brackets. The attribute-value pair in the URL token element of the driver-operation-data replaces this placeholder value during the data transfer. For example, consider a sample URL http://ipaddress:port/SchemaName/<association><api-version>. During the driver operation, the <api-version> URL placeholder is replaced by the value in the element <url-token api-version="1.0"/>.

XML

XML (Extensible Markup Language) is a generic subset of Standard Generalized Markup Language (SGML) that allows for exchange of structured data on the Internet.

HTTP

HTTP is a protocol used to request and transmit data over the Internet or other computer network. The protocol works well in an Internet infrastructure and with firewalls.

HTTP is a stateless request/response system because the connection is usually maintained only for the immediate request. The client establishes a TCP connection with the server and sends it a request command. The server then sends back its response.

HTTPS

HTTPS is the HTTP protocol over Secure Socket Layer (SSL) as a sub-layer under the regular HTTP application layering. HTTPS encrypts and decrypts user page requests as well as the pages that are returned by the Web server.

1.2.2 How the Driver Works

Figure 1-1 illustrates the data flow between Identity Manager and REST driver:

Figure 1-1 REST Driver Data Flow

The Identity Manager engine uses XDS, a specialized form of XML, to represent events in the Identity Vault. Identity Manager passes the XDS to the driver policy, which consists of basic policies and DirXML Script.

The driver uses a specialized form of XDS called <driver-operation-data>. The <driver-operation-data> element encapsulates the metadata and payload for a REST request.

When an event occurs in the Identity Vault, Identity Manager creates an XDS command to represent that event. Identity Manager passes the XDS command to the driver policy. The driver policy transforms that XDS command with an output transformation policy.

This output transformation policy generates the <driver-operation-data> that includes commands, URIs, methods, and payload information for the REST request to successfully complete on the Subscriber channel.

When the request completes, the driver processes responses and reports status of the completed operation to the Identity Manager engine or the Identity Vault.

On the Publisher channel, the REST driver receives the REST request in <driver-operation-data> format. Using the input policy, the driver converts the request to an XDS event and reports back to the connected system.

1.2.3 Understanding Driver Operation Data

The driver shim applies special handling to Subscriber commands based on an XML element embedded in the command, which appears in the driver shim as <driver-operation-data>. The <driver-operation-data> element is added to the command from one of the Subscriber channel policies.

The <driver-operation-data> element includes the metadata with the class-name, command, REST method, and the URI. The command, the REST method, and the URI is required only if the Resource handlers for the resource are not previously configured in the driver parameters. The <request> tag includes the URL-token associations, header content-type, and the data to be transferred. The <value> tag includes the JSON payload information.

The <driver-operation-data> element for a REST request includes the following elements:

  • <request>: Embeds the request information required to make the HTTP call.

  • <url-token>: Includes the placeholder provided in the driver configuration for resource.For example, during the driver configuration, version is the placeholder added to a resource URL /User/<version>. The attribute-value pair in the URL token element replaces this placeholder. For example, <url-token version="1.0"/>.

  • <header>: Includes the additional headers that can be added to the REST request in addition to the ones configured in the resource.

  • <value>: Includes the XML or the JSON payload.

Below is a sample request to add new users with the same common name using the <driver-operation-data> element:

<driver-operation-data class-name="User" command="add">
        <request method="put" url="https://172.16.0.0:XXXX/User/rest123">
          <url-token association="rest123"/>
          <header content-type="application/json"/>
          <value>{"CN":[{"value":"rest6789"}],"Full Name":[{"value":"rest6789 rest6789"}],"Given Name":[{"value":"rest6789"}],","Surname":[{"value":"rest6789"}],"Login Disabled":[{"value":"true"}]}
          </value>
        </request>
        <request method="put" url="https://172.16.0.0:XXXX/User/rest123">
         <url-token association="rest123"/>
          <header content-type="application/json"/>
          <value>{"CN":[{"value":"rest1234"}],"Full Name":[{"value":"rest1234 rest1234"}],"Given Name":[{"value":"rest1234"}],","Surname":[{"value":"rest1234"}],"Login Disabled":[{"value":"true"}]}
          </value>
        </request>
</driver-operation-data>

You will get a response similar to the below sample for this request:

<input>      
   <driver-operation-data class-name="User" command="add" remote-host="172.16.0.0" url="http://172.16.0.0:XXXX/User">
        <header content-type="application/json"/>
      <response>
        <value>{"association":"noble2","CN":"noble2","Full Name":"noble2","Given Name":"noble2","nspmDistributionPassword":"novell@123","Surname":"noble2"}
        </value>
      </response>
    </driver-operation-data>
</input>

NOTE:The driver retains the <driver-operation-data> between any REST operations, embeds the response in the same <driver-operation-data> and returns the response. A single <driver-operation-data> element is capable of accommodating multiple requests that belong to the same class.