In this section: |
Configuring the adapter consists of specifying connection and authentication information for at least one connection.
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.
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 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.
Logical name used to identify this particular set of connection attributes. The default is CON01.
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.
IP address of the proxy server, which intercepts requests and forwards them to the real server.
Port number on which the proxy server listens. The default port number is 80.
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.
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 two methods by which a user can be authenticated when connecting to a Web Services provider:
Primary authorization ID by which you are known to Web Services.
Password associated with the primary authorization ID.
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).
This option is used only for chained authentication. For details about this process, see How to Configure the Adapter for Chained Execution.
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.
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:
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 URL of the Web Services provider.
Is the URL of the WSDL that describes the Web service. This is used to create a synonym.
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 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:
Is the IP address of the proxy server, which intercepts requests and forwards them to the real 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 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]
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 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'
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.
Follow these steps to configure the adapter for chained authentication:
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.
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:
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 SOAP 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 SOAP 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.
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.
From the Web Console or the Data Management Console, create the synonym.
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.
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), $
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, $
WebFOCUS |