Licensed to be used in conjunction with basebox, only.
broker
broker is basebox' GraphQL HTTP(s) server. Your client sends GraphQL requests to the broker's /graphql endpoint, e.g. https://broker.host.com/graphql.
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 --help:
❯ ./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.