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 of 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.

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
cert_key_file: Type: String
Path and file name of TLS/SSL key file.
Example: "/path/to/key.pem"
cert_file: Type: String
Path and file name of TLS certificate (chain) file.
Example: "/path/to/cert.pem"

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`

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
client_id: Type: String
Mode: client
OAuth2/OpenID Connect client ID. You assign this id to your basebox project in your OpenID Connect providing system (e.g. Keycloak) when registering your application (i.e. "client").
Example: "bbtest"
client_secret: Type: String
Mode: client
OAuth2/OpenID Connect client secret; your OpenID Connect server assigns a client secret to your client when you register it.
Example: "TvdBt0CXNWG5Lq8mlh8sDFk0l4wWrl4q"
idp_url: Type: String
Mode: client
Base URL to the identity provider (OAuth2/OpenID Connect server, e.g. Keycloak).
For Keycloak, this is e.g. https://keycloak.basebox.io:8443/realms/your-realm; for Auth0, use the Domain field in your Auth0 application's settings with a leading 'https://'
scope: Type: String
Mode: client
Space separated list of OpenID Connect scopes to query during login; default is "openid profile email"; the value "openid" must be present.
Default: "openid profile email"
redirect_url: Type: String
Mode: client
Fully qualified URL to the OAuth2 callback endpoint on the client server.
After the user entered his/her credentials at the IdP's login form, the client will be redirected to this URL. The HTTP server that hosts the client must handle this URL; when it receives this request, it must POST the request's query string to the broker's "openid_connect_path" set below.
Note that you have to explicitly allow the redirect URL in your authentication provider settings.
If you need to support multiple redirect URLs, plaese have a look at application schemes. Example: "https://client-app.tld/oauth/callback"
openid_connect_path: Type: String
Mode: client
OpenID Connect login completion request path.
The client must pass the query string from the call to "redirect_url" to this URL and gets a basebox session token in return. Example: "/oauth/complete-login"
login_path: Type: String
Mode: client
Path to the browser login URL.
This path is where the basebox broker returns a 302 response that redirects the browser to the IdP login page; the target URL will contain all query parms needed to initiate an auth code flow login procedure, incl. CSRF protection tokens etc. Example: "/oauth/login"
logout_path: Type: String
Mode: client
Logout path that allows explicit, immediate logouts.
Example: "/oauth/logout"
user_info_additional_claims_required: Type: boolean
Mode: client
Set to true to get a user's additional claims from OAuth2
Example: true

Last update: 2023-11-06

broker Reference

HTTP Endpoints

/graphql

/oauth/login

Query Parameters

/oauth/complete-login

Configuration File

Section generic

Section graphql

Section server

Section proxy

Section auth

Section `generic`

Section `graphql`

Section `server`

Section `proxy`

Section `auth`