Fiks Arkiv

Maskinporten clients are created in the self-service portal:

• For the production environment, clients are created from: https://sjolvbetjening.samarbeid.digdir.no.
• For the test environment, clients are created from: https://sjolvbetjening.test.samarbeid.digdir.no.

1. Start by logging into your account with your chosen method.
2. When logged into your account, the organisation you represent is shown in the top menu to the right.

   

   If you logged in to represent a synthetic organisation, you will also be able to change the synthetic organisation you represent in the drop down menu on that item.

   

3. Select the Create client button to start creating a new client for the organisation you represent.
4. On the Add client page select Maskinporten.
5. On the Add Maskinporten client page fill in the display name, description and add your required scopes (these values can also be changed later). Then click the Create button.

   

6. You have now created a Maskinporten client for your organisation. To use this client you need to add at least one authentication key. The client supports JWK and PEM keys. Start by either locating an existing key or creating a new one. You can use the Altinn JWKS tool or other key generator of your choice for this. Next, navigate to the key section on your client page and select Add.

   

   In the JWK or PEM format field paste your public key and click Save. The key is now added to the client. Store your private key from your JWK or PEM in a secure location, as it is used to authorize the use of this client. If you use Azure Key Vault to store your private keys, they need to be base64-encoded before uploading.

   

7. If you didn’t do so in step 5, you need to add the desired scopes to your client before it can be used.

   

   

Prerequisites

• OpenSSL installed on your machine.
  A quick Google search will point you to installation instructions for your operating system.

1. Generate SSL Certificate and Private Key

   Open a console where openssl is available, navigate to a suitable directory, and run:

   openssl req -x509 -newkey rsa:2048 -nodes -keyout private.pem -out public.pem -days 720
   

   Explanation of Flags

   • req -x509: Generate a X.509 certificate.
   • -newkey rsa:2048: Create a new RSA key with 2048-bit encryption.
   • -nodes: Do not encrypt the private key.
   • -keyout private.pem: Output private key to private.pem.
   • -out public.pem: Output certificate to public.pem.
   • -days 720: Valid for 720 days.

   Answer any prompts with values representing your organization, or leave them blank if you prefer.

   Result: Two files will be created in the directory:

   • public.pem (certificate)
   • private.pem (private key)

2. Base64 Encode the Private Key

   Windows

   Use certutil to encode the private key:

   certutil -encode -f "private.pem" "privatebase64.txt"
   

   This generates a file privatebase64.txt containing the private key as a Base64-encoded string.

   Linux / macOS Use the base64 command:

   base64 private.pem > privatebase64.txt
   

   This creates privatebase64.txt with the Base64-encoded private key.

Notes

• Keep your private key secure. Do not share private.pem or its Base64 representation publicly.
• The generated certificate (public.pem) can be distributed as needed.

Troubleshooting

• OpenSSL not found: Ensure it’s installed and added to your system PATH.
• Permission issues: Run the commands with appropriate privileges or in a directory where you have write access.
• Invalid Base64 output: Verify the original file exists and is readable before encoding.

The client id for the Maskinporten client generated in step 1 and the base64-encoded public and private key should be added as ClientId and JwkBase64 in the MaskinportenSettings section.

Configuration Example

• Section name: MaskinportenSettings
• Service registration:

services
    .AddFiksArkiv()
    .WithMaskinportenConfig("MaskinportenSettings");

Application settings

"MaskinportenSettings": {
    "Authority": "https://[test.]maskinporten.no/",
    "ClientId": "retrieved from secrets",
    "JwkBase64": "retrieved from secrets"
}

Key Vault Secrets

• MaskinportenSettings--ClientId
• MaskinportenSettings--JwkBase64

For the application to be able to read the secrets from Azure Key Vault, it needs to be configured to do so. See the secrets section to achieve this.

Note: The secrets are read by the application on launch so if you make changes after the application is deployed, you will need to redeploy the application for them to come into effect.

Configuration Example

It is recommended to store all sensitive FiksIO setting values securely in Azure Key Vault or the secret management provider used by your application.

• Section name: FiksIOSettings
• Service registration:

services
    .AddFiksArkiv()
    .WithFiksIOConfig("FiksIOSettings");

Application settings

"FiksIOSettings": {
    "AccountId": "c3c87fac-06be-44ed-a11c-aa137d12863c",
    "IntegrationId": "08b3d8b9-5026-46dc-936c-8e6709efa72c",
    "IntegrationPassword": "retrieved from secrets",
    "AccountPrivateKeyBase64": "retrieved from secrets"
}

Key Vault Secrets

• FiksIOSettings--IntegrationPassword
• FiksIOSettings--AccountPrivateKeyBase64

Service registration

• Section name: FiksArkivSettings
• Service registration:

services
    .AddFiksArkiv()
    .WithFiksArkivConfig("FiksArkivSettings");

High-Level Structure

FiksArkivSettings
├─ Receipt
│  ├─ ConfirmationRecord
│  └─ ArchiveRecord
├─ Recipient
│  ├─ FiksAccount
│  ├─ Identifier
│  ├─ Name
│  └─ OrganizationNumber
├─ Metadata
│  ├─ SystemId
│  ├─ RuleId
│  ├─ CaseFileId
│  ├─ CaseFileTitle
│  └─ JournalEntryTitle
├─ Documents
│  ├─ PrimaryDocument
│  └─ Attachments{}
├─ ErrorHandling
│  ├─ MoveToNextTask
│  └─ Action
└─ SuccessHandling
   ├─ MoveToNextTask
   ├─ Action
   └─ MarkInstanceComplete

Further, we break down each sub-section of FiksArkivSettings, shows how to bind values (static vs. dynamic), and provides a complete appsettings.json example.

Sections & Settings

• Receipt (FiksArkivSettings.Receipt)

  Settings related to the records created after a successful shipment.

  Note: The data types defined here must have corresponding entries in the datatype definition in applicationmetadata.

  Setting Name	Purpose	Format
  ConfirmationRecord	Defines the data type and name for the arkivkvittering.	{ "DataType": "string", "Filename": "string" }
  ArchiveRecord	Defines the data type and name for the arkivmelding.	{ "DataType": "string", "Filename": "string" }

  Example configuration:

"FiksArkivSettings": {
  "Receipt": {
    "ConfirmationRecord": {
      "DataType": "fiks-receipt",
      "Filename": "Arkivkvittering.xml"
    },
    "ArchiveRecord": {
      "DataType": "fiks-archive-record", 
      "Filename": "Arkivmelding.xml"
    }
  }
}

{
  "dataTypes":[
    {
      "id": "fiks-receipt",
      "allowedContributers": [ "app:owned" ],
      "maxCount": 1,
      "minCount": 0,
      "enablePdfCreation": false,
      "enableFileScan": false,
      "validationErrorOnPendingFileScan": false
    },
    {
      "id": "fiks-archive-record",
      "allowedContributers": [ "app:owned" ],
      "maxCount": 1,
      "minCount": 0,
      "enablePdfCreation": false,
      "enableFileScan": false,
      "validationErrorOnPendingFileScan": false
    }
  ]
}

• Recipient (FiksArkivSettings.Recipient)

  Settings related to who will receive the Fiks Arkiv message.

  Setting Name	Purpose	Type
  FiksAccount	The recipient account GUID to ship messages to.	GUID (required)
  Identifier	Recipient identifier (e.g., municipality number).	string (required)
  Name	Recipient name.	string (required)
  OrganizationNumber	Optional recipient organization number.	string (optional)

  Recipient settings support both static and dynamic configuration formats - see How Values Are Provided for syntax and use DataModelBinding when fields differ per instance.

  Example configuration:

  "FiksArkivSettings": {
    "Recipient": {
      "FiksAccount": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.AccountId"
        }
      },
      "Identifier": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.Identifier"
        }
      },
      "OrganizationNumber": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.OrgNumber"
        }
      },
      "Name": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.Name"
      }
    }
  }
}

• Metadata (FiksArkivSettings.Metadata)

  Contextual information used by the archive system.

  Setting Name	Purpose	Default Behavior
  SystemId	System ID used in the generated arkivmelding.xml.	Defaults to Altinn Studio if not provided.
  RuleId	Optional rule ID for processing the incoming message in systems that support rule IDs.	Omitted if not provided.
  CaseFileId	ID for the generated case file (saksmappe element).	Defaults to the instance identifier if not provided.
  CaseFileTitle	Title for the generated saksmappe tittel element.	Defaults to the application title if not provided.
  JournalEntryTitle	Title for the generated journalpost tittel element.	Defaults to the application title if not provided.

  Metadata support both static and dynamic configuration formats - see How Values Are Provided for syntax and use DataModelBinding when fields differ per instance.

  Example configuration:

"FiksArkivSettings": {
  "Metadata": {
   "JournalEntryTitle": {
      "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "JournalEntryTitle"
      }
    },
    "CaseFileTitle": {
      "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "CaseFileTitle"
      }
    }
  }
}

• Documents (FiksArkivSettings.Documents)

Definition of the documents to include in the archive message (arkivmelding) that is sent to Fiks Arkiv.

Each document entry typically uses DataType to indicate the source and/or format. For example, "ref-data-as-pdf" for a PDF generated from reference data.

Example configuration:

"FiksArkivSettings": {
  "Documents": {
    "PrimaryDocument": {
      "DataType": "ref-data-as-pdf"
    },
    "Attachments": [
      {
        "DataType": "DataModel"
      },
      {
        "DataType": "vedlegg-datatype"
      }
    ]
  }
}

• ErrorHandling (FiksArkivErrorHandlingSettings)

What the application should do when a send attempt fails.

Example configuration:

"FiksArkivSettings": {
  "ErrorHandling": {
    "MoveToNextTask": true
  }
}

• SuccessHandling (FiksArkivSuccessHandlingSettings)

What the application should do when a send attempt succeeds.

Example configuration:

"FiksArkivSettings": {
  "SuccessHandling": {
      "MoveToNextTask": true,
      "MarkInstanceComplete": true
  }
}

Practical Tips

• Start simple: Configure Recipient and Metadata first; add Documents and Receipt details as needed.
• Use binding for variability: Prefer DataModelBinding for fields that vary per instance or environment.
• Keep defaults in mind: If you omit certain metadata fields, sensible defaults (like application title) are used.
• Actions & flow: Set ErrorHandling and SuccessHandling to align with your process (e.g., move to next task, mark instance complete).

How Values Are Provided

Each setting can be supplied in one of two ways:

1. Static (hard-coded) value

   "JournalEntryTitle": {
     "Value": "Hallo"
   }
   

2. Dynamic value via data model binding

   "CaseFileTitle": {
     "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "CaseFileTitle"
     }
   }
   

Use Value when you know the text upfront; use DataModelBinding when values should come from your runtime data (e.g., fields collected in a form or helper model).

Troubleshooting

• Missing titles: If journal or case file titles are empty, check that your DataModelBinding points to existing fields, or provide a Value.
• Incorrect recipient: Verify that FiksAccount contains a valid GUID and matches the intended recipient.
• Attachment resolution: Ensure each attachment DataType is defined in applicationmetadata.