Firely Server Administration API

The Administration database utilizes the Administration API. The endpoint for this API is:

http(s)://<firely-server-endpoint>/administration

The following functions are available in the Administration API:

• Managing Conformance Resources

• Subscriptions

• Re-indexing for new or changed SearchParameters

• Reset the database

• Preloading resources

• Terminology services

Configuration

You can configure the Administration API, including restricting access to functions of the Administration API to specific ip networks.This configuration is part of Firely Server settings.

"Administration": {
  "Repository": "SQLite", //Memory / SQL / MongoDb
  "MongoDbOptions": {
    "ConnectionString": "mongodb://localhost/vonkadmin",
    "EntryCollection": "vonkentries"
  },
  "SqlDbOptions": {
    "ConnectionString": "connectionstring to your Firely Server Admin SQL Server database (SQL2012 or newer); Set MultipleActiveResultSets=True",
    "SchemaName": "vonkadmin",
    "AutoUpdateDatabase": true,
    "MigrationTimeout": 1800 // in seconds
    //"AutoUpdateConnectionString" : "set this to the same database as 'ConnectionString' but with credentials that can alter the database. If not set, defaults to the value of 'ConnectionString'"
  },
  "SQLiteDbOptions": {
    "ConnectionString": "Data Source=./data/vonkadmin.db",
    "AutoUpdateDatabase": true,
    "MigrationTimeout": 1800 // in seconds
  },
  "Security": {
    "AllowedNetworks": [ "::1/128" ], // e.g.: ["127.0.0.1/32", "::1/128" (ipv6 localhost), "10.1.50.0/24", "10.5.3.0/24", "31.161.91.98/32"]
    "OperationsToBeSecured": [ "reindex", "reset", "preload" ]
  }
},

Choosing your storage

The Administration API uses a database separately from the main ‘Firely Server Data’ database. Historically, SQL Server, MongoDB and Memory are supported as databases for the Administration API.
As of Firely Server (Vonk) version 0.7.1, SQLite is advised for this, and we have made that the default configuration. See Using SQLite on how to configure for this.

1. Repository: Choose which type of repository you want. Valid values are:

1. Memory

2. SQL

3. SQLite

4. MongoDb

1. MongoDbOptions: Use these with "Repository": "MongoDb", see Using MongoDB for details.

2. SqlDbOptions: Use these with "Repository": "SQL", see Using SQL server for details.

3. SQLiteDbOptions: Use these with "Repository": "SQLite", see Using SQLite for details.

Limited access

1. Security: You can restrict access to the operations listed in OperationsToBeSecured to only be invoked from the IP networks listed in AllowedNetworks.

• Operations that can be secured are:

  • reindex (see Re-indexing for new or changed SearchParameters)

  • reset (see Reset the database)

  • preload (see Preloading resources)

  • importResources (see Load Conformance Resources on demand)

  • StructureDefinition (restrict both read and write)

  • SearchParameter (restrict both read and write)

  • ValueSet (restrict both read and write)

  • CodeSystem (restrict both read and write)

  • CompartmentDefinition (restrict both read and write)

  • Subscription: (restrict both read and write, see Subscriptions)

• The AllowedNetworks have to be valid IP networks, either IPv4 or IPv6, and providing an the subnet prefix length explicitly is recommended. If you provide a ‘bare’ IP Address, it will be interpreted as a /32 for IPv4 and /128 for IPv6, effectively reducing it to a single host network.

• We recommend to only use internal, single host networks.

Examples:

• 127.0.0.1/32 (IPv4 localhost)

• ::1/128 (IPv6 localhost)

• 192.168.0.18/32 (IPv4 single host)

• 10.0.0.1/24 (IPv4 network ranging from 10.0.0.0 to 10.0.0.255, not recommended)

Warning

Are you hosting Firely Server behind a reverse proxy? Please review other relevant settings here: Using X-Forwarded-Host header.

Warning

If you run Firely Server version 5.6.0 or older, you MUST provide the subnet prefix length explicitly. If you do not, the subnet will be based on the class of the IP address, which usually leads to /24 for IPv4. This may allow for more IP addressess than you intended to be able to access the restricted operations.

Note

If these operations are not used on the Administration API, it is recommended to remove them from the API altogether:

• reindex

• reset

• preload

• importResources

To do so, add Vonk.Administration.Api.AdministrationOperationConfiguration to the Exclude list in the PipelineOptions:

"PipelineOptions": {
   "Branches": [
       {
           "Name": "administration",
           "Include": [
               "Vonk.Administration",
               ...
           ],
           "Exclude": [
               "Vonk.Administration.Api.AdministrationOperationConfiguration"
           ]
       }
   ]
}