Create a REST V2 connection to interact with web service applications built on REST architecture.
Prerequisites
Before you configure a REST V2 connection, be sure to complete the prerequisites.
•Install the Secure Agent on a 64-bit machine.
•Ensure that the machine hosting the Secure Agent has a minimum memory size of 2048 MB.
Connect to REST V2
Let's configure the REST V2 connection properties to interact with web service applications built on REST architecture.
Before you begin
Before you get started, be sure to complete the prerequisites.
Connection details
The following table describes the basic connection properties:
Property
Description
Connection Name
Name of the connection.
Each connection name must be unique within the organization. Connection names can contain alphanumeric characters, spaces, and the following special characters: _ . + -,
Maximum length is 255 characters.
Description
Description of the connection. Maximum length is 4000 characters.
Type
REST V2
Runtime Environment
Name of the runtime environment where you want to run tasks.
Select a Secure Agent, Hosted Agent, or serverless runtime environment.
You cannot run a streaming ingestion task on a Hosted Agent or serverless runtime environment.
Authentication types
You can configure standard, OAuth 2.0 client credentials, OAuth 2.0 authorization code, JWT bearer token, and API key authentication types to connect to a REST endpoint.
Select the required authentication method and then configure the authentication-specific parameters.
Standard authentication
Standard authentication requires an authentication user ID and password to connect to a REST endpoint. When you configure a standard authentication type, you can further configure basic and OAuth authentication types.
Note: Digest authentication is not applicable.
The following table describes the basic connection properties for standard authentication:
Property
Description
Authentication Type
The authentication type that you can use when you select the Standard authentication.
You can select one of the following authentication types:
- BASIC
- OAUTH
- NONE
Default is NONE.
Auth User ID
The user name to log in to the web service application when you select the standard authentication.
Required for Basic authentication type.
Auth Password
The password associated with the user name when you select the standard authentication.
Required for Basic authentication type.
OAuth Consumer Key
The client key associated with the web service application.
Required only for OAuth authentication type.
OAuth Consumer Secret
The client password to connect to the web service application.
Required only for OAuth authentication type.
OAuth Token
The access token to connect to the web service application.
Required only for OAuth authentication type.
OAuth Token Secret
The password associated with the OAuth token.
Required only for OAuth authentication type.
Swagger File Path
The path of the Swagger file or OpenAPI file.
You can specify one of the following file paths:
- Path and file name of the Swagger or OpenAPI file on the Secure Agent machine.
- The URL on which the Swagger or OpenAPI file is hosted. The hosted URL must return the content of the file without prompting for further authentication and redirection.
For example, the path of the Swagger file can be:
C:\Swagger\sampleSwagger.json
The user must have the read permission for the folder and the file.
OAuth 2.0 Client Credentials authentication
OAuth 2.0 client credentials authentication requires at a minimum the client ID, access token URL, client secret, scope, and the access token.
The following table describes the basic connection properties for OAuth 2.0 client credentials authentication:
Property
Description
Access Token URL
Access token URL configured in your application.
Client ID
Client ID of your application.
Client Secret
Client secret of your application.
Scope
Specifies access control if the API endpoint has defined custom scopes. Enter scope attributes, each separated by a space. For example:
root_readonly root_readwrite manage_app_users
Access Token Parameters
Additional parameters to use with the access token URL. Define the parameters in the JSON format.
Select an option to send the client ID and client secret for authorization either in the request body or in the request header.
Default is Send Client Credentials in Body.
Generate Access Token
Generates an access token based on the information provided in the above fields.
Access Token
The access token value.
Enter the access token value or click Generate Access Token to populate the access token value.
To pass the generate access token call through a proxy server, you must configure an unauthenticated proxy server in the Secure Agent properties. The proxy configured in the connection configuration does not apply to the generate access token call.
Swagger File Path
The path of the Swagger file or OpenAPI file.
You can specify one of the following file paths:
- Path and file name of the Swagger or OpenAPI file on the Secure Agent machine.
- The URL on which the Swagger or OpenAPI file is hosted. The hosted URL must return the content of the file without prompting for further authentication and redirection.
For example, the path of the swagger file can be:
C:\swagger\sampleSwagger.json
The user must have the read permission for the folder and the file.
Note: In a streaming ingestion and replication task, use only a hosted URL of the swagger specification file as the swagger file path.
OAuth 2.0 Authorization Code authentication
To use authorization code authentication, register the following Informatica redirect URL in your application:
https://<Informatica cloud hosting facility for your organization>/ma/proxy/oauthcallback
If the access token expires and the error codes 400, 401, and 403 are returned in the response, Informatica redirect URL, which is outside the customer firewall, tries to connect to the endpoint and retrieves a new access token.
The following table describes the basic connection properties for OAuth 2.0 authorization code authentication:
Property
Description
Authorization Token URL
Authorization server URL configured in your application.
Access Token URL
Access token URL configured in your application.
Client ID
Client ID of your application.
Client Secret
Client secret of your application.
Scope
Specifies access control if the API endpoint has defined custom scopes. Enter scope attributes, each separated by a space.
For example,
root_readonly root_readwrite manage_app_users
Access Token Parameters
Additional parameters to use with the access token URL. Define the parameters in the JSON format.
Select an option to send the client ID and client secret for authorization either in the request body or in the request header.
Default is Send Client Credentials in Body.
Generate Access Token
Generates an access token and refreshes the token based on the information provided in the above fields.
Access Token
The access token value.
Enter the access token value or click Generate Access Token to populate the access token value.
To pass the generate access token call through a proxy server, you must configure an unauthenticated proxy server in the Secure Agent properties. The proxy configured in the connection configuration does not apply to the generate access token call.
Refresh Token
The refresh token value.
Enter the refresh token value or click Generate Access Token to populate the refresh token value. If the access token is not valid or expires, the Secure Agent fetches a new access token with the help of refresh token.
If the refresh token expires, you must either provide a valid refresh token or regenerate a new refresh token by clicking Generate Access Token.
Swagger File Path
The path of the Swagger file or OpenAPI file.
You can specify one of the following file paths:
- Path and file name of the Swagger or OpenAPI file on the Secure Agent machine.
- The URL on which the Swagger or OpenAPI file is hosted. The hosted URL must return the content of the file without prompting for further authentication and redirection.
For example, the path of the swagger file can be:
C:\swagger\sampleSwagger.json
The user must have the read permission for the folder and the file.
Note: In a streaming ingestion and replication task, use only a hosted URL of the swagger specification file as the swagger file path.
JWT bearer token authentication
JWT bearer token authentication requires at a minimum the JWT header, JWT payload, and authorization server URL.
The following table describes the basic connection properties for JWT bearer token authentication:
Property
Description
JWT Header
JWT header in JSON format.
Sample:
{
"alg":"RS256",
"kid":"xxyyzz"
}
You can configure HS256 and RS256 algorithms.
JWT Payload
JWT payload in JSON format.
Sample:
{
"iss":"abc",
"sub":"678",
"aud":"https://api.box.com/oauth2/token",
"box_sub_type":"enterprise",
"exp":"120",
"jti":"3ee9364e"
}
The expiry time represented as exp is the relative time in seconds. The expiry time is calculated in the UTC format from the token issuer time (iat).
When iat is defined in the payload and the expiry time is reached, mappings and Generate Access Token fails. To generate a new access token, you must provide a valid iat in the payload.
If iat is not defined in the payload, the expiry time is calculated from the current timestamp.
To pass the expiry time as a string value, enclose the value with double quotes. For example:
"exp":"120"
To pass the expiry time as an integer value, do not enclose the value with double quotes.
For example,
"exp":"120"
Authorization Server
Access token URL configured in your application.
KeyStore File Path
The absolute path of the keystore file that contains the keys and certificates required to establish a two-way secure communication with the REST API. Specify a directory path that is available on each Secure Agent machine.
You can also configure the keystore file name and path as a JVM option or import the certificate to any directory.
For the serverless runtime environment, specify the keystore file path in the serverless agent directory.
For example, /home/cldagnt/SystemAgent/serverless/configurations/ssl_store/<cert_name>.jks
KeyStore Password
The password for the keystore file required for a secure communication.
You can also configure the keystore password as a JVM option.
Private Key Alias
Alias name of the private key used to sign the JWT payload.
Private Key Password
The password for the keystore file required for a secure communication. The private key password must be same as the keystore password.
Access Token
The access token value.
Enter the access token value or click Generate Access Token to populate the access token value.
To pass the generate access token call through a proxy server, you must configure an unauthenticated proxy server in the Secure Agent properties. The proxy configured in the connection configuration does not apply to the generate access token call.
Swagger File Path
The path of the Swagger file or OpenAPI file.
You can specify one of the following file paths:
- Path and file name of the Swagger or OpenAPI file on the Secure Agent machine.
- The URL on which the Swagger or OpenAPI file is hosted. The hosted URL must return the content of the file without prompting for further authentication and redirection.
For example, the path of the swagger file can be:
C:\swagger\sampleSwagger.json
The user must have the read permission for the folder and the file.
Note: In a streaming ingestion and replication task, use only a hosted URL of the swagger specification file as the swagger file path.
Advanced settings
The following table describes the advanced connection properties for JWT bearer token authentication:
Property
Description
Authorization Advanced Properties
Additional parameters to use with the access token URL. Parameters must be defined in the JSON format.
The absolute path of the truststore file that contains the TLS certificate to establish a one-way or two-way secure connection with the REST API. Specify a directory path that is available on each Secure Agent machine.
You can also configure the truststore file name and password as a JVM option or import the certificate to the following directory:
For the serverless runtime environment, specify the truststore file path in the serverless agent directory.
For example, /home/cldagnt/SystemAgent/serverless/configurations/ssl_store/<cert_name>.jks
TrustStore Password
The password for the truststore file that contains the SSL certificate.
You can also configure the truststore password as a JVM option.
Proxy Type
Type of proxy.
Select one of the following options:
- No Proxy. Bypasses the proxy server configured in the agent or the connection properties.
- Platform Proxy. Considers the proxy configured in the agent.
- Custom Proxy. Considers the proxy configured in the connection properties.
Proxy Configuration
The format required to configure proxy.
You can configure proxy using the following format:
<host>:<port>
You cannot configure an authenticated proxy server.
Advanced Fields
Enter the arguments that the agent uses when connecting to a REST endpoint.
When you specify multiple arguments, separate each argument by a semicolon.
For example,
connectiondelaytime:10000;retryattempts:5
You can specify the following arguments:
- ConnectionTimeout. The wait time in milliseconds to get a response from a REST endpoint. The connection ends after the connection timeout is over.
Default is the timeout defined in the endpoint API.
Note: If you define both the REST V2 connection timeout and the endpoint API timeout, the connection ends at the shortest defined timeout.
- connectiondelaytime. The delay time in milliseconds to send a request to a REST endpoint.
Default is 10000.
- retryattempts. Number of times the connection is attempted when 400 and 500 series error codes are returned in the response.
Default is 3. Specify 0 to disable the retry attempts.
- qualifiedSchema. Determines if the schema selected is qualified or unqualified.
Default is false.
Note: In a streaming ingestion and replication task, only ConnectionTimeout and retryattempts are applicable.
API key authentication
API key authentication allows you to provide a unique key and a corresponding value to authenticate API calls made to the REST endpoint.
The following table describes the basic connection properties for API key authentication:
Property
Description
Key
The unique API key that REST V2 Connector uses to authenticate the API calls made to the REST endpoint.
Value
The value corresponding to the API key that is required to make the API calls.
Add API Key to
Determines if the API key and its corresponding value must be sent as a request header or a query parameter to make API calls to the REST endpoint.
Select one of the following options:
- Request Header
- Query Parameter
Swagger File Path
The path of the Swagger file or OpenAPI file.
You can specify one of the following file paths:
- Path and file name of the Swagger or OpenAPI file on the Secure Agent machine.
- The URL on which the Swagger or OpenAPI file is hosted. The hosted URL must return the content of the file without prompting for further authentication and redirection.
For example, the path of the swagger file can be:
C:\swagger\sampleSwagger.json
The user must have the read permission for the folder and the file.
Note: In a streaming ingestion and replication task, use only a hosted URL of the swagger specification file as the swagger file path.
Advanced settings
The following table describes the advanced connection properties:
Property
Description
TrustStore File Path
The absolute path of the truststore file that contains the TLS certificate to establish a one-way or two-way secure connection with the REST API. Specify a directory path that is available on each Secure Agent machine.
You can also configure the truststore file name and password as a JVM option or import the certificate to the following directory:
For the serverless runtime environment, specify the truststore file path in the serverless agent directory.
For example, /home/cldagnt/SystemAgent/serverless/configurations/ssl_store/<cert_name>.jks
TrustStore Password
The password for the truststore file that contains the SSL certificate.
You can also configure the truststore password as a JVM option.
KeyStore File Path
The absolute path of the keystore file that contains the keys and certificates required to establish a two-way secure communication with the REST API. Specify a directory path that is available on each Secure Agent machine.
You can also configure the keystore file name and path as a JVM option or import the certificate to any directory.
For the serverless runtime environment, specify the keystore file path in the serverless agent directory.
For example, /home/cldagnt/SystemAgent/serverless/configurations/ssl_store/<cert_name>.jks
KeyStore Password
The password for the keystore file required for secure communication.
You can also configure the keystore password as a JVM option.
Proxy Type
Type of proxy.
Select one of the following options:
- No Proxy: Bypasses the proxy server configured in the agent or the connection properties.
- Platform Proxy: Considers the proxy configured in the agent.
- Custom Proxy: Considers the proxy configured in the connection properties.
Proxy Configuration
The format required to configure proxy.
Configure proxy using the following format:
<host>:<port>
You cannot configure an authenticated proxy server.
Advanced Fields
Enter the arguments that the agent uses when connecting to a REST endpoint.
When you specify multiple arguments, separate each argument by a semicolon.
For example,
connectiondelaytime:10000;retryattempts:5
You can specify the following arguments:
- ConnectionTimeout. The wait time in milliseconds to get a response from a REST endpoint. The connection ends after the connection timeout is over.
Default is the timeout defined in the endpoint API.
Note: If you define both the REST V2 connection timeout and the endpoint API timeout, the connection ends at the shortest defined timeout.
- connectiondelaytime. The delay time in milliseconds to send a request to a REST endpoint.
Default is 10000.
- retryattempts. Number of times the connection is attempted when 400 and 500 series error codes are returned in the response.
Default is 3. Specify 0 to disable the retry attempts.
- qualifiedSchema. Determines if the schema selected is qualified or unqualified.
Default is false.
Note: In a streaming ingestion and replication task, only ConnectionTimeout and retryattempts are applicable.
Secure communication with TLS authentication
Configure TLS authentication to establish one-way or two-way secure communication between the Secure Agent and the REST API over TLS.
To establish one-way secure communcation, perform the following steps:
1Generate the truststore. For more information on the steps, see Generate a Truststore.
2Configure the REST V2 connection for one-way SSL. You can specify the truststore file and truststore password in the connection, or set them in the JVM options of the Secure Agent.
To establish two-way secure communcation, you must first configure one-way secure communication, and then perform the following steps:
1Generate the keystore. For more information on the steps, see Generate a Keystore.
2Configure the REST V2 connection for two-way SSL. You can specify the keystore file and keystore password in the connection, or set them in the JVM options of the Secure Agent.
If you specify keystore and truststore properties in the connection and in the JVM options, the Secure Agent processes the certificates based on the properties configured in the connection.
Generate a truststore
To generate a truststore, you need a server certificate. Get the server certificate and perform the following steps to generate the truststore:
1Import the server certificate to the following file path:
2To generate the truststore, run the following command from the command line:
keytool -importcert -alias <Specify alias name here> -file <Specify server certificate here> -keystore <Specify the name of custom truststore to be generated> -storepass <Specify password for the custom truststore>
For example, keytool -importcert -alias RESTV2CACert -file ca.pem -keystore sampletruststore -storepass JKSTrustStorePassword
In the example, a truststore file is generated by the name sampletruststore and password JKSTrustStorePassword.
Generate a keystore
To generate a keystore, you need a client certificate and a client private key. Get the client certificate and client private key, and then perform the following steps to generate the keystore:
1Import the certificate to the following file path:
2To generate the keystore, run the following command from the command line:
openssl pkcs12 -export -in <Specify client certificate here> -inkey <Specify client private key here> -name "<Specify any name here>" -passout pass:<Specify password for the keystore to be generated> -out <Specify name for the keystore with p12 extension>
For example, openssl pkcs12 -export -in /home/samplefolder/certs/client-cert.pem -inkey /home/samplefolder/certs/client-key.pem -name "restclient" -passout pass:PKCSKeyStorePassword -out samplekeystore.p12
In the example, a keystore file by the name samplekeystore.p12 is generated in the PKCS12 format.
To convert the keystore file from .p12 format to .jks format, run the following command from the command line:
keytool -importkeystore -srckeystore <Specify name of the p12 keystore file> -srcstoretype pkcs12 -srcstorepass <Specify password for generated p12 keystore file> -destkeystore <Specify name for the JKS keystore file> -deststoretype JKS -deststorepass <Specify password for the JKS keystore file>
Note: Ensure that the password specified in -srcstorepass must be the same as the -deststorepass.
For example, keytool -importkeystore -srckeystore samplekeystore.p12 -srcstoretype pkcs12 -srcstorepass PKCSKeyStorePassword -destkeystore keystore -deststoretype JKS -deststorepass PKCSKeyStorePassword
In the example, a keystore file is generated by the name samplekeystore and password PKCSKeyStorePassword.
Configuring one-way or two-way secure communication
You can configure a connection for one-way or two-way SSL.
Configuring the connection for one-way SSL
You can either specify the name of the truststore file and truststore password in the TrustStore File Name and TrustStore Password fields in the connection properties. Alterntaively, you can set the truststore file name and truststore password in the JVM options in the Secure Agent properties.
1Click Administrator > Runtime Environments, and select an agent.
2Select Type as DTM under System Configuration Details.
3Add the following JVM options:
- JVMOption1=-Djavax.net.ssl.trustStore=<absolute path of the .jks truststore file>
You can either specify the name of the keystore file and keystore password in the KeyStore File Name and KeyStore Password connection properties. Alternatively, you can set the keystore file and keystore password in the JVM options in the Secure Agent properties.
To use two-way SSL, you must first configure one-way SSL, and then perform the following steps to configure two-way SSL:
1Click Administrator > Runtime Environments, and select an agent.
2Select Type as DTM under System Configuration Details.
3Add the following JVM options:
- JVMOption3=-Djavax.net.ssl.keyStore=<absolute path of the .jks keystore file>
Secure communication in a serverless runtime environment
When you use the serverless runtime environment, you can configure TLS authentication and establish one-way or two-way secure communication with the REST API.
Ensure that the certificates are in the .jks format.
To configure a secure REST V2 connection using the serverless runtime environment, complete the following prerequisite tasks to add the TLS certificates to the serverless runtime location:
1Create the following structure for the serverless agent configuration in AWS:
2For one-way secure communication, add the truststore certificates and for the two-way secure communication, add the truststore and keystore certificates in the Amazon S3 bucket in the following location in your AWS account:
When the .yml file runs, the SSL certificates are copied from the AWS location to the serverless agent directory.
5In the REST V2 connection properties, specify the following certificate path in the serverless agent directory in the TrustStore File Path and KeyStore File Path fields:
Swagger specification file in a serverless runtime environment
To configure a swagger file in a serverless runtime environment, be sure to complete the prerequisites.
In the serverless runtime environment, you can configure a swagger file in one of the following ways:
•Provide the swagger file public hosted URL in the Swagger File Path connection property. Ensure that the URL must return the content of the file without prompting for further authentication and redirection.
•Place the swagger file in the serverless agent directory.
To configure a swagger file in a serverless runtime environment, complete the following prerequisite tasks to add the swagger file to the serverless runtime location:
1Create the following structure for the serverless agent configuration in AWS or Azure:
Consider the following guidelines when you run tasks in different runtime environments:
•You cannot use a proxy server to connect to Informatica Intelligent Cloud Services when you use the Hosted Agent or the serverless runtime environment.
•You cannot connect to the REST API endpoints that require custom server certificate signed by CA and are not a part of Informatica cacerts truststore, when you use the Hosted Agent.
•You cannot configure JWT bearer token authentication when you use the Hosted Agent.
•Ensure that the swagger specification file URL is a public URL and returns the content of the file without prompting for further authentication and redirection when you use the Hosted Agent.
Rules and guidelines for a REST V2 connection
Consider the following rules and guidelines for a Rest V2 connection:
•When you test the connection, the Secure Agent validates the following parameters:
- Path of the local Swagger file or the URL of the hosted Swagger file.
- JSON format of the Swagger file.
However, the Secure Agent does not validate endpoint credentials when you test the connection.
•You can configure proxy at the agent level or connection level. See the following table to understand the proxy settings that take precedence when you define the System proxy and proxy at the connection level: