Firely Server Administration API

The Firely Server is fully manageable through RESTful interactions via the Administration API. This API provides access to the administration database and supports a range of maintenance operations.

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

The following functions are available in the Administration API:

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 Adjusting Firely Server settings.

"Administration": {
  "Repository": "SQLite", //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
  },
  "AllowedNetworks": [ "127.0.0.1/32", "::1/128" ] // IPv4 and IPv6 localhost with explicit subnet masks
},

Choosing your storage

The Administration API uses its own database, separate from the main Firely Server Data database. It supports SQLite, SQL Server, and MongoDB storage as database options.

Note

SQLite is recommended in most deployments and is the default configuration. However, note that SQLite has limitations in auto-scaling environments like Kubernetes and Azure Web Apps. For details on configuration, see SQLite for Firely Server Administration on how to configure for this.

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

  1. SQL

  2. SQLite

  3. 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.

Limiting access

You can restrict access to administrative operations by setting the NetworkProtected property to true in each operation’s configuration under Administration.Operations:

"Administration": {
  "AllowedNetworks": ["127.0.0.1", "::1"],
  "Operations": {
    "$reindex": {
      "Name": "$reindex",
      "Level": ["System"],
      "Enabled": true,
      "NetworkProtected": true
    },
    "$reset": {
      "Name": "$reset",
      "Level": ["System"],
      "Enabled": true,
      "NetworkProtected": true
    }
  }
}

The AllowedNetworks property defines which IP networks can access operations with NetworkProtected set to true.

Operations that can be secured include:

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

  • $reset (see Reset the database)

  • $preload (see Preloading resources)

  • $import-resources (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)

  • StructureMap (restrict both read and write)

  • ConceptMap (restrict both read and write)

  • Library (restrict both read and write)

  • Measure (restrict both read and write)

  • Questionnaire (restrict both read and write)

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

The following rules apply for network configuration:

  • The AllowedNetworks have to be valid IP networks, either IPv4 or IPv6, and providing 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

  • $reindex-all

  • $reset

  • $preload

  • $import-resources

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"
           ]
       }
   ]
}