1. To-Increase Dynamics 365 for Finance & Operations
  2. EDI studio
  3. General
  4. Set up EDI
  5. Set up AS2

Set up AS2 web app

You can use EDI studio to exchange EDI messages using the AS2 protocol. To do so, you must set up the AS2 web app.

The AS2 web app setup consists of these elements:

  • App registration in the Microsoft identity platform.
  • Azure Storage account with file share.
  • Key vault to set up the secrets and certificates that are required to run the AS2 web app.
  • App configuration resource to be used by the AS2 web app.
  • App service to run the AS2 web app.

 


Administrator Administrator Start Start Register application with Azure Active Directory Register application with Azure Active Directory Register an application in Azure to manage the authentication and permissions for the AS2 web app. For more information, refer to Register an application with the Microsoft identity platform. Add a client secret to the registered application. For more information, refer to Add a client secret. Later in the AS2 setup, you need these values of the registered app: Application (client) ID Directory (tenant) ID Application ID URI Client secret value Set up Azure Storage account with file share Set up Azure Storage account with file share If you run the AS2 web app in the AS2 inbound process, it stores the data in EDI message files in the general storage location. Usually, the general storage location is defined by an Azure Storage account. You can create an Azure Storage account or, if you already have an Azure Storage account, use that one. For more information, refer to Create an Azure storage account. In the storage account, create the file share where the EDI message files must be stored by the AS2 web app. For more information, refer to Create a file share. Set up AS2 Key Vault

Set up AS2 Key Vault

When you use the AS2 web app, you need a key vault to set up the secrets and certificates that are required to run the AS2 web app.

 Set up app configuration Set up app configuration Set up an app configuration. Create the App Configuration and in the App Configuration set the required key values. Copy the connection string of the App Configuration from the Access keys page and save it somewhere. Usually, you use the connection string of the primary key. You need the connection string to connect the App Service to the App Configuration, in the configuration of the App Service. For more information, refer to About Azure App Configuration. Key values To add the key values to the App Configuration, download the Default AS2 App Configuration and extract it. The default AS2 web app name prefix for the keys is 'AS2WEBAPP'. If you want to use another prefix, you can change it. To do so, before you import the key values, edit the 'DefaultAS2AppConfiguration.json' file in a text editor. Note: You define the AS2 web app name in the App Service settings (ApplicationSetup:ApplicationId). For consistency purposes, you are advised to use the same name for the App Service and the AS2 web app name. When you edit the 'DefaultAS2AppConfiguration.json' file, you can also set the key values. However, do not set the values for these keys in the file: AS2WEBAPP:As2Setup:OwnedPrivateKey AS2WEBAPP:As2Setup:PartnerPublicKey AS2WEBAPP:Storage:Key When you have finished editing the JSON file, import the 'DefaultAS2AppConfiguration.json' file to your App Configuration. For more information, refer to Import data from a configuration file. In the App Configuration, you can edit the values of the imported keys with the Configuration explorer. To do so: For most of the keys, you can use the Edit option. For these keys, use the Add Key Vault reference option: AS2WEBAPP:As2Setup:OwnedPrivateKey AS2WEBAPP:As2Setup:PartnerPublicKey AS2WEBAPP:Storage:Key The key configuration that is required for the AS2 web app is: Key Allowed values Required Default value Description AS2WEBAPP:As2Setup:CompressData True/False No False Indicate if data must be compressed before it is sent to the web server of the EDI partner. AS2WEBAPP:As2Setup:EncryptData True/False No False Indicate if data must be encrypted before is sent to the web server of the EDI partner. AS2WEBAPP:As2Setup:FromPartner - Yes - Enter a name that represents your EDI partner. For example, the EDI partner company name. This name is added to (outbound) or read from (inbound) the request header.  AS2WEBAPP:As2Setup:OwnedPrivateKey Key vault reference Yes - Add the private key of the certificate that you generated for the Key Vault. Note: Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file. AS2WEBAPP:As2Setup:PartnerPublicKey Key vault reference Yes - Add the Key Vault secret that holds the public key that you received from your EDI partner. Note: Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file. AS2WEBAPP:As2Setup:SignAlgorithm Valid signing algorithm. For example: SHA1 No SHA1 Enter a valid algorithm that the AS2 web app uses to sign (outbound) or verify (inbound) EDI messages. Usually, the SHA1 algorithm is used. AS2WEBAPP:As2Setup:SignData True/False No False Indicate if data must be signed before it is sent to the EDI partner. AS2WEBAPP:As2Setup:ToPartner - Yes - Enter a name that represents your company. For example, the company name. This name is added to (outbound) or read from (inbound) the request header.  AS2WEBAPP:As2Setup:CertificatePassword - No - Only enter the certificate password if you have created your certificate outside the Azure portal and imported the certificate to the Key Vault. To access such a certificate, a password is required. AS2WEBAPP:As2Setup:CertificateExpiryWarningDays - No 30 The certificate and secrets in the Key Vault can have an expiration date set. You can define how many days before the expiration date a warning is shown on the configuration page of the AS2 web app. AS2WEBAPP:RequestHeaders:AS2Version For example: 1.0.0.15 Yes 1.0.0.15 For informational purposes only, you can enter the version number of the AS2 web app. The version number is added to the request header that is sent to the EDI partner. AS2WEBAPP:RequestHeaders:ContentTransferEncoding Binary or no value No Binary If set, the body of the message is encoded, for example, as as binary. If not set, the body is not encoded and sent as plain text. The encoding setting is added to the request header that is sent to the EDI partner. AS2WEBAPP:RequestHeaders:DispositionNotificationOptions - Yes signed-receipt-protocol=optional,pkcs7-signature;signed-receipt-micalg=optional,sha1 Define the MDN reply options. The MDN reply options are added to the request header that is sent to the EDI partner. AS2WEBAPP:RequestHeaders:DispositionNotificationTo - Yes - Define where the MDN reply must be sent to. The MDN reply recipient is added to the request header that is sent to the EDI partner. AS2WEBAPP:RequestHeaders:Endpoint - Yes - Enter the URL of the web server of the EDI partner to which data is sent. Note: This endpoint is provided by your EDI partner. AS2WEBAPP:Storage:Account - Yes - Enter the name of the Azure Storage account where the AS2 web app must store the EDI message files. Note: This only applies to the AS2 inbound process. AS2WEBAPP:Storage:Directory - Yes - Enter the Azure Storage account directory where the AS2 web app must store the EDI message files. Note: This only applies to the AS2 inbound process. AS2WEBAPP:Storage:FileExtension For example: xml Yes xml Enter the extension of the files that are created by the AS2 web app and stored in the defined Azure storage account. Note: This only applies to the AS2 inbound process. AS2WEBAPP:Storage:Key Key vault reference Yes - Add the Key Vault secret that holds the access key of the Azure Storage account where the AS2 web app must store the EDI message files. Note: Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file. This only applies to the AS2 inbound process. AS2WEBAPP:Storage:Share - Yes - The file share of the Azure Storage account in which the created EDI message files are stored by the AS2 web app. In the AS2 documentation, this file share is referred to as the 'general storage location'. Note: This only applies to the AS2 inbound process. Set up app service Set up app service Create and configure an App service in the Azure portal. The app service is the AS2 web app. On creation of the app service, in the: Runtime stack field, select '.NET 6 (LTS)'. Operation system field, select 'Windows'. Fill in the other fields as desired. For more information, refer to Create a Web app. To configure the web app, add and edit the required app settings. Do not remove the automatically generated app settings. For more information, refer to Configure app settings. Add and edit these app settings: App setting name Description AzureAd:TenantId Enter the Directory (tenant) ID of the earlier registered app. This is used to link the app service to the earlier registered app to access the key vault via the registered app. AzureAd:ClientId Enter the Application (client) ID of the earlier registered app. This is used to link the app service to the earlier registered app to access the key vault via the registered app. AzureAd:Scopes Enter the the Application ID URI of the earlier registered app. Enter the URI in this way: [Application ID URI].default This is used to link the app service to the earlier registered app to access the key vault via the registered app. ConnectionStrings:AppConfig To link the applicable app configuration to the app service, enter the endpoint of the App Configuration. ApplicationSetup:ApplicationId Enter the application ID prefix as used in the App Configuration key values. For example: AS2WebApp. AZURE_CLIENT_ID Enter the Application (client) ID of the earlier registered app. This is a standard setting to access the registered app. Access to the registered app is needed to: Browse the app service. Connect to the app service from the EDI studio. AZURE_TENANT_ID Enter the Directory (tenant) ID of the earlier registered app. This is a standard setting to access the registered app. Access to the registered app is needed to: Browse the app service. Connect to the app service from the EDI studio. AZURE_CLIENT_SECRET Enter the value of secret that is created for the earlier registered app. This is a standard setting to access the registered app. Access to the registered app is needed to: Browse the app service. Connect to the app service from the EDI studio. Complete app registration Complete app registration To enable browsing the app service, add a redirect URI to the earlier registered app. To add the redirect URI: Select the 'Web' platform. Enter this URI: [app service URL]/signin-oidc. For example: https://example.azurewebsites.net/signin-oidc. You can copy the URL from the App service Overview page. Select the ID tokens check box. For more information, refer to Add a redirect URI. Deploy app Deploy app To get the AS2 web app running in the cloud, deploy the created app service. Ask To-Increase for the AS2WebApp.zip file that contains the AS2 web app files that are required for deployment. Deploy the AS2 web app files with the Zip Push Deploy tool of the Kudu services portal. Procedure 1. Go to and open the earlier created app service. 2. Select Advanced Tools. 3. Click Go. 4. On the Kudu services portal, click Tools, Zip Push Deploy. 5. Drop the provided ZIP file (AS2WebApp.zip) in the grid. 6. Stop the app service. 7. Start the app service. End End

Activities

Name Responsible Description

Register application with Azure Active Directory

Administrator

Register an application in Azure to manage the authentication and permissions for the AS2 web app. For more information, refer to Register an application with the Microsoft identity platform.

Add a client secret to the registered application. For more information, refer to Add a client secret.

Later in the AS2 setup, you need these values of the registered app:

  • Application (client) ID
  • Directory (tenant) ID
  • Application ID URI
  • Client secret value

Set up Azure Storage account with file share

Administrator

If you run the AS2 web app in the AS2 inbound process, it stores the data in EDI message files in the general storage location. Usually, the general storage location is defined by an Azure Storage account.

You can create an Azure Storage account or, if you already have an Azure Storage account, use that one. For more information, refer to Create an Azure storage account.

In the storage account, create the file share where the EDI message files must be stored by the AS2 web app. For more information, refer to Create a file share.

Set up AS2 Key Vault

Administrator

When you use the AS2 web app, you need a key vault to set up the secrets and certificates that are required to run the AS2 web app.

Set up app configuration

Administrator

Set up an app configuration. Create the App Configuration and in the App Configuration set the required key values.

Copy the connection string of the App Configuration from the Access keys page and save it somewhere. Usually, you use the connection string of the primary key. You need the connection string to connect the App Service to the App Configuration, in the configuration of the App Service.

For more information, refer to About Azure App Configuration.

Key values

To add the key values to the App Configuration, download the Default AS2 App Configuration and extract it.

The default AS2 web app name prefix for the keys is 'AS2WEBAPP'. If you want to use another prefix, you can change it. To do so, before you import the key values, edit the 'DefaultAS2AppConfiguration.json' file in a text editor.

Note:

  • You define the AS2 web app name in the App Service settings (ApplicationSetup:ApplicationId). For consistency purposes, you are advised to use the same name for the App Service and the AS2 web app name.
  • When you edit the 'DefaultAS2AppConfiguration.json' file, you can also set the key values. However, do not set the values for these keys in the file:
    • AS2WEBAPP:As2Setup:OwnedPrivateKey
    • AS2WEBAPP:As2Setup:PartnerPublicKey
    • AS2WEBAPP:Storage:Key

When you have finished editing the JSON file, import the 'DefaultAS2AppConfiguration.json' file to your App Configuration. For more information, refer to Import data from a configuration file.

In the App Configuration, you can edit the values of the imported keys with the Configuration explorer. To do so:

  • For most of the keys, you can use the Edit option.
  • For these keys, use the Add Key Vault reference option:
    • AS2WEBAPP:As2Setup:OwnedPrivateKey
    • AS2WEBAPP:As2Setup:PartnerPublicKey
    • AS2WEBAPP:Storage:Key

The key configuration that is required for the AS2 web app is:

Key Allowed values Required Default value Description
AS2WEBAPP:As2Setup:CompressData True/False No False Indicate if data must be compressed before it is sent to the web server of the EDI partner.
AS2WEBAPP:As2Setup:EncryptData True/False No False Indicate if data must be encrypted before is sent to the web server of the EDI partner.
AS2WEBAPP:As2Setup:FromPartner - Yes -

Enter a name that represents your EDI partner. For example, the EDI partner company name.

This name is added to (outbound) or read from (inbound) the request header. 
AS2WEBAPP:As2Setup:OwnedPrivateKey Key vault reference Yes -

Add the private key of the certificate that you generated for the Key Vault.

Note: Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file.
AS2WEBAPP:As2Setup:PartnerPublicKey Key vault reference Yes - Add the Key Vault secret that holds the public key that you received from your EDI partner.

Note: Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file.
AS2WEBAPP:As2Setup:SignAlgorithm Valid signing algorithm. For example: SHA1 No SHA1

Enter a valid algorithm that the AS2 web app uses to sign (outbound) or verify (inbound) EDI messages.

Usually, the SHA1 algorithm is used.
AS2WEBAPP:As2Setup:SignData True/False No False Indicate if data must be signed before it is sent to the EDI partner.
AS2WEBAPP:As2Setup:ToPartner - Yes -

Enter a name that represents your company. For example, the company name.

This name is added to (outbound) or read from (inbound) the request header. 
AS2WEBAPP:As2Setup:CertificatePassword - No - Only enter the certificate password if you have created your certificate outside the Azure portal and imported the certificate to the Key Vault. To access such a certificate, a password is required.
AS2WEBAPP:As2Setup:CertificateExpiryWarningDays - No 30 The certificate and secrets in the Key Vault can have an expiration date set. You can define how many days before the expiration date a warning is shown on the configuration page of the AS2 web app.
AS2WEBAPP:RequestHeaders:AS2Version For example: 1.0.0.15 Yes 1.0.0.15

For informational purposes only, you can enter the version number of the AS2 web app.

The version number is added to the request header that is sent to the EDI partner.
AS2WEBAPP:RequestHeaders:ContentTransferEncoding Binary or no value No Binary

If set, the body of the message is encoded, for example, as as binary. If not set, the body is not encoded and sent as plain text.

The encoding setting is added to the request header that is sent to the EDI partner.
AS2WEBAPP:RequestHeaders:DispositionNotificationOptions - Yes signed-receipt-protocol=optional,pkcs7-signature;signed-receipt-micalg=optional,sha1

Define the MDN reply options.

The MDN reply options are added to the request header that is sent to the EDI partner.
AS2WEBAPP:RequestHeaders:DispositionNotificationTo - Yes -

Define where the MDN reply must be sent to.

The MDN reply recipient is added to the request header that is sent to the EDI partner.
AS2WEBAPP:RequestHeaders:Endpoint - Yes -

Enter the URL of the web server of the EDI partner to which data is sent.

Note: This endpoint is provided by your EDI partner.
AS2WEBAPP:Storage:Account - Yes - Enter the name of the Azure Storage account where the AS2 web app must store the EDI message files.

Note: This only applies to the AS2 inbound process.
AS2WEBAPP:Storage:Directory - Yes - Enter the Azure Storage account directory where the AS2 web app must store the EDI message files.

Note: This only applies to the AS2 inbound process.
AS2WEBAPP:Storage:FileExtension For example: xml Yes xml

Enter the extension of the files that are created by the AS2 web app and stored in the defined Azure storage account.

Note: This only applies to the AS2 inbound process.
AS2WEBAPP:Storage:Key Key vault reference Yes -

Add the Key Vault secret that holds the access key of the Azure Storage account where the AS2 web app must store the EDI message files.

Note:

  • Use the Add Key Vault reference option in the Configuration explorer of the App Configuration. So, do not set this value in the JSON file.
  • This only applies to the AS2 inbound process.
AS2WEBAPP:Storage:Share - Yes - The file share of the Azure Storage account in which the created EDI message files are stored by the AS2 web app. In the AS2 documentation, this file share is referred to as the 'general storage location'.

Note: This only applies to the AS2 inbound process.

Set up app service

Administrator

Create and configure an App service in the Azure portal. The app service is the AS2 web app.

On creation of the app service, in the:

  • Runtime stack field, select '.NET 6 (LTS)'.
  • Operation system field, select 'Windows'.

Fill in the other fields as desired. For more information, refer to Create a Web app.

To configure the web app, add and edit the required app settings. Do not remove the automatically generated app settings. For more information, refer to Configure app settings.

Add and edit these app settings:

App setting name Description
AzureAd:TenantId

Enter the Directory (tenant) ID of the earlier registered app.

This is used to link the app service to the earlier registered app to access the key vault via the registered app.
AzureAd:ClientId

Enter the Application (client) ID of the earlier registered app.

This is used to link the app service to the earlier registered app to access the key vault via the registered app.
AzureAd:Scopes

Enter the the Application ID URI of the earlier registered app.

Enter the URI in this way: [Application ID URI].default

This is used to link the app service to the earlier registered app to access the key vault via the registered app.
ConnectionStrings:AppConfig

To link the applicable app configuration to the app service, enter the endpoint of the App Configuration.
ApplicationSetup:ApplicationId Enter the application ID prefix as used in the App Configuration key values. For example: AS2WebApp.
AZURE_CLIENT_ID

Enter the Application (client) ID of the earlier registered app.

This is a standard setting to access the registered app. Access to the registered app is needed to:

  • Browse the app service.
  • Connect to the app service from the EDI studio.
AZURE_TENANT_ID

Enter the Directory (tenant) ID of the earlier registered app.

This is a standard setting to access the registered app. Access to the registered app is needed to:

  • Browse the app service.
  • Connect to the app service from the EDI studio.
AZURE_CLIENT_SECRET

Enter the value of secret that is created for the earlier registered app.

This is a standard setting to access the registered app. Access to the registered app is needed to:

  • Browse the app service.
  • Connect to the app service from the EDI studio.

Complete app registration

Administrator

To enable browsing the app service, add a redirect URI to the earlier registered app.

To add the redirect URI:

  • Select the 'Web' platform.
  • Enter this URI: [app service URL]/signin-oidc. For example: https://example.azurewebsites.net/signin-oidc. You can copy the URL from the App service Overview page.
  • Select the ID tokens check box.

For more information, refer to Add a redirect URI.

Deploy app

Administrator

To get the AS2 web app running in the cloud, deploy the created app service. Ask To-Increase for the AS2WebApp.zip file that contains the AS2 web app files that are required for deployment.

Deploy the AS2 web app files with the Zip Push Deploy tool of the Kudu services portal.

Set up AS2 Key Vault

Provide feedback