Security Framework

Tranquil Data supports a streamlined Authentication, Authorization, and Accounting model for all exposed network end-points. It supports both termination and pass-through security models for exported datastores, and may enforce authentication for User Interfaces and REST API sessions. A dedicated audit log accounts for all configuration, open ports, and client interaction.

Security Model#

There are a few types of network access that Tranquil Data enables. One is the set of web UIs and REST APIs, which are all exposed on a single HTTPS(s) port and categorized by root URI. Another is via Datastore Export, each of which uses a unique port and defines security capabilities based on the backing store type. The configuration and audit model described below applies to all of these types.

User Interface and API Security#

All web UIs and APIs may optionally enable TLS server-auth. By default, clients do not need to authenticate to the server to access any endpoint. Authentication may be enabled and enforced as shown below. The supported authentication types for HTTPS UI and REST interfaces are Basic Auth (which maps to name-password in configuration), OAuth, and AWS. If a component is configured to enforce authentication, and a client provides invalid credentials, then the request will be audited and denied.

Datastore Export Security#

Tranquil Data may act as a terminating network endpoint for exported interfaces. Clients connect to the port exposed by the Tranquil Data software, and based on configuration are either authenticated directly or by the backing datastore.

If the configuration specifies that clients must be verified directly, then Tranquil Data runs an authentication process before allowing any messages to flow-through to the backing service. This supports models where clients do not have rights to access a datastore directly. It also supports models where the client does have direct access rights, but where clients must be verified before talking directly to the backing service, or where it's important to have tranquil data be an active participant in negotiation.

A "pass-through" model is also supported where the Tranquil Data software does not attempt to verify the client, and instead the authentication protocol is run on a direct connection from Tranquil Data to the backing datastore to verify the client credentials. This supports models where Tranquil Data should be a passive intermediary, or where it's preferable to decentralize security management to each backing datastore. This is the default if configuration does not enforce specific verification.

The identity used to establish connections between Tranquil Data and a backing datastore depends on how the datastore was exported. If the export contained authentication credentials, then all back-end connections will use that identity regardless of how a client authenticates on the front-end. Otherwise, back-end connections will use the same identity and credentials that were used on the front-end. See datastore-specific documentation to learn how credentials are supplied at export-time for each supported datastore.

Depending on the method used to verify a client, assertions may be extracted from credentials. Each verifier type supports a specific model for extracting assertions when clients are authenticated locally. Similarly, specific credential types may supply assertions from successful pass-through authentication. These become part of the context model during record evaluation and made available to policy decision-making.

Configuration#

Configuration is defined for a single process through a stand-alone JSON-encoded file. The location of this file is defined via configuration. The root of the config file is as follows:

Field Name	Type	Required
verifiers	array of VerifierConfig
credentials	array of CredentialConfig
enforcedComponents	array of CredentialSelector

The values of verifiers define configuration for all available credential verifiers, regardless of whether they're used by any components. These configurations are checked at startup, ensuring that properties are valid, and that named endpoints are available.

The values of enforcedComponents select components which enforce verification. If the selected component is a REST API then it means that authentication will be required to use that API. If the selected component is a datastore export it means that pass-through is not supported for that export.

VerifierConfig#

Verifier Config defines all supported configurations for a given type of Verifier:

Field Name	Type	Required
verifier	string identifying a Verifier Type
profiles	array of VerifierProfile
default	string

The value of default if present, must name one of the profiles. It is the profile used if no profile is specified for credential verification. It is an error to name a default profile that is not defined.

VerifierProfile#

Verifier Profile defines specific configuration for a Verifier:

Field Name	Type	Required
profile	string
configuration	map of string to any

The value of profile is the name of this profile. It is an error to define multiple profiles with the same name.

The optional configuration is any specific configuration (as documented for each verifier type) that accompanies this profile. If absent/empty then all values will use defaults.

CredentialConfig#

Credential Config defines a mapping from one credential type to how that credential type is verified:

Field Name	Type	Required
type	string identifying a Credential Type
verifiers	array of CredentialVerifier

The value of verifiers is an ordered list defining precedence for how the given credential type will be verified. When a given component registers it will walk through this list and pick the first verifier that "selects" against the component. A default verifier will be placed last in precedence. It is an error to have more than one default verifier in this list.

CredentialVerifier#

Credential Verifier "selects" one component for a given credential verification model:

Field Name	Type	Required
verifier	string
profile	string
selectors	CredentialSelector

The value of verifier names a verifier type that is configured. It is an error to specify an unknown verifier type or to specify a verifier type that is not configured.

The value of profile names a verifier profile from this configuration. It may be empty only if the named verifier has a default profile. It is an error if this profile is unknown.

If selectors is absent, then it selects all components.

CredentialSelector#

Credential Selector matches on one of more components:

Field Name	Type	Required
componentName	SelectorComponent name
componentType	SelectorComponent type
domainName	string

The value of componentName may be empty to select all components.

The value of componentType may be empty to select all component types.

The value of domainName may be empty to select all domains.

SelectorComponent#

Component Name	Component Type	Description
`config`	`api`	The REST API and Web UI endpoint for use and sharing configuration
`decision`	`api`	The REST API endpoint for issuing traced decision queries
`export`	`api`	The REST API endpoint for issuing export requests
`fhir`	`export`	Any endpoint that exports a FHIR datastore
`mapping`	`api`	The REST API and Web UI endpoint for managing mapping groups
`mongodb`	`export`	Any endpoint that exports a MongoDB datastore
`mysql`	`export`	Any endpoint that exports a MySQL datastore
`pipeline`	`export`	Any endpoint that exports a Pipeline component
`postgres`	`export`	Any endpoint that exports a PostgreSQL datastore
`redact`	`api`	The REST API and Web UI endpoint for issuing traced document redaction
`s3`	`export`	Any endpoint that exports an AWS S3 datastore
`user`	`api`	The REST API for onboarding users and managing consent

Credential Types#

Credential Name	Description
`awsSigningCredentials`	Format used within Amazon Web Services to authenticate data or provide in-transit protection. These are typically provided in HTTP headers or as HTTP query parameters.
`namepwd`	A paired username and password, common to many DBMSs, and web services employing Basic Auth.
`rawBearerToken`	Token structure, such as JSON Web Token for verifying identity and exchanging assertions.

Supported Types

The supported credential types, and methods for verifying credentials and assertions (below) represent a recent product capability and capture a few common mechanisms that in practice our customers have requested. Input is welcome and encouraged about what additional types should be supported in future releases.

Verifier Types#

A Verifier is a component that supports verifying one or more types of Credentials against some service. Each verifier type has a unique identifier and set of configuration properties.

OAuth#

This verifier supports using rawBearerToken credentials to verify a client using an external OAuth service. The type name of this verifier is oauth.

This verifier provides any validated scopes in a token as assertions for evaluation and context formation

Property Name	Type	Description
`clientRequestTimeout`	integer	The time in seconds to wait for a response from the external OAuth service (default is 60)
`introspectionUrl`	string	The URL to use for token introspection (default is empty)
`maxMetadataSize`	integer	The maximum length of allowed metadata (default is 0 meaning no limit)
`resourceServerId`	string	The server identifier, or audience, is what the backing store calls itself when talking to the remote oauth service
`serverMetadataUrl`	string	The URL endpoint of the remote OAuth service
`allowedSigningAlgorithms`	array of string	The set of permitted signature algorithms (default is the standard set excluding `none`)
`verifyOauthServiceCertificate`	boolean	True if the remote service's PKC must be verified to proceed (default is true)

At export-time for datastores, the value for resourceServerId may be overridden though export configuration.

LDAP#

This verifier supports using namepwd credentials to verify a client using an external LDAP service. The type name of this verifier is ldap.

This verifier does not provide any assertions for evaluation or context formation.

Property Name	Type	Description
`hostname`	string	The DNS Name or IP Address where an LDAP service is running, optionally ending in `:PORT`
`useTLS`	boolean	`true` if the service expects a TLS connection (default is `false`)
`nameComponent`	string	The component identifying a user (default is `uid`)
`rootComponents`	string	The remaining components that form the DN for authentication (default is empty)

None of these values may be overridden at export-time.

As an example:

ConfigurationLDAP Interaction

{
    "hostname": "ldap.example.com",
    "useTLS": true,
    "rootComponents": "o=us"
}

ENDPOINT="ldaps://ldap.example.com:636"
BINDDN="uid=NAME;o=us"

Amazon Web Services#

This verifier supports using awsSigningCredentials credentials to verify a client using the provided credentials. The type name of this verifier is aws.

This verifier does not provide any assertions for evaluation or context formation.

Property Name	Type	Description
`id`	string	The identity for the one client allowed to connect
`key`	string	The key for the allowed client identity
`region`	string	The region where connection requests are allowed

All of these values may be set or overridden at export-time though export configuration.

Evolving Feature

This verifier is provided in its current form only to make testing and development simple & self-contained. It will be updated in a future release to integrate with external infrastructure and support production AWS use-cases.

Audit Log#

The audit log module captures details relevant to security auditing. In the case of a user connecting to Tranquil a unique identifier is included that can be used to coorelate behavior in other trace structures. The security audit trail includes:

The complete, active auth configuration at startup
All network ports, including endpoint type, opened by the engine for API access, metrics export, and Peer communication
All network ports, including the datastore identifier, opened as a result of datastore export
All outgoing connections made for any given datastore export, including the endpoint and identity used
All incoming connections that are successfully authenticated, including the associated component
All incoming connections that fail to authenticate the client, including the associated component
All incoming connections that fail because an unknown credential or protocol type is requested, including the associated component
All incoming connections that are allowed to "pass-through" an export for authentication at the backing store, including the associated component

Process configuration, open ports, and configuration selection is logged at info. Each of the component types logs connection attempts in its own named category (e.g., all connections to any exported FHIR datastore will be logged in the fhir category). Successful attempts are logged at info and unsuccessful attempts at warn. Connections that are passed-through to a backing datastore or allowed to use APIs with no authentication are logged at debug.

Example Configuration#

{
    "verifiers": [
        {
            "verifier": "ldap",
            "profiles": [
                {
                    "profile": "dbms",
                    "configuration": {
                        "hostname": "",
                    }
                },
                {
                    "profile": "admin",
                    "configuration": {
                        "hostname": "",
                    }
                }
            ],
            "default": "default"
        },
        {
            "verifier": "oauth",
            "profiles": [
                {
                    "profile": "gateway"
                }
            ]
        }
    ],
    "credentials": [
        {
            "type": "namepwd",
            "verifiers": [
                {

                }
            ]
        },
        {
            "type": "rawBearerToken",
            "verifiers": [
                {
                    "verifier": "oauth"
                }
            ]
        }
    ],
    "enforcedComponents": [
        {
            "componentType": "api"
        }
    ]
}