How To .. Configure Inbound AS2 with Dynamic Encryption and Signature Verificati...
source link: https://blogs.sap.com/2021/07/28/how-to-..-configure-inbound-as2-with-dynamic-encryption-and-signature-verification-using-partner-directory-on-cloud-integration/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
This blog will focus on configuring SAP BTP Cloud Integration AS2 Sender adapter and Partner Directory to dynamically select the security artifacts used for Encryption and Signature Verification by providing step-by-step instructions.
Bonus: Additionally will cover AS2 Outbound Adapter configuration using Encryption and Signature Verification.
Scenario
Our company R-Co is engaging organizations “Alpha” and “Bravo” and has agreed to exchange EDI documents through AS2 protocol, each of them has its respective security artifacts (Keypair, public and private certificates) which are used to secure the communication and protect the data exchanged.
Requirement
Our company has requested to build an integration service to exchange EDI documents that support multiple partners using AS2 protocol over HTTPS, authenticating using TLS mutual authentication, all messages must be encrypted and signed using specific certificates per partner.
Solution
Organization Alpha will be Partner_A
Using:
Signing Algorithm – SHA1
Encryption Algorithm – 3DES
Signed MDN Algorithm – SHA1
X.509 – SXXXXXX813.p12
Organization Bravo will be Partner_B
Using:
Signing Algorithm – SHA512
Encryption Algorithm – AES256
Signed MDN Algorithm – SHA512
X.509 – SXXXXXX184.p12
Our company will be R-Co using SAP BTP Cloud Integration
Service Endpoint: https://r-co.it-cpi003-rt.cfapps.us10.hana.ondemand.com/as2/as2
Message Subject: msgB2BPartners
X.509 – Tenant Keypair: sap_cloudintegrationcertificate
Basic Certificate Usage
Let’s understand how a basic setup works.
B2B Sender Partner Function Signature Self Private Key Function Encryption B2B Receiver’s Public Key Function MDN Verify Signature B2B Receiver’s Public Key B2B Receiver Partner Function Verify Signature B2B Sender’s Public Key Function Decryption Self Private Key Function MDN Signature Self Private KeyNow mapping to our scenario
Partner A KeyStore Key Pair Self Private Key SXXXXXX813.p12 Self Public Key Self Public Certificate SXXXXXX813.cer B2B Sender’s Public Key Certificate sap_cloudintegrationcertificate.cer Cloud IntegrationLoad Balancer Root Certificate DigiCert Global Root G2.cer Partner B KeyStore Key Pair Self Private Key SXXXXXX184.p12 Self Public Key Self Public Certificate SXXXXXX184.cer B2B Sender’s Public Key Certificate sap_cloudintegrationcertificate.cer Cloud Integration
Load Balancer Root Certificate DigiCert Global Root G2.cer Cloud Integration KeyStore Key Pair Self Private Key sap_cloudintegrationcertificate.p12 Self Public Key Self Public Certificate sap_cloudintegrationcertificate.cer B2B Receiver’s Public Key Certificate SXXXXXX813.cer alias -> partner_a_813
SXXXXXX184.cer alias -> partner_b_184 Cloud Integration
Load Balancer Root Certificate DigiCert Global Root G2.cer
Build
Now that we have defined how we should communicate with our partners let’s create our service.
Step 1: Create iFlow with Inbound AS2 Sender Adapter and Oubound JMS Receiver Adapter.
You may download the iFlow following link >> download
Note: I have included a script (optional) not in the scope of this blog, details can be found in the official documentation.
Note: In a productive scenario you may use EDI Integration Templates for SAP Integration Advisor >> “EDI to SAP SOAP – Inbound” or “EDI to SAP IDoc – Inbound”. Another option might be that you are building a custom iFlow and need to define an entry or routing iFlow for all your partners using the AS2 protocol
Step 2: Configure Inbound AS2 Sender Adapter.
Note: Link to the documentation here.
Processing Tab:
Message-ID Left & Right: We will configure a *wildcard* as we are not expecting any specific details from partners.
Partner AS2 ID: We will configure a *wildcard* to be able to receive multiple partners in the same iFlow.
Own AS2 ID: R-Co // We will set our company’s unique identifier.
Message Subject: msgB2BPartners // Message header of the incoming AS2 message.
The rest of the parameters we can leave as default values, if needed please refer to the documentation for all capabilities of the adapter, for now, we would be using the default role, and concurrent or parallel processes is recommended to be set at the minimum (1) per worker node.
Security Tab:
Decrypt Message: Checked // Message will be encrypted and sender side, decrypt is mandatory.
Private Key Alias: pd:ReceiverPrivateKey // Private key alias will be assigned at authentication via partner directory. The Keypair must be imported into the tenant’s keystore.
Verify Signature: Trusted Certificate // Signature will be validated against a certificate in the tenant’s keystore.
Public Key Alias: pd:SenderPublicKey // Public key alias will be assigned at authentication via partner directory. The certificate must be imported into the tenant’s keystore.
Note: However the settings of these parameters if Partner Directory entities are set, partner directory takes precedence and overwrites any configuration on the adapter, please find further details on official documentation.
MDN Tab:
Private Key Alias for Signature: sap_cloudintegrationcertificate // This could be any Keypair in the tenant’s keystore, recommended to use own tenant keypair.
Note: At the time of the writing of this blog this parameter could not be set dynamically.
The rest of the parameters will keep them with default values.
Certificates
Prerequisite: Exchange certificates with your partners.
A) sap_cloudintegrationcertificate. Navigate Monitor >> Manage Security >> Keystore >> select certificate >> Actions >> Download Certificate
B) DigiCert Global Root G2 (Load Balancer root + chain). Navigate Monitor >> Manage Security >> Connectivity Tests >> TLS. Type iFlow base URL and click Send. Click the Download button.
Note: Private certificates should never be exchanged, only share public certificates (.cer / .der) and complete chain (.pb7)
Step I: Create Service Instance and Service Key type X.509 for client certificate authentication
Note: Please find step by step guide <<wiki>>
Note: For purpose of this exercise we will use an S-User keypair to simulate each partner from where I have extracted the certificate; more details can be found in the following link.
Navigate BTP Cockpit >> Subaccount >> Spaces >> Instances >> Click on Create >> Service Instance
Select options as shown below and type a descriptive instance name > Next
Create a Service Key from Service Instance.
Type a descriptive Service Key Name and from the certificate file provided by the partner, copy and paste the value to X.509 field >> Create
View Service Key
Copy and save “clientid” value:
“clientid”: “sb-cb4b8731-0dc9-44a4-bd21-16cdfaf35aaf!b17506| !b2455”
Repeat same actions for Partner_B
Note: If you don’t have access to the SAP BTP cockpit, request these values from your BTP Admin.
Step II: Import public certificate from partner and assign aliases (Optional: Only if you would like to test without Partner Directory)
Note: For purpose of this exercise we will use an S-User keypair to simulate each partner from where I have extracted the certificate; more details can be found in the following link.
Navigate Monitor >> Manage Security >> Keystore >> Click on Add >> Certificate
Partner_A
Assign an Alias: partner_a_813
Partner_B
Assign an Alias: partner_b_184
Result
Step 3: Configure Outbound JMS Adapter
In our scenario, we will like to send the message to a JMS queue, in a production scenario you might want to pick from that queue or route to a specific iFlow using Process Direct instead.
Queue Name: B2B_Partners
Transfer Exchange Properties: Checked
We are ready to deploy our iFlow
Step 4: Configure Partner Directory
Now we are ready to configure the partner directory but first, we need some fundamentals from the official documentation.
The Partner Directory allows you to store information about communication partners and to parameterize integration flows using this information. The Partner Directory helps you to set up a communication network between many communication partners efficiently. You use the Partner Directory to store partner-specific information. Those components that are parameterized read this information during runtime from the Partner Directory.
The Partner Directory contains the following entities(which can be accessed using an OData API)
The following are specific iFlow components available in Partner Directory:
AS2 sender adapter: sender partner X.509 certificate to verify partner signature, sender partner-specific user, or client certificate
The AS2 sender reads the following parameters from the Partner Directory:
Let’s digest the previous information: Partner Directory is used to store partner-specific information and access this information from the runtime. Partner Directory has predefined entities which can be leveraged to determine specific values for your partners, such as unique ID per partner, authorized users linked to the partner id, and a directory of parameters linked to the partner id. Additionally, the AS2 Sender Adapter has built-in Partner Directory capabilities.
We can now start the configuration of the Partner Directory.
Note: Please refer to the official documentation or personally recommended blog on how to execute crud operation using Postman.
- Create Partner ID in Partner Directory.
We can create Pid or Partner ID by creating a String Parameter.
URL: {{UI_tenant_url}}/api/v1/StringParameters
Method: Post
Body in Json:{ "Pid": "MATARTEST_ZZ", "Id": "R-Co_08_850_4010", "Value": "abcdefghijklmnopqrstuvwxyz000001" }
Note: In my case, I have used a specific naming convention for my partner id which includes values from an X12 header document as part of my own strategy, this is optional, Partner ID can be any value that is unique for your directory. Example: Pid can be an ERP ID “100000099”, Id can be the endpoint address “URL-Address”, and Value can be the actual endpoint “https://acme-as2.com/inbound”
- Create an Authorized User in Partner Directory
We linked the Pid to a user by creating an Authorized Users entity.
URL: {{UI_tenant_url}}/api/v1/AuthorizedUsers
Method: Post
Body in JSON:{ "Pid": "MATARTEST_ZZ", "User": "sb-cb4b8731-0dc9-44a4-bd21-16cdfaf35aaf!b17506| !b2455" }
Pid value is the unique value representing your partner.
User value should be retrieved from the service key linked to the partner certificate, this is the same value we retrieve from SAP BTP Cockpit. - Create Partner Directory Parameters for AS2 Sender Adapter
- Decrypt Message. This parameter is needed if partners are encrypting the message. We create a String Parameter for our Pid and assign Id: “AS2_inbound_decrypt_message” and the value: “true”
URL: {{UI_tenant_url}}/api/v1/StringParameters
Method: Post
Body in Json:{ "Pid": "MATARTEST_ZZ", "Id": "AS2_inbound_decrypt_message", "Value": "true" }
- Private Key Alias. This is the alias for the keypair which is used for decrypting the message. Recommended to use tenant’s keypair but any keypair already imported can be used. We create a String Parameter for our Pid and assign id: “ReceiverPrivateKey” and the value: “sap_cloudIntegrationcertificate”
URL: {{UI_tenant_url}}/api/v1/StringParameters
Method: Post
Body in Json:{ "Pid": "MATARTEST_ZZ", "Id": "ReceiverPrivateKey", "Value": "sap_cloudintegrationcertificate" }
- Verify Signature. This parameter is to set request the adapter to verify the signature. We create a String Parameter for our Pid and assign id: “AS2_inbound_verify_signature” and assign the value: “trustedCertificate”
URL: {{UI_tenant_url}}/api/v1/StringParameters
Method: Post
Body in Json:{ "Pid": "MATARTEST_ZZ", "Id": "AS2_inbound_verify_signature", "Value": "trustedCertificate" }
- Public Key. This parameter contains the public certificate in PEM format, without header and footer, no spaces, or newlines. We create a Binary Parameter for our Pid and assign content-type: “crt” and value: “{{certificate_PEM}}”
URL: {{UI_tenant_url}}/api/v1/BinaryParameters
Method: Post
Body in Json:{ "Pid": "MATARTEST_ZZ", "Id": "SenderPublicKey", "ContentType": "crt", "Value": "MIIDkDCCAnigAwIBAgIOAO...VNxcW4SwvUHIbSg==" }
- Decrypt Message. This parameter is needed if partners are encrypting the message. We create a String Parameter for our Pid and assign Id: “AS2_inbound_decrypt_message” and the value: “true”
We have completed the configuration for Partner_A, please repeat all tasks for Partner_B. When finalized if all API calls have been executed successfully you will be able to have the following parameters configured in your tenant.
Note: I have used Pid: “MATARTEST_ZZ” Partner_A and Pid: “MATARSYST_ZZ” Partner_B
String Parameters:
AuthorizedUsers:
Binary Parameter:
Testing
To be able to test we need an AS2 tool to send documents to our iFlow, a good option is Mendelson also referenced by the official documentation unfortunately at the moment of writing this article Mendelson support has confirmed that Client Certificate Authentication is not working in the community version (forum) so instead we will use SAP BTP Trial – Cloud Integration.
Note: Please find a blog on how to enable a trial account <<blog>>
Step 1: Certificate Management
Cloud Integration Trial tenant will be acting as B2B Sender System for Partner_A and Partner_B so we need to maintain the proper security artifacts.
- Import Keypair in Cloud Integration Keystore.
Navigate Monitor >> Manage Security >> Keystore >> Click on Add >> Key Pair
Partner_A >> alias >> partner_a_813
Partner_B >> alias >> partner_b_184
Cloud Integration r-co tenant will be acting as B2B Receiver System so we need to maintain the public key from the sap_cloudintegrationcertificate Key Pair.
- Navigate Monitor >> Manage Security >> Keystore >> Click on Add >> Certificate
assign alias >> cpi_w
If imported successfully must have the following entries on the trial’s tenant keystore
Keypair:
Certificate:
Step 2: Create iFlow
- Create an iFlow with two Integration processes, two HTTPS Sender Adapter, two AS2 Receiver Adapter.
- Configure HTTPS Sender Adapter
2.1 Create first endpoint as: /partner_a2.2 Create second endpoint as: /partner_b
For simplicity will disable CSRF protected, and leave all default values.
Step 3: Configure Outbound AS2 (Receiver) Adapter
Note: Please refer to the Certificate section above for clarification on certificate usage.
Note: For purpose of this exercise we will use an S-User keypair to simulate each partner from where I have extracted the certificate; more details can be found in the following link.
- Configure AS2 Receiver Adapter – Partner_A
- Connection – Client Certificate Authentication – Select Authentication Type as Client Certificate and type in the alias created >> partner_a_813
- Processing – Own AS2 ID: “Partner_A“, Partner AS2 ID: R-Co, Message Subject: “msgB2BPartners“, and Content-Type Application/EDI-X12
- Security – As defined Sign Message: Checked, Algorithm: SHA1, Private Key Alias: partner_a_813, Encrypt Message: Checked, Algorithm: 3DES, and Public Key Alias: cpi_w (sap_cloudintegrationcertificate)
- MDN – Type: Sync, Request Signing: Checked, Algorithm: SHA1, Verify Signature: Checked, and Public Key Alias: cpi_w (sap_cloudintegrationcertificate)
- Configure AS2 Receiver Adapter – Partner_B
- Connection – Client Certificate Authentication – Select Authentication Type as Client Certificate and type in the alias created >> partner_b_184
- Processing – Own AS2 ID: “Partner_B“, Partner AS2 ID: R-Co, Message Subject: “msgB2BPartners“, and Content-Type Application/EDI-X12
- Security – As defined Sign Message: Checked, Algorithm: SHA512, Private Key Alias: partner_b_184, Encrypt Message: Checked, Algorithm: AES256, and Public Key Alias: cpi_w (sap_cloudintegrationcertificate)
- MDN – Type: Sync, Request Signing: Checked, Algorithm: SHA512, Verify Signature: Checked, and Public Key Alias: cpi_w (sap_cloudintegrationcertificate)
- Save and Deploy
After successfully deploying we should have two endpoints, which will simulate sending data as Partner_A and Partner_B in compliance with the initial requirement and technical details.
Step 4: Complete E2E testing
We can test our scenario using a local client, I will use Postman to call the HTTPS endpoint and send a dummy EDI file. Note: Please find a video tutorial on how to create credentials and execute iFlow <<video>>
- Partner_A Test – X12 850
Note: If successful reply will contain MDN details - Partner_B Test – X12 855
Results
After execution, we can check the logs on both tenants.
Monitoring – Outbound (Trial tenant)
Navigate Monitor >> Message Processing >> All Integrations Flows
Select Message for iFlow: IF_AS2_T
A successful message with a Synchronous MDN should have a status of processing completed successfully and MDN Attachment.
Outbound Message: Partner_A
MDN Attachment – Partner_A
Outbound Message – Partner_B
MDN Attachment – Partner_B
Same values as per Postman responses.
Monitoring – Inbound
Navigate Monitor >> Message Processing >> All Integrations Flows
Select Message for iFlow: IF_AS2_Inbound_to_JMS
Inbound Message – Partner_A
The Partner ID was retrieved automatically using Partner Directory Binary Parameter and AuthorizedUser entity.
Trace – Partner_A
Will deep dive into the header values to validate the user, certificate, and AS2 envelop values.
Header Values – Partner_A
Note: We can compare x-forwarded-client-cert and SAPAuthenticatedUserName values against the service key in SAP BTP Cockpit.
At last, we analyze if the data was decrypted.
Payload – Partner_A
Analyze decrypted payload
Inbound Message – Partner_B
The Partner ID was retrieved automatically using Partner Directory Binary Parameter and AuthorizedUser entity.
Trace – Partner_B
Will deep dive into the header values to validate the user, certificate, and AS2 envelop values.
Header Values – Partner_B
Note: We can compare x-forwarded-client-cert and SAPAuthenticatedUserName values against the service key in SAP BTP Cockpit.
At last, we analyze if the data was decrypted.
Payload – Partner_B
Analyze decrypted payload
Monitor Queue
Messages are available for further processing we can corroborate the Message-ID corresponds to the ones shown in the Message Monitor screen.
Conclusion
We have demonstrated that SAP Cloud Integration with the Partner Directory can dynamically select the correct certificates, and configuration to process the incoming data from different business partners. Thanks
My goal was to provide you with a guide on how to configure AS2 Adapters in SAP BTP Cloud Integration while leveraging Partner Directory built-in capabilities using client certificate authentication, hopefully, this can help you in your projects, keep integrating
Regards
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK