Articles on: Tutorials

Configure authentification with Carbone docker image

How to enable authentication with Carbone docker

By default, Carbone docker image is running without authentication.

Please follow the steps below:

Enable authentication options in Carbone

You first need to set environment variable CARBONE_EE_AUTHENTICATION to true.
If you use Studio (CARBONE_EE_STUDIO=true), don't forget to also enable security on it with : CARBONE_EE_STUDIOUSER=user:password

Carbone key generation

When running Carbone for the first time, if no keys are present, Carbone automatically generate a key pair (key.pem and in /app/config/.

To simplify migration and architecture issues, we strongly recommend that you generate your own keys and make them available to Carbone.

To do this, you must first generate a private key with the following command:
openssl ecparam -genkey -name secp521r1 -noout -out key.pem

Then the corresponding public key :
openssl ec -in key.pem -pubout -out

Launching Carbone with your key

As with license provisioning, we recommend using a docker secret to map the public key to the container's config directory.

Here's an example using docker compose (file docker-compose.yml) :
version: "3.9"
    image: carbone-ee:4.20.0
    platform: linux/amd64
      - "4000:4000"
      - source: carbone-license
        target: /app/config/license.carbone-license
      - source: carbone-publickey
        target: /app/config/
      - CARBONE_EE_STUDIO=true
      - CARBONE_EE_STUDIOUSER=user:passw0rd
    file: license.carbone-license

Generating JWT tokens for API use

Carbone uses standard ES512 JWT tokens.

You must then generate a token and sign it with your private key.

The JWT token must contain the following information.
Header :
    "alg" : "ES512",
    "typ" : "JWT"

    'iss' : 'carbone-user',
    'aud' : 'carbone-ee', 
    'exp' : xxxxx // timestamp en sec

Numerous solutions exist, but we suggest you use

After installation, you just need to run the following command to generate one JWT token :
current_time=$(date +%s)
expiration_time=$(($current_time + 864000)) # Ten days from now for ex

step crypto jwt sign --alg ES512 --iss=carbone-user --subtle --aud=carbone-ee --exp=$expiration_time --key=key.pem

Et voilà !

Updated on: 03/19/2024

Was this article helpful?

Share your feedback


Thank you!