Skip to content
Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

broker Reference

HTTP Endpoints

broker provides various HTTP endpoints (or paths) your client needs to call to handle authorization and GraphQL requests.

/graphql

Method: POST

Handles GraphQL requests from authenticated clients.

/oauth/login

Method: GET Query parameters: app-scheme (see below)

This is where your client starts the login process. Returns a 302 response with the URL of the OpenID Connect provider/server login form in the Location header field. If your client is not a browser, you must ensure that when calling the URL, you also pass all the URL's query parameters.

After the user submits his/her credentials to the login form, the IdP responds with a 302 redirect response to the clients OAuth2 callback; for more information, see our Authorization page.

If the user session is still valid, the IdP might not display the login form but immediately respond with a 302 response to the client's OAuth2 callback.

Note

This path is configurable in the config file; see the login_path option in the auth section below.

Query Parameters

app-scheme

Optional; name of the application scheme to get a login URL for. You can define app schemes in the config file, see auth.app_schemes below.
If omitted, the redirect_url defined in section [auth] is used.

/oauth/complete-login

Method: POST

Accepts the query parameters passed to the client server's OAuth2 callback endpoint. If everything is all right, responds with a 200 code and a JSON payload containing user session information:

{
  "token":"6aa1337f-595a-44b7-be6a-635582187bc6",
  "subject":"auth0|34950a487340750",
  "id_token_claims":{
    "aud":[
      "5wl8hQV1thh07rScSoJ3aN56ETuXWprg"
    ],
    "email":"tester@basebox.io",
    "email_verified":false,
    "name":"Tester First",
    "nickname":"tester",
    "picture":"https://s.gravatar.com/avatar/daa8da7b11eeed7e35036718ee7604e9?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fte.png",
    "sub":"auth0|34950a487340750",
    "updated_at":1683902018
  },
  "roles":[],
  "claims":{}
}

Note

The exact contents of the returned JSON object depend on the OpenID Connect provider you are using. The example above is what gets returned when using AUth0.
The token field however is always present, as this is the basebox session token; see below.

The client can now call the /graphql endpoint to send GraphQL requests. When doing so, the client must pass the session token in the Authorization header field as a bearer token:

Authorization: Beader <token>

JavaScript fetch API example:

fetch("https://basebox.tld/graphql", {
  "headers": {
    "Authorization": "Bearer 6aa1337f-595a-44b7-be6a-635582187bc6"
  }, 
  ...
});

Note

This path is configurable on the config file; see the openid_connect_path option in the auth section below.

Configuration File

The configuration file is in TOML syntax; it is very similar to good old INI files and organizes options in sections, denoted by square brackets.

Section generic

log_level

Type: String
Set broker's log level or verbosity; we recommend setting it to info. Possible values from least to most verbose are:
"error", "warn", "info", "debug", "trace"

Section graphql

schema_file

Type: String
Path and filename to your project's GraphQL schema file.

allow_introspection

Type: boolean
Set to either true or false. Turns GraphQL introspection on or off. Should be off for production!

Section server

host

Type: String
Host name or IP address of the network interface broker should listen on for requests. For production use, this should be set to the IP address of the host; use "0.0.0.0" to listen on all available interfaces and "127.0.0.1" to only accept local connections (for testing etc). If you set this to a hostname, broker will bind to the IP address returned from a DNS lookup. Example: "127.0.0.1"

port

Type: Integer
Port number; default is 80 for http, 443 for https.
Example: 8080

workers

Type: Integer
Number of HTTP server threads to spawn; default is one per CPU core.
Example: 2

tls_key_file

Type: String
Path and file name of TLS/SSL key file.
Example: "/path/to/key.pem"

tls_cert_file

Type: String
Path and file name of TLS certificate (chain) file.
Example: "/path/to/cert.pem"

max_request_size

Type: Integer
Maximum allowed HTTP request size in bytes; default is 256k.
Example: 262144

Section proxy

This section defines how the broker should connect to dbproxy.

host

Type: String
host name or IP of basebox DB proxy.
Example: "127.0.0.1"

port

Type: Integer
The TCP/IP port of dbproxy.
Example: 8081

tls

Type: Boolean
Whether to use TLS to connect to dbproxy; set to true or false.
Example: false

Section auth

jwks_file

Type: String
Path and file name to a JSON Web Key Set (JWKS) file. This file contains the public keys that broker uses to verify access token signatures. This is an alternative to specifying the discovery_url and jwks_url fields below and can be used for environments that have no access to the internet. Example: "/path/to/jwks.json"

discovery_url

Type: String
Mode: access-token
URL of IdP's discovery endpoint; only needed if jwks_url is not set. If both fields are not set, the discovery URL is made up by appending ".well-known/openid-configuration" to the iss field.

jwks_url

Type: String
Mode: access-token
URL of IdP's public keyset; optional if discovery_url is set or can be derived from the iss field

iss

Type: String
Mode: access-token
Issuer field, usually the URL of the IdP realm, e.g. https://idp.example.com/realms/testing

aud

Type: String
Mode: access-token
Access token audience field

Section auth_management

provider

Type: String
Name of the authentication provider to use for authentication management. Currently, only auth0 is supported.

domain

Type: String
Domain of your Auth0 realm; example: "your-tenant.auth0.com"

client_id

Type: String
Client ID of the machine-to-machine client that is allowed to get access tokens for the Management API.
https://auth0.com/docs/secure/tokens/access-tokens/get-management-api-access-tokens-for-production

client_secret

Type: String
Client secret of the machine-to-machine client that is allowed to get access tokens for the Management API.
https://auth0.com/docs/secure/tokens/access-tokens/get-management-api-access-tokens-for-production