Configuring the Adapter for REST

In this section:

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


Top of page

x
Declaring Connection Attributes

How to:

Reference:

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:

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



x
Procedure: How to Declare Connection Attributes

You can configure the adapter from either the Web Console or the Data Management Console.

  1. From the Web Console menu bar, click Adapters.

    or

    From the Data Management Console, expand the Adapters folder.

    The Adapters folder opens.

  2. Expand the Available folder, if it is not already expanded.
  3. Expand the appropriate group folder and the specific adapter folder. The group folder is described in the connection attributes reference.
  4. Right-click the adapter name and/or version and select Configure.

    The Add Adapter to Configuration pane opens.

  5. Enter values for the parameters required by the adapter, as described in the connection attributes reference.
  6. Click Configure without Authentication. The configured adapter is added to the Adapters list in the navigation pane.


x
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.

x

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.

x

Security

There are three 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.
x
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).



x
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 How to 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'

Top of page

x
Security for RESTful Web Services

How to:

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:

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.



x
Procedure: How to Configure the Adapter for Chained Execution

To configure the adapter for chained authentication:

  1. 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.

  2. 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.

  3. 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.

  4. 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
  5. 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), $


x
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