States Configuration

The component’s name of metaVault is DFAKTO_STATES. You will need to prefix the environment variable with this value.

Authentication

This section is used to configure the Identity provider used to manage the users and log in to the different components of the solution. See Identity provider configuration to help configure an identity provider for beVault.

The default Scope is: “profile email OpenID”

AppData JSON configuration file

JSON

{
  "Authentication": {
      "AuthMethod": "Jwt",
      "AdminEmail": "admin@test.net",
      "UserIdHeader": "MV-USER-ID",
      "Authority": "https://login.microsoft.com/[TENANTID]/v2.0",
      "ClientId": "[CLIENTID]",
      "Audience": "[CLIENTID]",
      "ValidIssuers": [
        "http://login.microsoftonline.com",
        "https://sustainable-tokens.green/auth/token"
      ],
      "Scope":"[COMPLETE_SCOPE_API] profile email openid",
      "RequireHttpsMetadata": true
    }
}

The values in the example above are formatted for a configuration of Azure Active Directory

Environment variables

YAML

Authentication__AuthMethod=Jwt
Authentication__AdminEmail=admin@test.net
Authentication__UserIdHeader=MV-USER-ID
Authentication__Audience=[CLIENTID]
Authentication__Authority=https://login.microsoftonline.com/[TENANTID]/v2.0
Authentication__ClientId=[CLIENTID]
Authentication__Scope=[COMPLETE_SCOPE_API] profile email openid
Authentication__ValidIssuers__0=http://login.microsoft.com
Authentication__ValidIssuers__1=https://sustainable-tokens.green/auth/token
Authentication__RequireHttpsMetadata=true

Don’t forget to prefix the variables with the component’s name

Config variable details

Parameter	Explanation
AuthMethod	Defines how authentication will function in Metavault and States. There are three possible values: Jwt (default): This is the classical OIDC setup, where the front will get a token that the back-end will validate. FakeJwt: Used for testing, don’t activate in production. This uses a json format with a list of claims as authentication token. Useful to bypass auth and test with various values. None: Used when authentication is handled by an external actor. All calls will be accepted. If using this mode, see UserIdHeader config to specify which HTTP header to use as the user id “Claim“.
ValidIssuers	For the “Jwt” AuthMethod. A list of additional issuer URLs that are considered valid when found in JWT authentication tokens. This concerns the “iss“ field in said tokens. Sometimes, token endpoints use different urls than the one specified in automatic configuration “.well-known” endpoints. This helps working around this problem.
AdminEmail	This user id will be considered an admin when connected, meaning they will have the rights to manage users/groups and their associated access rights. Additionally, with AuthMethod set to None and with an empty UserIdHeader, all calls to the Metavault and States will use this identity.
UserIdHeader	With AuthMethod set to None, if this is set, Metavault and States will use the contents of the specified HTTP header as the user id of the call. Example: If UserIdHeader is set to `MV-USER-ID` Metavault will look for something like this in the HTTP request: `MV-USER-ID=bob`, the connecting user will then be “bob“. This is mostly useful when incoming calls are already authenticated, like in the Snowflake app store.
RequireHttpsMetadata	Defines the protocol used to communicate with the Oauth authentication provider (Keycloak). “True“, which is the default, requires https. Local deployments may want to set “false”.

State Core

AppData JSON configuration file

JSON

"stateCore": {
    "RedisOptions": "localhost:6379",
    "ExecutionRetentionDays": 90,
    "ExecutionsCountLimit": 1000,
    "AwsAccessKey":"",
    "AwsSecretKey":""
},

Environment variables

YAML

DFAKTO_STATES_stateCore__AwsAccessKey=
DFAKTO_STATES_stateCore__AwsSecretKey=
DFAKTO_STATES_stateCore__ExecutionRetentionDays=90
DFAKTO_STATES_stateCore__ExecutionsCountLimit=1000
DFAKTO_STATES_stateCore__RedisOptions=localhost:6379

RedisOptions: The location of the redis instance
ExecutionRetentionDays: After how many days, the info about execution already finished should be deleted. Default to 90 days
ExecutionCountLimit: After how many executions should we start to clean up finished execution. Default to 1000 executions.
AwsAccessKey, AwsSecretKey: >= 1.5.0 if specified, a user will be created with this access key and corresponding secret key

If the ExecutionRetentionDays and ExecutionCountLimit options are both set, the first condition that is met will trigger the deletion of executions.

logs

By default, all applications are sending reasonable logs to the console, the configuration can be updated using Serilog configuration section.

Here is the configuration of the logs. The most useful field to set is probably the path field, which sets where the logs will be stored on the disk.

For the other options :

MinimumLevel: Indicate the level of log we want to store. From low to high, these are Verbose, Debug, Information, Warning, Error and Fatal
rollOnfileSizeLimit: Indicate if we want to create a new log file when the current one reaches its size limit
fileSizeLimitByte: Indicate the size limit of a log file. Once this size is reached, a new file will be created if the rollOnfileSizeLimit is set to true
retainedFileCountLimit: Indicate how much file we should have, we start overriding the first log file.
option : formatter: The formatter decides the format of the logs (text, json, …)

For more option, see https://github.com/serilog/serilog-settings-configuration

AppData JSON configuration file

JSON

{
    "Serilog": {
        "MinimumLevel": {
            "Default": "Information",
            "Override": {
                "Microsoft": "Warning",
                "Microsoft.EntityFrameworkCore": "Warning",
                "System": "Warning"
            }
        },
        "WriteTo": [
            {
                "Name": "Console",
                "Args": {
                    "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console",
                    "outputTemplate": "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj} <s:{SourceContext}>{NewLine}{Exception}"
                }
            },
            { 
                "Name": "File",
                "Args":{ 
                    "path": "/var/log/testlog_.txt", 
                    "rollingInterval": "Day",
                    "fileSizeLimitBytes": 10000000,
                    "rollOnFileSizeLimit": true,
                    "retainedFileCountLimit": 10
                }
            }
        ]
    }
}

Environment variables

YAML

Serilog__MinimumLevel__Default=Information
Serilog__MinimumLevel__Override__Microsoft=Warning
Serilog__MinimumLevel__Override__System=Warning
Serilog__WriteTo__0__Args__outputTemplate=[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj} <s:{SourceContext}>{NewLine}{Exception}
Serilog__WriteTo__0__Args__theme=Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console
Serilog__WriteTo__0__Name=Console
Serilog__WriteTo__1__Args__fileSizeLimitBytes=10000000
Serilog__WriteTo__1__Args__path=/var/log/testlog_.txt
Serilog__WriteTo__1__Args__retainedFileCountLimit=10
Serilog__WriteTo__1__Args__rollingInterval=Day
Serilog__WriteTo__1__Args__rollOnFileSizeLimit=True
Serilog__WriteTo__1__Name=File

Don’t forget to prefix the variables with the component’s name

Others

Web server config

AppData JSON configuration file

JSON

{
  "Hsts": {
        "MaxAge": "00.00:05:00",
        "Preload": true
    }
}

Environment variables

YAML

Hsts__MaxAge=00.00:05:00
Hsts__Preload=True

Don’t forget to prefix the variables with the component’s name

HTTP Strict Transport Security (HSTS) is a simple and widely supported standard to protect visitors by ensuring that their browsers always connect to a website over HTTPS.

MaxAge: The time, that the browser should remember that a site is only to be accessed using HTTPS.
Preload: it is possible to enforce secure connections on a higher level, even before visiting a website for the first time: the HSTS preload list. This is a list, managed by google, with domain names that by default support HSTS:

AppData JSON configuration file

JSON

{
  "Urls": "http://localhost:5000",
  "ForwardedHeadersOptions": {
      "ForwardedHeaders": "All"
  }
}

Environment variables

YAML

ForwardedHeadersOptions__ForwardedHeaders=All
Urls=http://localhost:5000

Don’t forget to prefix the variables with the component’s name

The ForwardedHeadersOptions set the behavior of proxied headers onto the requests. You can most likely leave it to the default All value.

The accepted values are :

All : Process X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto.
None : Do not process any forwarders
XForwardedFor : Process X-Forwarded-For, which identifies the originating IP address of the client.
XForwardedHost : Process X-Forwarded-Host, which identifies the original host requested by the client.
XForwardedProto : Process X-Forwarded-Proto, which identifies the protocol (HTTP or HTTPS) the client used to connect.

IpRateLimiting

It is possible to limit the number of requests sent to the API to avoid DDoS. All options are described here. Here is a sample configuration section.

IP Rate Limiting is disabled by default (if no configuration is provided)

AppData JSON configuration file

JSON

"IpRateLimiting": {
    "EnableEndpointRateLimiting": false,
    "StackBlockedRequests": false,
    "RealIpHeader": "X-Real-IP",
    "ClientIdHeader": "X-ClientId",
    "HttpStatusCode": 429,
    "IpWhitelist": [ "127.0.0.1", "::1/10" ],
    "EndpointWhitelist": [ "get:/health/live","get:/health/ready" ],
    "ClientWhitelist": [ ],
    "GeneralRules": [
      {
        "Endpoint": "*",
        "Period": "1s",
        "Limit": 2
      },
      {
        "Endpoint": "*",
        "Period": "15m",
        "Limit": 100
      },
      {
        "Endpoint": "*",
        "Period": "12h",
        "Limit": 1000
      },
      {
        "Endpoint": "*",
        "Period": "7d",
        "Limit": 10000
      }
    ]
  }

Environment variables

YAML

IpRateLimiting__ClientIdHeader=X-ClientId
IpRateLimiting__EnableEndpointRateLimiting=False
IpRateLimiting__EndpointWhitelist__0=get:/health/live
IpRateLimiting__EndpointWhitelist__1=get:/health/ready
IpRateLimiting__GeneralRules__0__Endpoint=*
IpRateLimiting__GeneralRules__0__Limit=2
IpRateLimiting__GeneralRules__0__Period=1s
IpRateLimiting__GeneralRules__1__Endpoint=*
IpRateLimiting__GeneralRules__1__Limit=100
IpRateLimiting__GeneralRules__1__Period=15m
IpRateLimiting__GeneralRules__2__Endpoint=*
IpRateLimiting__GeneralRules__2__Limit=1000
IpRateLimiting__GeneralRules__2__Period=12h
IpRateLimiting__GeneralRules__3__Endpoint=*
IpRateLimiting__GeneralRules__3__Limit=10000
IpRateLimiting__GeneralRules__3__Period=7d
IpRateLimiting__HttpStatusCode=429
IpRateLimiting__IpWhitelist__0=127.0.0.1
IpRateLimiting__IpWhitelist__1=::1/10
IpRateLimiting__RealIpHeader=X-Real-IP
IpRateLimiting__StackBlockedRequests=False

Don’t forget to prefix the variables with the component’s name

Prometheus integration

Prometheus (https://prometheus.io/) is an open-source systems monitoring and alerting

DefaultContextLabel: Metrics recorded are grouped into “Contexts”, for example a database context or application context. Metrics names should be unique per context. The default is “Application”.
Enabled: Allows recording of all metrics to be enabled/disabled, default is true.
ApdexTrackingEnabled: Allows enabling/disabling of calculating the apdex score on the overall responses times. Defaults to true. The Apdex (Application Performance Index) is used to monitor end-user satisfaction. It is an open industry standard that estimates the end user’s satisfaction level on an application’s response time through a score between 0 and 1.
apdexTSeconds: The Apdex T seconds value used in calculating the score on the samples collected.
IgnoredHttpStatusCode: Allows specific HTTP status codes to be ignored when reporting on response related information, e.g., You might not want to monitor 404 status codes.
IngoredRoutesRegexPatterns: An list of regex patterns used to ignore matching routes from metrics tracking.
Oauth2TrackingEnabled: Allows recording of all OAuth2 Client tracking to be enabled/disabled. Defaults to true.
MetricsEndPointEnabled: Allows enabling/disabling of the /metrics endpoint, when disabled will result in a 404 status code, the default is true.
MetrucsTextEndpointEnabled: Allows enabling/disabling of the /metrics-text endpoint, when disabled will result in a 404 status code, the default is true.
EnvironmentInfoEndpointEnabled: Allows enabling/disabling of the /env endpoint, when disabled will result in a 404 status code, the default is true.

AppData JSON configuration file

JSON

{
    "MetricsOptions": {
        "DefaultContextLabel": "dFakto States",
        "Enabled": true
    },
    "MetricsWebTrackingOptions": {
        "ApdexTrackingEnabled": true,
        "ApdexTSeconds": 0.1,
        "IgnoredHttpStatusCodes": [ 404 ],
        "IgnoredRoutesRegexPatterns": [],
        "OAuth2TrackingEnabled": true
    },
    "MetricEndpointsOptions": {
        "MetricsEndpointEnabled": true,
        "MetricsTextEndpointEnabled": false,
        "EnvironmentInfoEndpointEnabled": true
    }
}

Environment variables

YAML

MetricEndpointsOptions__EnvironmentInfoEndpointEnabled=True
MetricEndpointsOptions__MetricsEndpointEnabled=True
MetricEndpointsOptions__MetricsTextEndpointEnabled=False
MetricsOptions__DefaultContextLabel=dFakto States
MetricsOptions__Enabled=True
MetricsWebTrackingOptions__ApdexTrackingEnabled=True
MetricsWebTrackingOptions__ApdexTSeconds=0.1
MetricsWebTrackingOptions__IgnoredHttpStatusCodes__0=404
MetricsWebTrackingOptions__OAuth2TrackingEnabled=True

Don’t forget to prefix the variables with the component’s name

Sentry

Sentry (https://sentry.io/) is an application monitoring platform.

DSN: where to send events, so the events are associated with the correct project.
IncludeRequestPayload: whether we should send the request body to Sentry. This is done so that the request data can be read at a later point in case an error happens while processing the request.
SendDefaultPii: Whether we should report the user who made the request
MinimumBreadcrumbLevel: Configure the lowest level a message has to be to become a breadcrumb. Breadcrumbs are the last (by default 100) log that were sent before the event was fired to Sentry.
MinimumEventLevel: A LogLevel which indicates the minimum level a log message has to be sent to Sentry as an event. By default, this value is Error.
AttachStackTrace: Configures whether Sentry should generate and attach stack traces to capture message calls.
Debug: Turns debug mode on or off. If debug is enabled, Sentry will attempt to print out useful debugging information if something goes wrong with sending the event. The default is always false. It's generally not recommended to turn it on in production, though turning debug mode on will not cause any safety concerns.
DiagnosticsLevel: Debug by default.
DefaultTags: Defaults tags to add to all events.

AppData JSON configuration file

JSON

{
  "Sentry": {
      "Dsn": "",
      "IncludeRequestPayload": true,
      "SendDefaultPii": true,
      "MinimumBreadcrumbLevel": "Debug",
      "MinimumEventLevel": "Warning",
      "AttachStackTrace": true,
      "Debug": true,
      "DiagnosticsLevel": "Error",
      "DefaultTags": {
          "client": "XXX"
      }
  }
}

Environment variables

YAML

Sentry__AttachStackTrace=True
Sentry__Debug=True
Sentry__DefaultTags__client=XXX
Sentry__DiagnosticsLevel=Error
Sentry__Dsn=
Sentry__IncludeRequestPayload=True
Sentry__MinimumBreadcrumbLevel=Debug
Sentry__MinimumEventLevel=Warning
Sentry__SendDefaultPii=True

Don’t forget to prefix the variables with the component’s name