DataMigrator/Reporting Server > Using the Adapter for REST > Configuring the Adapter for REST

Configuring the Adapter for REST

Topics:

Declaring Connection Attributes
Security for RESTful Web Services

Configuring the adapter consists of specifying connection information and if necessary, authentication information for at least one connection.

Declaring Connection Attributes

How to:

Configure an Adapter
Declare Connection Attributes Manually

Reference:

Connection Attributes for the Adapter for REST

In order to access the RESTful Web Service provider hosting the target web service, the adapter requires connection information.

You supply this information using the SET CONNECTION_ATTRIBUTES command. You can:

Enter connection and authentication information in the Web Console or the Data Management Console configuration panes. The consoles add the command to the profile you select: the global server profile (edasprof.prf), a user profile (user.prf), or a group profile (if supported on your platform).
Manually add the command in the global server profile (edasprof.prf), in a user profile (user.prf), or in a group profile (if supported on your platform).

You can declare connections to more than one web services provider by including multiple SET CONNECTION_ATTRIBUTES commands.

Procedure: How to Configure an Adapter

From the Web Console sidebar, click Connect to Data.

or

From the Data Management Console, expand the Adapters folder.

In the DMC, the Adapters folder opens. In the Web Console, the Adapters page opens showing your configured adapters.
In the Web Console, click the New Datasource button on the menu bar and find the adapter on the drop-down list or, in the DMC, expand the Available folder if it is not already expanded.
On the Web Console, you can select a category of adapter from the drop-down list or use the search option (magnifying glass) to search for specific characters.
In the DMC, expand the appropriate group folder and the specific adapter folder. The group folder is described in the connection attributes reference.
Right-click the adapter name and/or version and select Configure.

The Add Adapter to Configuration pane opens.
Enter values for the parameters required by the adapter, as described in the chapter for the specific adapter you want to configure.
Click Configure. The configured adapter is added to the Adapters list in the DMC resources tree or the Configured list in the Web Console.
In the Web Console, the adapter remains on the Available Adapters list with a check mark to indicate that at least one connection has been configured. You can configure additional connections from either the Configured or Available list by right-clicking the adapter and clicking Add Connection.

Reference: Connection Attributes for the Adapter for REST

The Adapter for REST is under the Procedures group folder.

Connection name

Logical name used to identify this particular set of connection attributes. The default is CON01.

Service Description

Is the service description. The available options are:

none. Indicates a WADL (Web Application Description Language) file, which describes the RESTful Web Service, does not exist.
WADL. Indicates an XML file that describes the RESTful Web Service.

Base Url

Is the part of the URL that is common for calling all the functionality of a particular RESTful Web Service. Addresses can begin with http:// or https://. For example: http://api.geonames.org.x

PROXY Server IP Address

Is the IP address of the proxy server, which intercepts requests and forwards them to the actual server. x

PROXY Port

Is the port number on which the proxy server listens. The default port number is 80.x

Service Principal Name

Is the name by which a client uniquely identifies an instance of a service. For example: mydaemon/foo:4761.x

Certificate

Is the location of locally-stored, user-provided server x.509 certificates for SSL authentication. The certificate file is used to authenticate the server to which the adapter is connecting.

Certificate type

Is the certificate type. The options are:

trusted. The trusted certificate file (trustedcertfile) points to a file of CA certificates in PEM format, as illustrated below:
```
-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----
```
A trusted certificate file can contain several CA certificates. You can add text before, between, and after certificates. For example, to provide descriptions of the certificates.
non-trusted. This option adds Key file, Pass phrase, and Label to the configuration pane.

Key file

Is the private key used for creating the client X.509 certificate in PEM format. This option is used together with a certificate for a non-trusted connection.

Pass phrase

Is the password used to unlock the key file. The value is needed only if the key file is encrypted.

Label

Identifies a certificate in the file if the file contains more than one certificate.

Security

There are four methods by which a user can be authenticated when connecting to a database server:

Explicit. The user ID and password are explicitly specified for each connection and passed to the database, at connection time, for authentication.
Password Passthru. The user ID and password received from the client application are passed to the database, at connection time, for authentication.
Trusted. The adapter connects to the database using the database rules for an impersonated process that are relevant to the current operating system.
OAuth. The adapter connects to the database using the OAuth 2.0 authentication protocol for granting access to REST APIs.

Via MFD/Select Application

This option is used only for chained authentication. For details about this process, see How to Configure the Adapter for Chained Execution.

Select profile

Select a profile from the drop-down menu to indicate the level of profile in which to store the CONNECTION_ATTRIBUTES command. The global profile, edasprof.prf, is the default.

If you wish to create a new profile, either a user profile (user.prf) or a group profile if available on your platform (using the appropriate naming convention), choose New Profile from the drop-down menu and enter a name in the Profile Name field (the extension is added automatically).

Store the connection attributes in the server profile (edasprof).

Syntax: How to Declare Connection Attributes Manually

The user ID and password are explicitly specified for each connection, and are passed to the REST Web Service at connection time for authentication. The syntax is:

ENGINE REST SET CONNECTION_ATTRIBUTES connection_name/
 [user[,pswd]]:'base_URL WADL_URL [AUTH:applid/mf]
 [fieldname="value" ...]
 [PROXYS:proxy_IP_address] [PROXYP:{80|port_number}] 
 [CERTIFICATE:cert_location [cert_key=key_file][cert_phrase=pass_phrase]
 [cert_label= cert_label]]'

where:

REST

Indicates the adapter.

connection_name

Is the logical name used to identify this particular set of attributes.

user,pswd

If specified, the user ID and password are passed to the authentication operation defined in the AUTH parameter at connection time.

For chained authentication, these are required fields if defined in the authentication Master File, either in the header or in the description of the group. For related information, see How to Configure the Adapter for Chained Execution.

base_URL

Is the part of the URL that is common for calling all of the functionality of a particular RESTful Web Service.

WADL_URL

Is the URL of the WADL that describes the web service. This is used to create a synonym. If a WADL File is not used, this should be set to file://Fake_URL.wadl.

applid/mf

For chained authentication, this is the location on the server of the Master File that describes the associated authentication operation. For related information, see How to Configure the Adapter for Chained Execution.

fieldname=value

For chained authentication in which you are passing additional parameters to an authentication operation, fieldname corresponds to the field defined with NEED_VALUE value in the ACCESS_PROPERTY parameter of the Master File, except for fields using the USERNAME and PASSWORD reserved names.

For an illustration, see Pass Additional Parameters to an Authentication Operation.

Note:

Values provided in the SET CONNECTION_ATTRIBUTES command overwrite default values set in XDEFAULT parameter in the Master File.
Field values must be enclosed in double quotation marks (") and cannot contain double or single quotation marks.

proxy_IP_address

Is the IP address of the proxy server, which intercepts requests and forwards them to the server.

port_number

Is the port number on which the proxy server listens. The default port number is 80.

cert_location

Is the location of locally-stored user-provided server x.509 certificates (Trusted CA) for SSL authentication. The certificate file is used to authenticate the server to which the adapter is connecting.

The trusted certificate file (trustedcertfile) points to a file of CA certificates in PEM format, as illustrated in the following example:

-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----

A trusted certificate file can contain several CA certificates. You can add text before, between, and after certificates. For example, to provide descriptions of certificates.

If you wish to specify a non-trusted certificate, enter the following additional information:

[cert_key=key_file] [cert_phrase=pass_phrase] [cert_label=cert_label]

where

key_file: Is the private key used for creating the client X.509 certificate in PEM format. This entry is required for a non-trusted connection.
pass_phrase: Is the password used to unlock the key file. This entry is needed only if the key file is encrypted.
cert_label: Identifies a certificate in the file if the file contains more than one certificate.

Example: Declaring Connection Attributes Manually

The following SET CONNECTION_ATTRIBUTES command allow the application to access the web application named GEONAMES.

ENGINE REST SET CONNECTION_ATTRIBUTES geonames/,:'http://api.geonames.org file://Fake_URL.wadl'

Security for RESTful Web Services

How to:

Configure the Adapter for Chained Execution
Pass Additional Parameters to an Authentication Operation

Chained execution of an authentication operation is used when the web server returns a response containing a cookie or a token to be used in the subsequent processing operation. Chained execution is defined in the connection string associated with the requested operation. When a cookie is used, both connection strings (authentication and execution) must contain the same Base URL.

The Adapter for RESTful Web Services supports the following security facilities:

Cookies, containing user credentials, which are in effect for the length of a TSCOM agent session (that is, between user connect and disconnect). The scope of the cookie is the single TSCOM agent. The received cookie is sent back to the sender IP, along with subsequent REST requests.
Identification token values, which are returned by an authentication operation and are acceptable to associated execution operations.

Chained authentication supports the Explicit and Password Passthru (with PING capabilities) security models.

To use chained authentication, you must declare the connection for authentication, then create a Master File that contains the authentication specifications (using an authentication string), and store it in an application folder. You can then use the authentication metadata to create one or more associated execution connection strings.

Note: When the connection string contains user ID and password information, and chained authentication is not defined, basic HTTP authentication is used. That is, the user ID and password are encrypted using the x64 algorithm, and it is then used to establish the HTTP connection.

Procedure: How to Configure the Adapter for Chained Execution

To configure the adapter for chained authentication:

Create a connection string using a BASE URL needed for the REST call to authenticate. This connection is needed to specify the part of the REST URL that would prefix the URL Extension to the authentication operation.

In the Connection Parameters pane of the Web Console or the Data Management Console, enter the BASE URL, and click Configure without Authentication.

Keep in mind that if a cookie (rather than a token) is to be used in the subsequent processing operation, you must specify the same Base URL for this authentication connection string and for the execution connection string that you specify in step 3.
Create synonyms for relevant authentication operations.

Create the synonym from the Web Console or the Data Management Console, then open the Synonym Editor to edit the synonym using the following guidelines.

Authentication synonyms must include the following input fields:

USERNAME

The user ID value is taken from the connection string defining the operation to be executed.

PASSWORD

The password value is taken from the connection string defining the operation to be executed.

Authentication synonyms may also include fields with the following access properties. The following fields must belong to segments describing the REST request:

ACCESS_PROPERTY=NEED_VALUE

Defines fields that provide additional parameters for an authentication operation. You can supply default values in XDEFAULT parameters. Values provided in the associated connection string overwrite the default values.

There may be more than one such field.

The following fields must belong to segments describing the REST response:

ACCESS_PROPERTY=AUTHRESP

Defines fields that describe the result of an authentication operation. Correct response values must be provided in the ACCEPT attribute (using the OR predicate if more than one value is acceptable). There may be more than one such field. The operation is considered invalid if at least one of the fields contains a non-acceptable value.

ACCESS_PROPERTY=AUTHTOKEN

Defines a field that contains a response token to be passed as an input value to the operation to be executed. There can be only one such field. If none is defined, the authentication operation is expected to return a cookie.
Create a connection string using a BASE URL that is used to call the execution request and a previously created authentication operation synonym.

In the Connection Parameters pane of the Web Console or the Data Management Console, enter the BASE URL, then from the Via MFD/Select Applications drop-down list, select the location on the server of the Master File that describes the associated authentication operation. Click Next and select the Master File that is used to run the authentication request.
In order to create synonyms for relevant execution operations, this must be done within a procedure. The reason is that Create Synonym runs a REST request to determine the response returned. The request must be authenticated properly to generate a valid response for use in creating the metadata.
For example:
```
-* Runs Authentication request
EX WFLOGON
-* Runs a Create Synonym request
CREATE SYNONYM rest/folderlist AT ibfs FOR ibfs/WFC/Repository 
PARMS 'HTTPMETHOD=GET PARAMSURL="IBIRS_action=get"'  
CHECKNAMES UNIQUENAMES DBMS REST DROP
```
Ensure that the operation synonyms have an input field that describes the authenticating token (if needed) using ACCESS_PROPERTY=AUTHTOKEN.

From the Web Console or the Data Management Console, open the Synonym Editor to edit the synonym as described.

For related information, see Connection Attributes for the Adapter for REST and Creating Synonyms.

Example: Configuring Chained Authentication

Connection string:

ENGINE REST SET CONNECTION_ATTRIBUTES ibfs/,:'http://localhost:8080/ibi_apps/rs file://Fake_URL.wadl auth:rest/logon'

Master File fragment describing an authentication operation:

FILENAME=GETTOKEN, SUFFIX=REST , $
  SEGMENT=GETTOKEN, SEGTYPE=S0, $
  GROUP=HEADER, ALIAS=Header, ELEMENTS=2, $
  FIELDNAME=USERNAME, ALIAS=username, USAGE=A30, ACTUAL=A30,
    ACCESS_PROPERTY=(NEED_VALUE), $
  FIELDNAME=PASSWORD, ALIAS=password, USAGE=A30, ACTUAL=A30,
    ACCESS_PROPERTY=(NEED_VALUE), $
  FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX,
    ACCESS_PROPERTY=(INTERNAL),$
  SEGMENT=RESPONSE, SEGTYPE=S0, SEGSUF=XML , PARENT=GETTOKEN,
    POSITION=__RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=getToken0Out, USAGE=A1, ACTUAL=A1,
    ACCESS_PROPERTY=(INTERNAL), $
  FIELDNAME=RESULT, ALIAS=Result, USAGE=A120, ACTUAL=A120,
    ACCESS_PROPERTY=(AUTHTOKEN),
  REFERENCE=RESPONSE, PROPERTY=ELEMENT, $

Master File fragment describing a data retrieval operation:

FILENAME=FINDADDRESS, SUFFIX=REST , $
SEGMENT=FINDADDRESS, SEGTYPE=S0, $
GROUP=HEADER, ALIAS=Header, ELEMENTS=8, $
 FIELDNAME=HOUSENUMBER, ALIAS=houseNumber, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='2815', $
 FIELDNAME=STREET, ALIAS=street, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='PRAIRIE AVE.', $
 FIELDNAME=INTERSECTION, ALIAS=intersection, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), $
 FIELDNAME=CITY, ALIAS=city, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='MIAMI BEACH', $
 FIELDNAME=STATE_PROV, ALIAS=state_prov, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='FL', $
 FIELDNAME=ZONE, ALIAS=zone, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='33140', $
 FIELDNAME=COUNTRY, ALIAS=country, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='US', $
 FIELDNAME=TOKEN, ALIAS=token, USAGE=A120, ACTUAL=A120,
   ACCESS_PROPERTY=(NEED_VALUE, AUTHTOKEN), $   
 FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX,
   ACCESS_PROPERTY=(INTERNAL), $
  SEGMENT=RESPONSE, SEGTYPE=S0, SEGSUF=XML , PARENT=FINDADDRESS,
   POSITION=__RESPONSE, $
  FIELDNAME=RESPONSE, ALIAS=findAddressResponse, USAGE=A1, ACTUAL=A1,
   ACCESS_PROPERTY=(INTERNAL), $

Syntax: How to Pass Additional Parameters to an Authentication Operation

You can pass an extra set of parameters to the authentication operation using XDEFAULT parameters to set the default values in the appropriate Master File.

Tip: To complete this task, use the Synonym Editor in the Web Console or the Data Management Console.

A sample of the syntax is in the following example.

Example: Passing Additional Parameters to an Authentication Operation

ENGINE REST SET CONNECTION_ATTRIBUTES belgR/:'https://secure.securex.be/
HRAWebservice/webservices file://Fake_URL.wadl AUTH:belgium/
directauthenticate DBID="HRADemo01" LANGID="1"'

Master File fragment:

FILENAME=DIRECTAUTHENTICATE, SUFFIX=REST , $
SEGMENT=DIRECTAUTHENTICATE, SEGTYPE=S0, $
GROUP=HEADER, ALIAS=Header, ELEMENTS=4, $
FIELDNAME=USERNAME, ALIAS=usrname, USAGE=A30, ACTUAL=A30,
   ACCESS_PROPERTY=(NEED_VALUE), $
FIELDNAME=PASSWORD, ALIAS=pwd, USAGE=A30, ACTUAL=A30,
   ACCESS_PROPERTY=(NEED_VALUE), $
FIELDNAME=DBID, ALIAS=dbId, USAGE=A30, ACTUAL=A30, ACCESS_PROPERTY=(NEED_VALUE), $ 
   XDEFAULT='Test', $
FIELDNAME=LANGID, ALIAS=langId, USAGE=A30, ACTUAL=A30, ACCESS_PROPERTY=(NEED_VALUE), $
   XDEFAULT='E', $
FIELDNAME=__RESPONSE, USAGE=TX80L, ACTUAL=TX,
   ACCESS_PROPERTY=(INTERNAL), $
SEGMENT=RESPONSE, SEGTYPE=S0, SEGSUF=XML , PARENT=DIRECTAUTHENTICATE,
   POSITION=__RESPONSE, $
FIELDNAME=RESPONSE, ALIAS=DirectAuthenticateResponse, USAGE=A1,
   ACTUAL=A1, ACCESS_PROPERTY=(INTERNAL), $
FIELDNAME=DIRECTAUTHENTICATERESULT, ALIAS=DirectAuthenticateResult,
  USAGE=A5, ACTUAL=A5, ACCESS_PROPERTY=(AUTHRESP), ACCEPT='true',
  REFERENCE=RESPONSE, PROPERTY=ELEMENT, $

	WebFOCUS

Feedback