Licensed to be used in conjunction with basebox, only.
Setting up Auth0 for basebox
See also our Authorization Guide.
About Auth0
Auth0 is a commercial OpenID Connect authentication provider that is officially supported by basebox. They have a free plan that you can use to get started.
You can also use Keycloak, but this is a bit more involved because you have to host it yourself or run it in a Docker container.
Auth0 Setup Steps
After registering at Auth0, you have to create a so called application to be used with your basebox project.
- Log into your Auth0 account
- If not already done, create a new Tenant, i.e. an authorization domain. A tenant in Auth0 terms is region-specific and can "host" multiple applications. You cannot create an application without a tenant.
- In the left menu, click Applications -> Applications; you should see a list of existing applications (if there are any). Click +Create Application in the rop right corner
- Pick a name and select the most appropriate application type; in this example, we select Single Page Web Application
- You will now be taken to the Quickstart tab that helps you in configuring/programming your client to authenticate at Auth0; we skip that for now. Instead, click the Settings tab.
Auth0 Application Settings
The settings tab contains important data that you need to configure your client application to be able to log your users in as well as data that is needed by basebox to validate authentication tokens.
Client Side Implementation
It is beyond the scope of this guide to explain how to implement OpenID Connect based authentication in your client, and we cannot cover all client technologies out there; but for a starter, you can look at our Vue based sample todo app and how it handles authentication using oidc-client-ts.
Configure basebox
Both broker and dbproxy have a config file that needs to contain information about the authentication tenant and application in a section named [auth]. The 2 fields you have to set are:
iss
This is the content of the *Domain* field in the settings tab; it usually has the form `<tenant-name>.<region-code>.auth0.com`, prefixed with `https://`
aud
In the left menu column, click on *Settings*; this takes you to the *Tenant Settings* page. Scroll down to the *API Authorization Settings* block and copy/edit the *Default Audience* field.
Example Config
[auth] section in both broker's and dbproxy's config file: