AS2 app documentation

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.

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=). This also creates a secret with the same name as the certificate. That secret represents the private key.

   Note

   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.

   Note

   Setting up Azure storage is not covered on this page. See: Azure Storage Account setup.

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.

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.

{
    "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. 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.

8. Go to the app registration created earlier and to the Authentication menu.

9. Select Add a platform and select Web.

10. Add a redirect URL with value https:///signin-oidc.

11. 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": "",
    "ClientId": "",
    "CallbackPath": "/signin-oidc",
    "Scopes": "/.default",
    "AllowWebApiToBeAuthorizedByACL": true
  },
  "ConnectionStrings": {
    "AppConfig": ""
  },
  "ApplicationSetup": {
    "ApplicationId": "" 
  },

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

Headers

Headers are optional. Anywhere Mobility Solutions 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.