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

basebox Authorization and Authentication

See also our Getting Started section for Auth0 and Keycloak.

Overview

Needless to say, security is one of basebox' top concerns. Therefore, basebox uses a secure standard for authorization named OpenID Connect. OpenID Connect is an extension to OAuth2, providing authentication on top of OAuth2's authorization.

OpenID Connect Primer

OpenID Connect is not a product, but a standard or protocol. There are various implementations for OpenID Connect; basebox supports two of the most common, which are Keycloak (an Open Source server software you host on your own) and Auth0 (a commercial service or SaaS). Other implementations probably work as well, but we have not tested them.

Note

If you don't know OpenID Connect, we recommend you read OpenID Connect Protocol by Auth0; there are countless other resources on the web, but this one is a good start.

OpenID Connect and basebox

In a nutshell, your client app needs to pass an OpenID Connect access token to the broker with each request to the GraphQL endpoint. You do so by adding the access token to the HTTP Authorization header field, preceded with the "Bearer" keyword, e.g.

Authorization: Bearer <access token base64 encoded string>

The access token is issued by an OpenID Connect provider (IdP) and contains information about the user and the client. The IdP is a separate component in your project, e.g. Keycloak or Auth0. The IdP is responsible for authenticating the user and issuing the access token.

How to get an Access Token

This depends on your client application. If you are using a web browser, you will probably use the Authorization Code Flow to get an access token. If you are using a mobile app, you will probably use the Authorization Code Flow with Proof Key for Code Exchange (PKCE). If you are using a server-side app, you will probably use the Client Credentials Flow.

Note

There are various ways ("flows" in OpenID Connect terms) to authenticate with OpenID Connect. Please note that the so called Implicit Flow is deprecated and should not be used anymore.

For an example how a web client could do authentication and obtain an access token, have a look at our Vue based client application, e.g. here.

References

There are many resources on the web describing API authentication using OpenID Connect; some are good, and some just plain wrong. It is easy to get lost. This is a list of sites about the topic we found helpful and correct: