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.
Before you begin, please read through the prerequisites for BWS on-premises installations.
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: ConsoleAs you can see, for complex settings a double underscore, __, is used to separate the hierarchical keys.
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.
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.
Once you have started the BWS portal, you must now do the following steps.
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.
When the BWS Portal detects that the database does not contain a BWS configuration yet, an initialization process is started.
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:
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).
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 'Upload Public RSA key'. After a short moment your protection key is generated. Click the button 'Copy Protection Key' and go back to your local BWS Portal.
Copy your Protection Key and finalize the BWS Configuration inside the BWS Portal.
The initial version of BWS should be configured now and you can continue to configure and start the BWSgRPC 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.
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
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.
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.
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>"As the BWS gRPC service utilizes the gRPC framework, which uses HTTP/2 based transport, the service supports the HTTP/2 protocol and only HTTP/2. This is due to clients that might use unsecure gRPC (plain http), that cannot negotiate the connection protocol, in contrast to TLS clients that run ALPN (Application-Layer Protocol Negotiation).
The BWS gRPC service supports the gRPC health checking protocol (health/v1) and also some classic HTTP health checks:
Please note that the HTTP health checks have to be called using https or by directly using the HTTP/2 protocol (as already mentioned above).
Without TLS configuration you can use