AS2 app Documentation

Setting up the AS2 Web App

Contents

Setting up the Azure App Registration

An Azure App Registration needs to be created to be used for handling authentication of the web app, as well as to handle permissions of the web app, 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, you will see information such as the Client Id and Tenant Id. We will come back to these later.
  5. Go to Expose an API and click on Add a scope. Confirm the application id URL and add a scope.
  6. Notice the Application ID URI at the top. This will be needed later.

Setting up KeyVault

KeyVault is required for the following secrets/certificates to be stored and used by the app.

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

Generate certificates and secrets

  1. Create a keyvault resource.
  2. Go to Certificates and generate a certificate with default options and filling in the name and the subject (e.g. CN=<DomainName>). This will also create a secret with the same name of the certificate. That secret will represent the private key.

The generated secret is hidden from the keyvault secret list but still accessible. 3. Go to Secrets and generate the a secret called receiverpublickey. In here, 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 in this page. See more about setting up Azure Storage.

Allow access from the app.

The following steps will allow the app to access the keyvault secrets.

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

Setting up App Configuration

The following steps will create an app configuration resource with configuration values to be used by 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 will contain 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, let's assume that the application id is AS2WEBAPP. Generate the following configuration, either manually or by updating the json file found 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. This should be set 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. This should be set up as a key vault reference from the Azure portal, not from the json file.
AS2WEBAPP:As2Setup:SignAlgorithm Valid signing algorithm (e.g. 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 own certificate was created outside of Azure using a password.
AS2WEBAPP:As2Setup:CertificateExpiryWarningDays - No 30 If the expiry of the owned certificate or the partner certificate expires within the number of days set here, a warning is shown on the config page (landing page).
AS2WEBAPP:RequestHeaders:AS2Version (e.g. 1.2) Yes - The version sent as request header to the AS2 Partner
AS2WEBAPP:RequestHeaders:ContentTransferEncoding (e.g. 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 AS2Partner to which data is sent.
AS2WEBAPP:Storage:Account - Yes - The storage account name.
AS2WEBAPP:Storage:Directory - Yes - The storage account directory.
AS2WEBAPP:Storage:FileExtension (e.g. xml) Yes - The extension of the stored files in Azure Storage.
AS2WEBAPP:Storage:Key Key Vault Reference Yes - The access key to Azure storage. This should be set 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": ""
}

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. Tick Allow Anonymous Access. This is needed for receiving 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. Click on 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.

The actual web app can be deployed 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. These can be overridden using the configration 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

The send method of the web app can be called to start the process of sending data to the AS2 partner. The content can be sent 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 Is 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, but any headers that need to be sent forward to the AS2 partner need to be prefixed by AS2-. As an example, header AS2-Message-ID will be forwarded as a header to the AS2 partner as Message-ID.