AS2 app Documentation

Setting up the AS2 Web App

Contents

Steps - Setting up the Azure App Registration

Create an Azure App Registration to handle authentication of the web app and permissions in relation to other Azure resources such as KeyVault.

  1. Go to the Azure portal and search for App Registrations.
  2. Create a new app registration. Select a name and set the desired account type.
  3. Leave the redirect URL empty for now and create the app registration.
  4. On the overview page, note information such as the Client Id and Tenant Id. These are needed later.
  5. Go to Expose an API and select Add a scope. Confirm the application ID URL and add a scope.
  6. Note the Application ID URI at the top. This is needed later.

Setting up KeyVault

KeyVault stores the following secrets and certificates for use by the app:

  • The public key received from the AS2 partner, needed to encrypt and verify data.
  • The certificate owned by the app, which contains the private key needed to sign and decrypt the data.
  • The Azure storage access key for storing the data.

Steps - Generate certificates and secrets

  1. Create a KeyVault resource.

  2. Go to Certificates and generate a certificate with default options, filling in the name and the subject (for example, CN=<DomainName>). This also creates a secret with the same name as the certificate. That secret represents the private key.

    The generated secret is hidden from the KeyVault secret list but remains accessible.

  3. Go to Secrets and generate a secret called receiverpublickey. Paste the public key from the certificate sent by the AS2 partner.

  4. Create another secret for the storage account access key called storagekey. Enter the storage account access key here.

    Setting up Azure storage is not covered on this page. See more about setting up Azure Storage.

Steps - Allow access from the app

The following steps allow the app to access the KeyVault secrets.

  1. Go to Access Policies in the KeyVault menu. Select Add Access Policy.
  2. Select the Get and List permissions under Secret Permissions.
  3. In Principal, find the app registration created earlier.
  4. Select Add.

Steps - Setting up App Configuration

The following steps create an app configuration resource with configuration values for the web app.

  1. In the Azure Portal, search for App Configurations. Create an app configuration.
  2. Go to Configuration Explorer in the App Configuration menu. This contains all configuration values.

Each configuration value is prefixed by the application ID — a logical name determined in the appsettings of the web app itself. In this case, assume that the application ID is AS2WEBAPP. Generate the following configuration, either manually or by updating the JSON file in the resources folder with values and uploading it using the import functionality in the portal App Configuration menu.

Key Allowed Values Required Default Value Description
AS2WEBAPP:As2Setup:CompressData True/False No False Whether data should be compressed before sending to the AS2 Partner.
AS2WEBAPP:As2Setup:EncryptData True/False No False Whether data should be encrypted before sending to the AS2 Partner.
AS2WEBAPP:As2Setup:FromPartner — Yes — Forwarded as a request header to the AS2 Partner.
AS2WEBAPP:As2Setup:OwnedPrivateKey Key Vault Reference Yes — The private key generated. Set this up as a Key Vault reference from the Azure portal, not from the JSON file.
AS2WEBAPP:As2Setup:PartnerPublicKey Key Vault Reference Yes — The partner's public key. Set this up as a Key Vault reference from the Azure portal, not from the JSON file.
AS2WEBAPP:As2Setup:SignAlgorithm Valid signing algorithm (for example, SHA1) No SHA1
AS2WEBAPP:As2Setup:SignData True/False No False Whether data should be signed before sending to the AS2 Partner.
AS2WEBAPP:As2Setup:ToPartner — Yes — Forwarded as a request header to the AS2 Partner.
AS2WEBAPP:As2Setup:CertificatePassword — No — Used if the owned certificate was created outside of Azure using a password.
AS2WEBAPP:As2Setup:CertificateExpiryWarningDays — No 30 If the owned certificate or the partner certificate expires within the number of days set here, a warning appears on the config page (landing page).
AS2WEBAPP:RequestHeaders:AS2Version (for example, 1.2) Yes — The version sent as a request header to the AS2 Partner.
AS2WEBAPP:RequestHeaders:ContentTransferEncoding (for example, Binary) No Binary Sent as a request header to the AS2 Partner.
AS2WEBAPP:RequestHeaders:DispositionNotificationOptions — Yes — Sent as a request header to the AS2 Partner.
AS2WEBAPP:RequestHeaders:DispositionNotificationTo — Yes — Sent as a request header to the AS2 Partner.
AS2WEBAPP:RequestHeaders:Endpoint — Yes — The URL of the AS2 Partner to which data is sent.
AS2WEBAPP:Storage:Account — Yes — The storage account name.
AS2WEBAPP:Storage:Directory — Yes — The storage account directory.
AS2WEBAPP:Storage:FileExtension (for example, xml) Yes — The extension of the stored files in Azure Storage.
AS2WEBAPP:Storage:Key Key Vault Reference Yes — The access key to Azure Storage. Set this up as a Key Vault reference from the Azure portal, not from the JSON file.
AS2WEBAPP:Storage:Share — Yes — The share of the Azure Storage account. 
{
    "AS2WEBAPP:As2Setup:CompressData": "False",
    "AS2WEBAPP:As2Setup:EncryptData": "True",
    "AS2WEBAPP:As2Setup:FromPartner": "",
    "AS2WEBAPP:As2Setup:OwnedPrivateKey": "",
    "AS2WEBAPP:As2Setup:PartnerPublicKey": "",
    "AS2WEBAPP:As2Setup:SignAlgorithm": "SHA1",
    "AS2WEBAPP:As2Setup:SignData": "True",
    "AS2WEBAPP:As2Setup:ToPartner": "",
    "AS2WEBAPP:RequestHeaders:AS2Version": "1.2",
    "AS2WEBAPP:RequestHeaders:ContentTransferEncoding": "Binary",
    "AS2WEBAPP:RequestHeaders:DispositionNotificationOptions": "signed-receipt-protocol=optional,pkcs7-signature;signed-receipt-micalg=optional,sha1",
    "AS2WEBAPP:RequestHeaders:DispositionNotificationTo": "",
    "AS2WEBAPP:RequestHeaders:Endpoint": "",
    "AS2WEBAPP:Storage:Account": "",
    "AS2WEBAPP:Storage:Directory": "",
    "AS2WEBAPP:Storage:FileExtension": "xml",
    "AS2WEBAPP:Storage:Key": "",
    "AS2WEBAPP:Storage:Share": ""
}

Steps - Setting up the Azure Web App

  1. Search for App Services in the Azure Portal.
  2. Create an app service targeting .net6 and Windows.
  3. After creating the resource, go to Authentication in the app service menu.
  4. Add an identity provider by selecting the app registration created earlier.
  5. Select Allow Anonymous Access. This is needed to receive data from the partner.
  6. Go to Configuration in the app service menu.
  7. Add the following settings:
Key Value
AZURE_CLIENT_ID The client ID of the app registration created earlier.
AZURE_TENANT_ID The tenant ID of the app registration created earlier.
AZURE_CLIENT_SECRET A secret key generated in the app registration Certificates & Secrets menu.
  1. Go to the app registration created earlier and to the Authentication menu.
  2. Select Add a platform and select Web.
  3. Add a redirect URL with value https://<webappdomain>/signin-oidc.
  4. Make sure ID Tokens is checked.

Deploying the web app

Deploy the web app directly from Visual Studio using web deploy, or via zip deploy using the KUDU portal from the app service in the Azure portal (Advanced > Go).

Before deploying, make sure the following settings exist in appsettings.json. You can override these using the Configuration section in the app service in the Azure portal.

"AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "",
    "TenantId": "<App Registration Tenant Id>",
    "ClientId": "<App Registration Client Id>",
    "CallbackPath": "/signin-oidc",
    "Scopes": "<API application ID URI from the expose an API page of the app registration>/.default",
    "AllowWebApiToBeAuthorizedByACL": true
  },
  "ConnectionStrings": {
    "AppConfig": "<The app configuration connection string found in the Access Keys page in the app configuration resource.>"
  },
  "ApplicationSetup": {
    "ApplicationId": "<The Logical Application ID that determines the config>" 
  },

Calling the Send Method

Call the send method of the web app to start sending data to the AS2 partner. Send the content as plain text or as a Base64 string.

Endpoint: /api/as2/senddata

Method: POST

ContentType: JSON

Example:

{
    "encoding": "Binary",
    "documentContent":"PHJvb3Q+dGVzdCAyPC9yb290Pg==",
    "filename": "test.xml",
    "documentContentFormat": "Base64String"
}

Content fields

Field Required Comments Default Value
encoding Yes Parsed into Mimekit enum ContentEncoding Binary
documentContent Yes The actual content —
filename Yes Passed forward to the AS2 Partner —
documentContentFormat No PlainText or Base64String. If the value is not plain text, the document content is first decoded, then processed. PlainText

Headers

Headers are optional. Any headers to send forward to the AS2 partner must be prefixed by AS2-. For example, header AS2-Message-ID is forwarded to the AS2 partner as Message-ID.