Configuring the Adapter for Web Services

In this section:

x

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


Top of page

x
Declaring Connection Attributes

How to:

Reference:

In order to access the Web Services 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. The configured adapter is added to the Adapters list in the navigation pane.


x
Reference: Connection Attributes for Web Services

The Web Services adapter is under the Procedures group folder.

The following list describes the connection attributes for which you can supply values. To complete the attribute declaration, click the Configure button.

Connection name

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

WSDL URL

URL of the WSDL that describes the Web service. Addresses can begin with:

file://

http://

https://

This value is required for creating a synonym only; otherwise, it is ignored.

PROXY Server IP Address

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

PROXY Port

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

Certificate

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.

For 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 certificates.

For non-trusted, the next three fields are added 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 two methods by which a user can be authenticated when connecting to a Web Services provider:

  • Explicit. The user ID and password are explicitly specified for each connection and passed to Web Services, at connection time, for authentication.
  • Password Passthru. The user ID and password received from the client application are passed to Web Services, at connection time, for authentication.
User

Primary authorization ID by which you are known to Web Services.

Password

Password associated with the primary authorization ID.

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

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.

End Points

This option appears on a second configuration pane, after you click the Next button.

Select the End Points URL for the Web Services provider from the drop-down list.



x
Syntax: How to Declare Connection Attributes Manually

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

ENGINE SOAP SET CONNECTION_ATTRIBUTES connection/
[user[,pswd]]:'endpoint_URL WSDL_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:

SOAP

Indicates the adapter.

connection

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 groups description. For related information, see How to Configure the Adapter for Chained Execution.

endpoint_URL

Is the URL of the Web Services provider.

WSDL_URL

Is the URL of the WSDL that describes the Web service. This is used to create a synonym.

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 in the Master File, except for fields using the reserved names USERNAME and PASSWORD.

For an illustration, see Passing 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.

proxys_IP_address

Is the IP address of the proxy server, which intercepts requests and forwards them to the real 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 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 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]
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 enrty 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

The following SET CONNECTION_ATTRIBUTES command allow the application to access the Web application named SAMPLEAPP.

ENGINE SOAP SET CONNECTION_ATTRIBUTES esriR/45678,4456789DFAFC:
 'http://arcweb.esri.com/services/v2/AddressFinder
 file://D:\users\WSDL\ESRI\AddressFinder.wsdl AUTH:ESRI/gettoken'

Top of page

x
Security for 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 end point URL.

The Adapter for Web Services supports the following security facilities:

Chained authentication supports the explicit and 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 an application. You can then use the authentication metadata to create one or more associated execution connection strings. For details, see How to Configure the Adapter for Chained Execution.

Note that 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 then used to establish the HTTP connection.



x
Procedure: How to Configure the Adapter for Chained Execution

Follow these steps to configure the adapter for chained authentication:

  1. Create a connection string using a WSDL URL that describes authentication operations. This connection is needed to specify the authentication end-point URL.

    To complete this step, in the Web Console or the Data Management Console Connection Parameters pane, type the WSDL URL, click Next, and select an End Points URL from the drop-down list.

    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 end point 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.

    To complete this step, from the Web Console or the Data Management Console, create the synonym, then open the graphical 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 SOAP 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 SOAP 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 WSDL URL that describes the operation and the end point of the execution request, and a previously created authentication operation synonym.

    To complete this step, from the Web Console or the Data Management Console Connection Parameters pane, type the WSDL 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 End Points URL from the drop-down list.

  4. Create synonyms for relevant execution operations.

    From the Web Console or the Data Management Console, create the synonym.

  5. Ensure that the operation synonyms have an input field that describes the authenticating token (if needed) using ACCESS_PROPERTY=AUTHTOKEN.

    To complete this step, from the Web Console or the Data Management Console, open the graphical Synonym Editor to edit the synonym as described.

For related information, see Connection Attributes for Web Services and Creating Synonyms.



Example: Configuring Chained Authentication

Connection strings:

ENGINE SOAP SET CONNECTION_ATTRIBUTES esriA/,:
'https://arcweb.esri.com/services/v2/Authentication 
file://D:\users\WSDL\ESRI\Authentication.wsdl'
 
ENGINE SOAP SET CONNECTION_ATTRIBUTES esriR/109618,8366C1649D9DFAFC:
'http://arcweb.esri.com/services/v2/AddressFinder 
file://D:\users\WSDL\ESRI\AddressFinder.wsdl AUTH:ESRI/gettoken'

Master File fragment describing an authentication operation:

FILENAME=GETTOKEN, SUFFIX=SOAP , $
  SEGMENT=GETTOKEN, SEGTYPE=S0, $
  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=SOAP , $
SEGMENT=FINDADDRESS, SEGTYPE=S0, $
GROUP=ADDRESS, ALIAS=address, USAGE=A210, ACTUAL=A210, $
 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', $
GROUP=ADDRESSFINDEROPTIONS, ALIAS=addressFinderOptions, USAGE=A30,
 ACTUAL=A30, $
  FIELDNAME=DATASOURCE, ALIAS=dataSource, USAGE=A30, ACTUAL=A30,
   MISSING=ON, ACCESS_PROPERTY=(NEED_VALUE), XDEFAULT='GDT.Streets.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), $


Example: Passing 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, you can use the Synonym Editor in the Web Console or the Data Management Console.

ENGINE SOAP SET CONNECTION_ATTRIBUTES belgR/:'https://secure.securex.be/
HRAWebservice/webservices/WSEmployee.asmx https://secure.securex.be/
HRAWebservice/webservices/WSEmployee.asmx?WSDL AUTH:belgium/
directauthenticate DBID="HRADemo01" LANGID="1"'

Master File fragment:

FILENAME=DIRECTAUTHENTICATE, SUFFIX=SOAP , $
SEGMENT=DIRECTAUTHENTICATE, SEGTYPE=S0, $
GROUP=DIRECTAUTHENTICATE, ALIAS=DirectAuthenticate, USAGE=A120,
   ACTUAL=A120, $
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, $

iWay Software