Licensed to be used in conjunction with basebox, only.
broker is basebox' GraphQL HTTP(s) server. Your client sends GraphQL requests to the broker's
/graphql endpoint, e.g.
The broker's tasks are:
- Handle OpenID Connect
- Authorize and authenticate GraphQL requests
- Validate GraphQL requests
- Host the BLL (Business Logic Layer, not part of the first BETA but coming soon)
- Communicate with the dbproxy to resolve requests
- Return GraphQL compliant JSON response
Running the broker
In production, the broker should be run as a system service; we will provide instructions on how to achieve this soon. For now, since basebox is not yet production ready, you run broker simply in a terminal.
Command Line Parameters
To see broker's command line arguments, call it with
❯ ./broker --help This is broker, basebox' universal high performance GraphQL server. Usage: broker [OPTIONS] Options: -c, --config-file <CONFIG_FILE> Path and file name of the configuration file -d, --dump-default-config Dump default config file to stdout and quit -h, --help Print help (see a summary with '-h') -V, --version Print version
So to run broker, you create the config file (see below) and start broker like so:
Example Configuration File
Most of broker's options are controlled by a TOML configuration file. You can get the default configuration file and use it as a starter for your own configuration by running broker with the
-d switch; so to create a config file template, just run:
This will create a file named
config.toml in the current directory with the default configuration.
Here is the current version:
[generic] # log level; can be error, warn, info, debug, trace log_level = "info" [graphql] # path and file name to GraphQL schema file schema_file = "/path/to/schema.gql" # allow introspection is off by default allow_introspection = false [proxy] # host name or IP of basebox DB proxy host = "127.0.0.1" port = 8081 # Whether to use http or https to connect to the proxy tls = false [server] # Host name of the broker (GraphQL server) host = "127.0.0.1" # Port number; default is 80 for http, 443 for https port = 8080 # number of HTTP server threads to spawn; default is one per CPU core # workers = 2 # Path and file name of TLS/SSL key file # tls_key_file = "/path/to/key.pem" # Path and file name of TLS certificate (chain) file # tls_cert_file = "/path/to/cert.pem" [auth] # `mode` can be either "access-token" or "client". In access-token mode, all clients sending # GraphQL requests to basebox just pass an access token in the "Authorization" HTTP header. # In client mode, basebox acts as the OpenID Connect client and requests ID and access tokens # from the OpenID Connect server on behalf of the client. # See https://docs.basebox.io/guide/authorization mode = "access-token" # URL of IdP's discovery endpoint. If not set, the URL is made up by appending # ".well-known/openid-configuration" to the `iss` field. # discovery_url = "https://idp.example.com/realms/testing/.well-known/openid-configuration" # URL of IdP's public keystore. If set, the discovery endpoint is not used at all. # jwks_url = "https://idp.example.com/realms/testing/protocol/openid-connect/certs" # Access token validation: # Contents of 'iss' field, usually the URL of the authentication realm # iss = "https://idp.example.com/realms/testing" # Contents of the 'aud' field for access tokens; for Keycloak, this defaults to 'account'; # for Auth0, this is the value of the Default Audience field in your Tenant settings. # aud = "account" # To use "client" mode, please see the docs: # https://docs.basebox.io/reference/broker/#configuration-file
More on the configuration options can be found in broker's reference.