BWS On-Premises Installation

Docker Images & Container Settings

Many roads lead to Rome. The required settings to run the BWS Docker container can be provided with the appsettings files, that are mounted into the container, or with Docker environment variables.

The MongoDB connection string is required by all BWS services & portal
A recommend secret used to encrypt your RSA private key. Must be identical to the secret used with the other BWS containers!
Additional settings are optional, like Kestrel (Web hosting) settings or logging settings as described later in this document.

You define the secret (Base64 encoded byte array) used to encrypt your RSA private key. If no secret is configured, BWS uses a default secret. Feel free to use our BioID Playground API to generate Base64 encoded secrets.

Before you begin, please read through the prerequisites for BWS on-premises installations.

1. Start the BWSPortal-OnPrem first

1.1 Configure the necessary settings

At first you must configure the BWSPortal docker container. You have the following required settings:

The following code should be saved in the file e.g. appsettings.bwsportal.json.

{
    "MongoDB": {
        "ConnectionString": "mongodb://username:password@mongodb.mydomain.com:27017/bws?ssl=true"
    },
    "KeyEncryption": {
        "Secret": "<a key encryption secret - Base64 encoded byte array>"
    },
    "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [{
        "Name": "Console"
        }
    ]}
}

If you use Docker environment variables, these could look like this:

environment:
    MongoDB__ConnectionString: mongodb://username:password@mongodb.mydomain.com:27017/bws?ssl=true
    KeyEncryption__Secret: <a key encryption secret - Base64 encoded byte array>
    Serilog__MinimumLevel: Information
    Serilog__WriteTo__0__Name: Console

As you can see, for complex settings a double underscore, __, is used to separate the hierarchical keys.

1.2 Starting the docker container

The following code should be saved in the file e.g. bwsportal-compose.yaml and executed with the following command docker compose -f bwsportal-compose.yaml up -d


services:
    bwsportal-onprem:
    image: bcr.bioid.com/{project}/bwsportal-onprem:{version}
    restart: always
    networks:
        - bwsportal
    ports:
        - {dockerHostPort}:8080
    volumes: 
        - /{dockerHostPath}/bwslogging/:/mnt/bwslogging/
        - /{dockerHostPath}/appsettings.bwsportal.json:/app/appsettings.json
    environment:  
        ASPNETCORE_URLS: http://+:8080
networks:
    bwsportal:

This should start the BWS Portal listening on HTTP port 8080. We highly recommend to configure the Portal to use TLS as outlined below.

Advanced configuration options

The BWS Portal services itself comes with a few settings, mainly to configure the database connection, but other things can be configured as well.

The BWS Portal comes with an integrated user management. Additionally to this local user management an OpenID Connect provider can be used for authentication. The configuration of an external OpenID Connect Server looks as follows:

{
  "OIDC": {
    "Authority": "<URL of OpenID Connect Server>",
    "ClientId": "<OIDC client ID>",
    "ClientSecret": "<OIDC client secret>",
    "DisplayName": "<Display name for this OIDC provider>"
  }
}

environment:
    OIDC__Authority: <URL of OpenID Connect Server>
    OIDC__ClientId: <OIDC client ID>
    OIDC__ClientSecret: <OIDC client secret>
    OIDC__DisplayName: <Display name for this OIDC provider>

You need to register your client at the OpenID Connect provider. Please make sure the Redirect URI on the OIDC provider is set to your BWS Portal endpoint with the path /signin-oidc appended.

2. BWS configuration & activation

Once you have started the BWS portal, you must now do the following steps.

Sign in to the BWS Portal

Depending on what you have previously configured in the Docker container, you can sign in using a local account or using an OpenID Connect provider. If you use the local account, you must register first.

Then sign in to the BWS Portal.

Start BWS configuration

When you navigate to the BWS Portal web site for the first time, you have to register as a new user, or, if you have configured an OpenID Connect provider, you can login with your OpenID Connect account.

If the BWS Portal detects that the database does not contain a BWS configuration yet, an initialization process is started.

Step 1: Enter your company name

The user enters a name for the new BWS on-prem installation, e.g. the company name and click on 'Create On-Prem version'.

The following steps are now carried out automatically:

With this name, an installation, a subscription and a first BWS client is configured in the database.
A public/private RSA Key Pair is generated and stored in the database (as PKCS#8 encrypted private key info) - for the encryption of the private key info, the above mentioned key secret is used.
The RSA key pair is mainly used for the communication with BioID (see below).
The user creating these first entries automatically gets Admin privileges.

Step 2: Copy your Public Key to bwsportal.bioid.com

For the communication with BioID, the public key needs to be exported/copied and imported/pasted into the pre-configured on-prem installation client at the BioID BWS Portal (Cloud).

You can copy your public key now in the initialization wizard, or, if you skipped this step already, go in your BWS portal to Settings → Management and click on 'Copy Public Key' to copy the key to your clipboard.

In the BioID BWS Portal import your public key by clicking on the 'Create initial protection key' button. The dialog opens, put your public key here and click on the button 'Send Public RSA Key to BioID …'. After a short moment your protection key is generated. Click the button 'Copy Protection Key' and go back to your local BWS Portal.

Step 3: Enter the Protection Key from bwsportal.bioid.com

Copy your Protection Key and finalize the BWS Configuration inside the BWS Portal. Again, if you skipped this step already, go to Settings → Management and 'Insert your Protection Key' here.

The initial version of BWS should be configured now and you can continue to configure and start the BWSgRPC service.

If you have skipped the previous steps of Public/Protection keys, you can create/renew the license as follows.

Please note, that the newly created subscription has no permissions assigned yet. At least one user needs to have owner permissions to this subscription. Therefore you have to add yourself or another responsible person (which has to register at the on-prem BWS Portal first) as Owner to the subscription permissions.

3. Start the BWS gRPC Service

The BWS gRPC Service implements the gRPC BWS API.

It requires the BWS Portal to be installed and an initial configuration to be created first. Only if a valid installation configuration with a valid encryption key and protection key can be found in the database, the service will start up correctly.

3.1 Configure the necessary settings

The following code should be saved in the file e.g. appsettings.bwsgrpc.json.

{
  "MongoDB": {
    "ConnectionString": "mongodb://username:password@mongodb.mydomain.com:27017/bws?ssl=true"
  },
  "ClientService": {
    "Secret": "<a key encryption secret - Base64 encoded byte array>"
  },
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [{
        "Name": "Console"
      }
    ]
  }
}

If you use Docker environment variables, these could look like this:

environment:
    MongoDB__ConnectionString: mongodb://username:password@mongodb.mydomain.com:27017/bws?ssl=true
    ClientService__Secret: <a key encryption secret - Base64 encoded byte array>
    Serilog__MinimumLevel: Information
    Serilog__WriteTo__0__Name: Console

Common Pitfalls

Secret for bwsportal:
"KeyEncryption": {
    "Secret": "<a key encryption secret - Base64 encoded byte array>""
}

Secret for bwsgrpc
"ClientService": {
    "Secret": "<a key encryption secret - Base64 encoded byte array>""
}

Please ensure that you use the same secret! The secret for the BWSPortal can also be found in the "KeyEncryption" section and for the BWSgRPC service in the "ClientService" section. Please use our BioID Playground API to generate Base64 encoded secrets.

3.2 Now we can run the BWS gRPC service

The following code should be saved in the file e.g. bwsgrpc-compose.yaml and executed with the following command docker compose -f bwsgrpc-compose.yaml up -d

services:
    bwsgrpc:
        image: bcr.bioid.com/{project}/bwsgrpc-onprem:{version}
        restart: always
        networks:
            - bwsgrpc
        ports:
            - {dockerHostPort}:50051
        volumes: 
            - /{dockerHostPath}/bwslogging/:/mnt/bwslogging/
            - /{dockerHostPath}/appsettings.bwsgrpc.json:/app/appsettings.json
        environment:  
            ASPNETCORE_URLS: http://+:50051
networks:
    bwsgrpc:

This should start the BWS gRPC service listening on HTTP port 50051. We highly recommend to configure the service to use TLS.

General settings used by all services

BWS uses the Kestrel web server to host our services. Therefore, the Kestrel endpoint configuration options can be applied to the BWS services as well.

Please do not forget to create a mountpoint to your certificate on your docker host to load the certificate. For example, to configure TLS you can use a settings file like:

{
    "Kestrel": {
        "Endpoints": {
            "Https": {
                "Url": "https://+:5001",
                "Certificate": {
                    "Path": "<path to .pfx file>",
                    "Password": "<certificate password>"
                }
            }
        }
    }
}

environment:
    ASPNETCORE_URLS: https://+:5001
    ASPNETCORE_Kestrel__Certificates__Default__Path: <path to .pfx file>
    ASPNETCORE_Kestrel__Certificates__Default__Password: <certificate password>

All our services use Serilog for structured logging. Therefore, logging can be configured using Serilog settings. Beside of the standard Serilog sinks Console and File, we already added sinks like Seq and Elasticsearch. Other sinks can be added on demand.

Here is an example configuration settings file writing to the Console and Seq:

{
  "Serilog": {
    "MinimumLevel": "Warning",
    "WriteTo": [
      {
        "Name": "Console"
      },
      {
        "Name": "Seq",
        "Args": {
          "serverUrl": "<URL of SEQ server>"
        }
      }
    ]
  }
}

environment:
            Serilog__MinimumLevel=Warning
            Serilog__WriteTo__0__Name: Console
            Serilog__WriteTo__1__Name: Seq
            Serilog__WriteTo__0__Args__serverUrl: "<URL of SEQ server>"

HTTP/2 and HTTP/1.1

As the BWS service allows RESTful API calls and also utilizes the gRPC framework, which uses HTTP/2 based transport, the service supports the HTTP/2 and the HTTP/1.1 protocols by default. Therefore it might come to problems when using unsecure connections (plain http), that cannot negotiate the connection protocol, in contrast to TLS clients that run ALPN (Application-Layer Protocol Negotiation).

When you come across those kind of problems, consider to explicitely configure Kestrel for the specific protocols.

Health Checks

The BWS gRPC service supports the gRPC health checking protocol (health/v1) and also some classic Docker health checks:

gRPC liveness health check against the server by using the service name liveness
gRPC readiness health check against the BWS API service by using the service name readiness
Docker liveness health check at endpoint /livez
Docker readiness health check at endpoint /readyz
classic Docker health check at endpoint /healthz

Testing

When everything went fine, we can now test our BWS installation using the BWS 3 command line interface (as downloadable here), e.g. bws healthcheck --host https://bws.yourdomain.com

Browse docs