In this section: |
Configuring the adapter consists of specifying connection information and if necessary, authentication information for at least one connection.
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.
You can configure the adapter from either the Web Console or the Data Management Console.
or
From the Data Management Console, expand the Adapters folder.
The Adapters folder opens.
The Add Adapter to Configuration pane opens.
The Adapter for REST is under the Procedures group folder.
Logical name used to identify this particular set of connection attributes. The default is CON01.
Is the service description. The available options are:
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.
Is the IP address of the proxy server, which intercepts requests and forwards them to the actual server.
Is the port number on which the proxy server listens. The default port number is 80.
Is the name by which a client uniquely identifies an instance of a service. For example: mydaemon/foo:4761.
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.
Is the certificate type. The options are:
-----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.
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.
Is the password used to unlock the key file. The value is needed only if the key file is encrypted.
Identifies a certificate in the file if the file contains more than one certificate.
There are three methods by which a user can be authenticated when connecting to a database server:
This option is used only for chained authentication. For details about this process, see How to Configure the Adapter for Chained Execution.
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).
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:
Indicates the adapter.
Is the logical name used to identify this particular set of attributes.
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.
Is the part of the URL that is common for calling all of the functionality of a particular RESTful Web Service.
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.
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.
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:
Is the IP address of the proxy server, which intercepts requests and forwards them to the server.
Is the port number on which the proxy server listens. The default port number is 80.
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
Is the private key used for creating the client X.509 certificate in PEM format. This entry is required for a non-trusted connection.
Is the password used to unlock the key file. This entry is needed only if the key file is encrypted.
Identifies a certificate in the file if the file contains more than one certificate.
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'
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.
To configure the adapter for chained authentication:
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 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:
The user ID value is taken from the connection string defining the operation to be executed.
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:
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:
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.
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.
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.
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
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.
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), $
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.
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 |