Using the AS2 Connection Manager
Web Service comes with an SSIS connection manager component that can be used to establish AS2 Connections.
To add a connection to your SSIS package, right-click the Connection Manager area in your Visual Studio project, and choose "New Connection..." from the context menu. You will be prompted the "Add SSIS Connection Manager" window. Select the "AS2 Connection Manager (KingswaySoft)" item to add the new connection manager.
The AS2 Connection Manager contains the following four pages to connect to the HTTP server.
- General
- Authentication
- AS2 Settings
- Proxy Settings
- Advanced Settings
General Page
The General page on the AS2 Connection Manager allows you to specify general settings for the connection.
- Test Connection button
-
The Test Connection button will open up a dialog that allows you to test the connection manager.
The Test Connection dialog request properties will be prepopulated with the base URL and headers from your connection manager. You can add or change headers, HTTP method, URL, and body if required.
- HTTP Method
-
The HTTP method of the test HTTP request will default to GET but can be any HTTP method that your server supports.
- URL
-
The URL or the test HTTP request will default to the base URL from the connection manager and any query string parameters associated with authentication.
- Body
-
The Body of the test HTTP request will default to empty or may contain a soap envelope for soap requests.
- Headers
-
The Headers of the test HTTP request will by default contain any custom headers from the connection manager and headers related to authentication.
- Test Connection button
-
The Test Connection button will send a request that uses proxy and authentication information from the connection manager, and the method, URL, body, and headers that are currently in the test connection dialog.
- Reset button
-
The Reset button will reset the request HTTP Method, URL, body, and header to the default values.
Authentication Page
The Authentication page allows you to specify the authentication mode that will be used with the connection.
There are nine authentication modes:
- AWS Signature
- Azure OAuth
- Basic
- Bearer Token
- Credentials (Basic, Digest, NTLM)
- Custom Token
- Google Service Account
- JWT
- Kerberos
- None
- OAuth1
- OAuth2
- Authentication Mode: AWS Signature
-
- AWS Signature Settings
- Signature Version
-
Specify between Version 4 and Version 2.
- Access Key
-
The Access key to be used for authentication.
- Access Secret
-
Provide the Access secret to be used for authentication.
- Session Token
-
The Session Token option allows you to specify a temporary security token, known as temporary security credentials. Note this property is optional.
- AWS Region (Only for Version 4 Signature version)
-
The AWS Region for the web service endpoint.
- Service Name (Only for Version 4 Signature version)
-
The AWS service name to be provided.
- Signature Method (Only for Version 2 Signature version)
- Choose between available Signature Methods
- HMAC-SHA1
- HMAC-SHA256
Authentication Mode: Azure OAuth
-
OAuth Type
The OAuth Type can be chosen between the below.
- Certificate
- Client Credentials
- Tenant Id
-
Provide tenant identifiers such as the tenant ID or domain name for your Microsoft organization. A default value “common” is used when no value is provided.
- Client Id
-
The Application ID of the Azure Active Directory App.
- Client Secret (Only for Client Credentials OAuth Type)
-
The Application Secret that you generated for your app in the app registration portal.
- Scope
-
Set Scope to identify the set of resources and operations that an access token permits. The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want, affixed with the .default suffix.
- Certificate Location (Only for Certificate type OAuth type)
-
The certificate location can be either of the below.
- Store
- File System
- Path to File System
-
Provide the path to the certificate file to use for authentication. Click the ellipses button to browse their file system for the certificate. This option is available when you choose File System as Certificate Location.
Note: The component supports Azure Blob Shared Access Signature (SAS) URL in the certificate path.
- Certificate Password
-
Provide the password to the certificate file. This option is available when you choose File System as the Certificate Location.
- Certificate Thumbprint
-
The Certificate Thumbprint option is only available when the Certificate OAuth Type has been chosen, it allows you to specify the thumbprint of the certificate created for the application registered in Microsoft Azure Active Directory (AAD).
- Authentication Mode: Basic
-
Basic authentication adds a basic authentication header to web requests. The AS2 Connection Manager will append the Base64 encoded string value representing your username and password to the text “Basic” in the request Authorization header.
- Username
-
The Username to use when accessing the web service.
- Password
-
The Password to use when accessing the web service.
- Authentication Mode: Bearer Token
-
- Bearer Token
-
The Bearer Token allows requests to authenticate using a static access key. AS2 Connection Manager will append the token value to the text "Bearer " in the required format to the request Authorization header.
- Authentication Mode: Credentials
-
- Domain
-
The domain or host to authenticate against.
- Username
-
The Username option allows you to specify the user account that you want to use when connecting to the specified server.
- Password
-
The Password option allows you to specify the password for the above user account in order to log in to the specified server.
- Authentication Mode: Custom Token
-
- Custom Access Token Settings
- CURL File
-
Provide the location to a file that contains a token request CURL command.
- Find Token Strategy
-
Provide the find token strategy by specifying one from the below.
- JPath
- XPath
- Regex
- Header
- Find Token Strategy
-
Provide the JPath, XPath, expression, etc. that can be used to extract the token value from the response.
- Token Expiry
-
Manually specify the token expiry in seconds.
- Test Custom Token
-
Click on this button to open up the below screen in which you can parse through the CURL File and test the token request.
-
Note: The Custom Access Token works by making a web request to retrieve an authorization token using a CURL command from a file. After the request is made the token is extracted from the response using one of the 'Find Token Strategies' and a 'Find Token Expression'. Once the token is extracted from the response it will be available for use by specifying '@Connection[AccessToken]' in supported connection properties or supported component properties. The token is re-retrieved after the specified expiry time in seconds.
Authentication Mode: Google Service Account
Service Account
The Service Account option allows you to specify the account which will be used to connect to your Google service.
- Certificate Location (Only for Certificate type OAuth type)
-
The certificate location can be either of the below.
- Store
- File System
- Path to File System
-
Provide the path to the certificate file to use for authentication. Click the ellipses button to browse their file system for the certificate. This option is available when you choose File System as Certificate Location.
Note: The component supports Azure Blob Shared Access Signature (SAS) URL in the certificate path.
- Certificate Password
-
Provide the password to the certificate file. This option is available when you choose File System as the Certificate Location.
- Certificate Thumbprint
-
This option allows you to specify the thumbprint of the selected certificate in order to authenticate using your Google Service Account.
- Scope
-
Set Scope to identify the set of resources and operations that an access token permits.
Authentication Mode: JWT
Import Claims from Existing JWT…
Clicking on this button will open up the below page to import claims from existing JWT.
- JWT Claims
-
The grid contains the following columns
- Claim Name
- Claim Value
- Header (checkbox)
- JWT Secret
-
Provide the JWT Secret.
Authentication Mode: Kerberos
- Domain
-
The domain or host to authenticate against.
- Username
-
The Username option allows you to specify the user account that you want to use when connecting to the specified server.
- Password
-
The Password option allows you to specify the password for the above user account in order to log in to the specified server.
Authentication Mode: None
Use None mode when your request does not require authorization.
Authentication Mode: OAuth1
- Generate Token file… button would take you to the OAuth token generator.
- Path to Token File
-
The path to the token file on the file system.
- Token File Password
-
The password to the token file.
- Authentication Mode: OAuth 2
-
- Path to Token File
-
The path to the token file on the file system.
- Token File Password
-
The password to the token file.
- Put Access Token In
-
In the part of the web request where the token should go, there are three options available:
- HTTP Header
- Query String
- Custom
Note: The “Custom” access token location option is designed to work for advanced scenarios where the injection of the access token received from the OAuth authentication flow needs to be managed in a very particular way, such as inserting it in your HTTP request body, or using it in a different HTTP header or query string parameter (other than the standard OAuth Authorization HTTP header or query string parameter). Note that when using this option, where the access token is actually placed will depend on your implementation at the component level by using the @Connection[AccessToken] variable; otherwise, the token will be simply ignored. Supported components includes Web Service/XML/JSON components.
AS2 Settings Page
The AS2 Settings Page can be used to specify the settings for the AS2 connection
- To
-
The To field can be used to specify the address of the recipient
- From
-
The From field can be used to specify the Address of the sender.
- Compress
-
Check this field to enable compression.
- Signing Certificate Location
-
The certificate location can be either of the below.
- Store
- File System
- Path to Certificate
-
Provide the path to the certificate file to use for authentication. Click the ellipses button to browse their file system for the certificate. This option is available when you choose File System as Certificate Location.
- Signing Certificate Password
-
Provide the password to the certificate file. This option is available when you choose File System as the Certificate Location.
- Certificate Thumbprint
-
This option allows you to specify the thumbprint of the selected certificate in order to authenticate using your Google Service Account.
- Recipient Certificate Location
-
The certificate location can be either of the below.
- Store
- File System
- Path to Certificate
-
Provide the path to the certificate file to use for authentication. Click the ellipses button to browse their file system for the certificate. This option is available when you choose File System as Certificate Location.
- Certificate Thumbprint
-
This option allows you to specify the thumbprint of the selected certificate in order to authenticate using your Google Service Account.
- Recipient Encryption Algorithm
-
The following encryption algorithms are supported, which can be chosen from the drop-down list.
- RC2/40
- RC2/64
- RC2/128
- DES
- TripleDES
- AES/128
- AES/192
- AES/256
- RC4/40
- RC4/64
- RC4/128
Proxy Settings Page
The Proxy Settings page on the AS2 Connection Manager allows you to specify some advanced and optional settings for the connection.
- Proxy Server Settings
-
- Proxy Mode(since v3.0)
-
The Proxy Mode option allows you to specify how you want to configure the proxy server setting. There are three options available:
- No Proxy
- Auto-detect (Using system-configured proxy)
- Manual
- Proxy Server
-
Using the Proxy Server option allows you to specify the name of the proxy server for the connection.
- Port
-
The Port option allows you to specify the port number of the proxy server for the connection.
- Username (Proxy Server Authentication)
-
The Username option (under Proxy Server Authentication) allows you to specify the proxy user account.
- Password (Proxy Server Authentication)
-
The Password option (under Proxy Server Authentication) allows you to specify the proxy user's password.
Note: The Proxy Password is not included in the connection manager's ConnectionString property by default. This is by design for security reasons. However, you can include it in your ConnectionString if you want to parameterize your connection manager. The format would be ProxyPassword=myProxyPassword; (make sure you have a semicolon as the last character). It can be anywhere in the ConnectionString.
Advanced Settings Page
The Advanced Settings page allows you to specify advanced settings for the connection.
- Client Certificate
-
- Certificate Location
-
Allows you to specify the location of the certificate that will be used. There are two options available:
- Store
- File System
- Certificate Thumbprint
-
Allows you to specify the thumbprint of the client certificate from the Certificate Store. Click the ellipses button to browse and select a certificate for the user's store. This option is available when you choose Store as Certificate Location.
- Path to Certificate
-
Provide the path to the certificate file to use for authentication. Click the ellipses button to browse their file system for the certificate. This option is available when you choose File System as Certificate Location.
Note: The component supports Azure Blob Shared Access Signature (SAS) URL in the certificate path.
- Certificate Password
-
Provide the password to the certificate file. This option is available when you choose File System as the Certificate Location.
- Miscellaneous Settings
-
- Ignore Certificate Errors
-
This option can be used to ignore those SSL certificate errors when connecting to the target server.
Warning: Enabling the "Ignore Certificate Errors" option is generally NOT recommended, particularly for production instances. Unless there is a strong reason to believe the connection is secure - such as the network communication is only happening in an internal infrastructure, this option should be unchecked for best security.
Note: When this option is enabled, it applies to all HTTP-based SSL connections in the same job process.
- Retry on Intermittent Errors
-
The retry on intermittent errors determines if requests will be retried when there is an error. If this option is checked requests will be retried up to 3 times.
- HTTP Response Error Code
-
The HTTP response error codes are a list of HTTP response codes that will be treated as errors when they are encountered by the component. This determines if the response will cause the component to fail (in a source component) or some other error handling behaviour (destination component). For each error code specified, it can be marked as retryable. When a retryable error is encountered the component will retry the request 3 times before failing.