iftgftc/traceability-driver repository overview

The Traceability Driver is a free open-source software tool that can be used to help reduce the costs of making a traceability solution interoperable. It is a standalone module that can be installed into an existing software system to expose traceability data using the GDST module.

⁠How does it work?

The Traceability Driver works by mapping data in an existing database into GDST events and master data. The GDST events and master data are then saved into a seperate database called the GDST Data Cache. The GDST Data Cache can then be queried using the GDST Communication Protocol.

⁠GDST Data Cache

The GDST Data Cache is where the traceability is stored. It serves as the data source for API queries. By default, the GDST Data Cache built using MongoDB, but it can be configured to use other databases such as SQL Server, MySQL, or PostgreSQL.

⁠Synchronization

Synchronizing the data between the existing software system and the Traceability Driver is done by using a database connection. Every minute, the Traceability Driver will sync up to 10,000 records from the database. Memory variables are used to keep track of where the last sync left off.

The synchronization process involves the following steps:

• Upon start up, the synchronization will execute automatically.
• The synchronization will load all mappings found in the local Mappings folder of the executing directory.
• The synchronization will execute each mapping in the order that they are found in the Mappings folder.
• The traceability data is stored into the GDST Data Cache.
• The Traceability Driver will wait 1 minute before attempting to synchronize again.

⁠Installation

The driver can be installed as a release or docker image.

⁠Docker Installation

The base image of the Traceability Driver does not contain any mappings. To configure the driver for your environment, you will need to create a docker file that uses the Traceability Driver base image and copies your mapping files to the app/Mappings folder in the container.

# Use the public image as the base
FROM iftgftc/traceability-driver:latest

# Copy your mapping folder into the container
COPY relative/path/to/your/mappings/folder/ /app/Mappings/

# The entrypoint/command from the base image will run automatically unless overridden

The docker installation of the Traceability Driver is intended to be deployed behind a reverse proxy that handles SSL and HTTPS redirection. Otherwise, a certificate for the Traceability Driver must be created and mounted to the container along with the relevant environment variables.

- ASPNETCORE_URLS = https://+:443;http://+:80
- ASPNETCORE_Kestrel__Certificates__Default__Password=<certificate-password>
- ASPNETCORE_Kestrel__Certificates__Default__Path =/<path-to-your-certificate-file>/aspnetapp.pfx

⁠Configuration

The Traceability Driver is configured using environment variables. These environment variables can be configured within a docker compose file for local development, or in a cloud environment where the container is deployed.

⁠Local Development

A docker compose file is recommended for local development.

When using a docker compose file, the TD_MAPPINGS_FOLDER environment variable must be set to the location of the mappings folder on the host machine. A corresponding mount point must be set in the docker compose file to mount the mappings folder into the container.

volumes:
    - ${TD_MAPPINGS_FOLDER}:/app/Mappings

⁠Docker Compose File Examples

Mongo, no Auth

services:
    traceabilitydriver:
        image: iftgftc/traceability-driver:latest
        environment:
        - ASPNETCORE_ENVIRONMENT=Release
        - ASPNETCORE_HTTP_PORTS=8080
        - URL=https://localhost:58950
        - MongoDB__ConnectionString=<your-connectionstring>
        - MongoDB__DatabaseName=TraceabilityDriverTests
        - DISABLE_HTTPS_REDIRECTION=TRUE
        ports:
            - "80:8080"
        volumes:
            - ${TD_MAPPINGS_FOLDER}:/app/Mappings
        

Mongo, with API Key Auth

services:
    traceabilitydriver:
        image: iftgftc/traceability-driver:latest
        environment:
        - ASPNETCORE_ENVIRONMENT=Release
        - ASPNETCORE_HTTP_PORTS=8080
        - URL=https://localhost:58950
        - MongoDB__ConnectionString=<your-connectionstring>
        - MongoDB__DatabaseName=TraceabilityDriverTests
        - DISABLE_HTTPS_REDIRECTION=TRUE
        - Authentication__APIKey__HeaderName=X-API-KEY
        - Authentication__APIKey__ValidKeys__0=test
        - Authentication__APIKey__ValidKeys__1=test_2
        ports:
            - "80:8080"
        volumes:
            - ${TD_MAPPINGS_FOLDER}:/app/Mappings
        

Mongo, with OAuth

services:
    traceabilitydriver:
        image: iftgftc/traceability-driver:latest
        environment:
        - ASPNETCORE_ENVIRONMENT=Release
        - ASPNETCORE_HTTP_PORTS=8080
        - URL=https://localhost:58950
        - MongoDB__ConnectionString=<your-connectionstring>
        - MongoDB__DatabaseName=TraceabilityDriverTests
        - DISABLE_HTTPS_REDIRECTION=TRUE
        - Authentication__JWT__Audience=<your-audience>
        - Authentication__JWT__Authority=<your authority>
        - Authentication__JWT__MetadataAddress=<your-metadata-address>
        ports:
            - "80:8080"
        volumes:
            - ${TD_MAPPINGS_FOLDER}:/app/Mappings
        

SQL Server, No Auth

services:
    traceabilitydriver:
        image: iftgftc/traceability-driver:latest
        environment:
        - ASPNETCORE_ENVIRONMENT=Release
        - ASPNETCORE_HTTP_PORTS=8080
        - URL=https://localhost:58950
        - SqlServer__ConnectionString=<your-connection-string>
        - DISABLE_HTTPS_REDIRECTION=TRUE
        ports:
            - "80:8080"
        volumes:
            - ${TD_MAPPINGS_FOLDER}:/app/Mappings
        

⁠Configuration Variables

⁠URL

Defines the URL where the API will be hosted. This must be configured correctly or the GDST Capability Test will fail.

Example URL Configuration

"URL": "http://localhost:5000"

⁠Authorization

The Traceability Driver allows for three modes of authentication:

• OAuth (JWT) Authentication - Allows for configuring OAuth authentication to the API using self-signed tokens.
• API Key Authentication - Allows for configuring API key authentication to the API which is required by GDST 1.2 communication protocol.
• No Authentication - If neither an API Key or OAuth authentication is present in the configuration, then no authentication is required to access the API.

⁠OAuth (JWT) Authentication

The OAuth (JWT) authentication is used to authenticate the API using self-signed tokens. The authentication is configured in the appsettings.json file of the installation.

• Token Issuer - The token issuer is the OAuth provider that is used to authenticate the API.
• Audience - The audience is the intended audience of the token.
• Metadata Address - The metadata address is the JWKS discovery endpoint that is used to validate the token.
• Require HTTPS Metadata - This is used to require HTTPS for the metadata address.

Example OAuth (JWT) Configuration

"Authentication": {
    "JWT": {
        "Authority": "https://your-oauth-provider.com",    
        "Audience": "your-api-identifier",                 
        "MetadataAddress": "https://your-oauth-provider.com/.well-known/openid-configuration", 
        "RequireHttpsMetadata": true       
     }
  },

⁠API Key Authentication

API Key authentication is used to grant access to the controllers and the API keys are defined in the appsettings.json file.

Example API Key Configuration

"Authentication": {
    "APIKey": {
        "HeaderName": "X-API-Key",
        "ValidKeys": [                     
          "key1-abc123",
          "key2-xyz789"
        ]
    }
}