You can create integrations with trading partners that require an AS2 connection. Find out more about what AS2 is and how it works with integrator.io.
Contents
- Step 1: Gather & exchange your info
- Step 2: Create the AS2 connection
- Step 3: Set up your AS2 station
- Step 4: Set up your partner’s AS2 station
- Step 5: Choose your authentication type
- Step 6: Edit optional advanced settings
Step 1: Gather & exchange your info
Before you can establish your connection, you and your partner must exchange certain pieces of info. Find out more about this info is and how it works.
Your info
The following items should have already been determined and shared with your partner:
- The X.509 Certificate that contains info that you need, like the ID and public key.
- The certificate’s private key
- Your unique ID
- MDN signing algorithm
- Decryption algorithm
- Signature verification algorithm
Your partner’s info
- AS2 URL
- AS2 ID
- Asynchronous URL, which is necessary only if your partner requires an async MDN
- MDN verification algorithm, used by integrator.io to verify MDNs from your partner
- Encryption algorithm for sending messages to your partner
- Signing algorithm for sending messages to your partner
- Public key
Your partner’s AS2 endpoint configuration info
This list depends on your partner’s authentication requirements. You might need some, all, or none of the following items:
- HTTPS token
- Values to provide only if you have to wait between calls to AS2:
- Rate limits
- Fail status code
- Fail path
- Fail values
Step 2: Create the AS2 connection
- From the Tools menu, navigate to Flow Builder.
- In Flow Builder, click to add AS2 to either endpoint:
- Source applications for exports
- Destination & lookup applications for imports and lookups
- Choose AS2.
- Immediately, you’re asked to create or select a Connection before continuing. Click the + icon to start defining your new connection.
Step 3: Set up your AS2 station
Name (required): Enter a unique name to the connection for easy reference.
AS2 URL (required): Select the URL to which your trading partners will send AS2 documents. These URLs are shared by all integrator.io accounts. Select the https protocol if your software has an HTTPS/SSL CA certificate, provided by Amazon Trust Services Repository.
AS2 identifier (required): Create an ID that’s unique to your integrator.io account. You should have one ID for production and one for sandbox, if needed.
Require MDNs from partners (required, disabled): This field is always set to Yes because integrator.io requires MDNs. Find out more about MDNs and how they work to keep your data secure.
Require asynchronous MDNs (required, disabled): This field is always set to No because integrator.io requires synchronous MDNs.
MDN signing (required): Choose your signature type from the list of standard algorithms.
MDN encoding (optional): Choose Base64 or Binary.
Decryption algorithm (required): Choose your decryption algorithm from the list of standard algorithms.
Signature verification algorithm (required): Choose from the list of standard algorithms for integrator.io to use to verify messages from your partner.
Incoming message encoding (required): Choose the character encoding of the incoming HTTP message body in case it’s encrypted (Base64 or Binary, with Base64 being the default).
X.509 certificate (required): Paste the certificate with which the message will be signed. Your partner will verify the signature. This certificate must be in PEM format. If it is not, you can convert it in OpenSSL.
X.509 private key (required): Paste your private key. We will use this key to decrypt the messages from your partners. This key also must be in PEM format.
AS2 IP addresses (informational): If your partner’s server is behind a firewall, provide your partner with these addresses for their firewall whitelist.
Step 4: Set up your partner’s AS2 station
In the AS2 connection form, under Partner AS2 station configuration, fill in the necessary fields with your partner’s info.
Partner’s AS2 URL (required): Enter the URL for establishing an AS2 connection with your partner.
Partner’s AS2 identifier (required): Enter your partner’s unique ID.
Partner requires asynchronous MDNs (optional): Check this box if your partner wants the MDN to be sent separately from the HTTP response.
- Partner’s URL for asynchronous MDNs (required when Partner requires asynchronous MDNs is selected): Provide the digest algorithm for integrator.io to use when verifying the MDN returned by your trading partner.
MDN signature verification (optional): Check this box if your trading partner requires that the MDN signature be verified. Otherwise, integrator.io will not attempt to verify the signature.
- MDN verification algorithm (optional, enabled when MDN signature verification is selected): Choose the digest algorithm for integrator.io to use when verifying the MDN returned by your trading partner.
Encryption type (required): Choose the algorithm you want integrator.io to use to encrypt messages sent to your partners. Your partner should have shared this preference with you already.
Signing (required): Choose from the list of standard algorithms.
Encoding (optional): Select the character encoding used by integrator.io for outgoing messages when they are encrypted (Base64 or Binary, with Base64 being the default).
Signature encoding (optional): Choose the way your partner expects the signature to be encoded on the receiving side (Base64 or Binary). This setting applies only when Encryption type is blank or set to None.
Partner’s certificate (required): Paste your partner’s public certificate.
Step 5: Choose your authentication type
In the AS2 connection form, choose from the three HTTP authentication types:
If you choose None, you may proceed to configure the API rate limits.
Basic authentication means that the connection prompts for only a username and password.
Authentication type (required): Choose Basic.
Authentication fail status code (optional): If the service you want to connect to returns authentication errors other than 401, enter the code that indicates that the authentication failed.
Authentication fail path (optional): If the service you want to connect to puts the authentication error in the HTTP body, enter the path to the error.
Authentication fail values (optional): If you supplied a fail path above, enter the fail condition values to test to try to figure out why the connection failed.
Username (required): Enter your username.
Password (required): Enter your password.
Configure API rate limits (optional): Check this box to expand the rate limit options.
This method uses a token issued to you by your partner to establish your AS2 connection.
Authentication type (required): Choose Token.
Authentication fail status code (optional): If the service you want to connect to returns authentication errors other than 401, enter the code that indicates that the authentication failed.
Authentication fail path (optional): If the service you want to connect to puts the authentication error in the HTTP body, enter the path to the error.
Authentication fail values (optional): If you supplied a fail path above, enter the fail condition values to test to try to figure out why the connection failed.
Token (required): Enter the token you got from your partner. Multiple layers of protection are in place, including AES 256 encryption, to keep your token secure. When editing this form later, you must enter this token again; it is stored only for a saved connection.
Location (optional): You can decide where to put the token:
- Header: Set the token as a request header
- URL parameter: Add the token to the URL in a parameter
- Body: Embed the token in the request body
Send the token in the header
Location (optional): Choose Header.
Header name (optional): Enter a custom header name, if the AS2 system requires something other than the default, Authorization.
Scheme (optional): Choose the HTTP authentication scheme you want to use. By default, integrator.io will follow HTTP specs with regards to auth scheme names (such as Bearer, OAuth, and MAC), but if the API you are connecting to does not follow the specs exactly, this field provides an override.
Configure token refresh (optional): Check this box to expand the token refresh options.
Configure API rate limits (optional): Check this box to expand the rate limit options.
Send the token as a URL parameter
Location (optional): Choose URL parameter.
Parameter name (optional): Enter the name of parameter that contains the token. For example, if you enter myAS2ConnectionToken, then all HTTP requests will include: ?myAS2ConnectionToken=[token].
Configure token refresh (optional): Check this box to expand the token refresh options.
Configure API rate limits (optional): Check this box to expand the rate limit options.
Send the token in the body
If you are sending the token in the request, no further information is needed. The provided token will appear in the body of your request.
Configure token refresh (optional): Check this box to expand the token refresh options.
Configure API rate limits (optional): Check this box to expand the rate limit options.
Refresh your token
If your token expires after a certain amount of time, describe how to refresh it. Your partner will provide you will all of the info necessary for refreshing your token.
Configure token refresh (optional): If your token expires after a certain amount of time, check this box.
Refresh token (optional): Enter the refresh token your partner gave you.
Refresh relative URI (optional): Enter the relative URI to refresh the token.
Refresh media type (optional): Choose the media type to use when refreshing the token.
Refresh method (optional): Choose the HTTP method to use to refresh the token.
Refresh token path (optional): Enter the path to refresh the token.
Refresh token headers (optional): Set the header name-value pairs. When you type in the last line, a blank line is added. Leave the line blank when you’re finished.
Step 5b: Configure API rate limits
If you’re required to wait between calls to the AS2 endpoint – beyond the expected return rate-limit responses, specify how long integrator.io should wait.
Your partner will provide you with all of the necessary info on their rate limits.
Limit (required): Enter the rate at which integrator.io can make calls to your partner’s AS2 endpoint.
Fail status code (optional): If the endpoint you want to connect to returns authentication errors other than 401, enter the code given if the authentication fails.
Fail path (optional): If the endpoint you want to connect to puts the authentication error in the HTTP body, enter the path to the error.
Fail values (optional): If you supplied a fail path, enter the values to test to try to figure out why a connection has failed.
When you’ve filled in all of the necessary info and you’re ready for integrator.io to make the connection, click Save. If the connection failed, double-check all of the info that you entered for accuracy.
Step 6: Edit optional advanced settings
Prevent canonicalization (optional): “Canonicalized” data has been transformed to its simplest essential form during HTTP requests. Check this box to skip canonicalization during signature verification, which avoids any risk of the signature getting invalidated when accompanying transformed binary data.
Concurrency level (optional): Up to 25 allowed....
Comments
1 comment
This is very good documentation around AS2. Several partners ask me about AS2 connections setup and this article really helps us understand AS2 connection setup process. Thank you.
Please sign in to leave a comment.