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 key.pub) 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 key.pub

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"
services:
  carbone:
    image: carbone-ee:4.20.0
    platform: linux/amd64
    ports:
      - "4000:4000"
    secrets:
      - source: carbone-license
        target: /app/config/license.carbone-license
      - source: carbone-publickey
        target: /app/config/key.pub
    environment:
      - CARBONE_EE_STUDIO=true
      - CARBONE_EE_AUTHENTICATION=true
      - CARBONE_EE_STUDIOUSER=user:passw0rd
secrets:
  carbone-license:
    file: license.carbone-license
  carbone-publickey:
    file: key.pub

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"
}

Payload

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

Numerous solutions exist, but we suggest you use https://github.com/smallstep/cli

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