github.com/google/fleetspeak@v0.1.15-0.20240426164851-4f31f62c1aea/sandboxes/https-header-mode/README.md (about)

     1  # HTTPS Header Mode
     2  
     3  ## Introduction
     4  
     5  This sandbox demonstrates how to run Fleetspeak in 'https header mode'.
     6  
     7  The Fleetspeak frontend (the server) is using the Fleetspeak client's
     8  certficiate to identify it by deriving the client id from the certficiate.
     9  
    10  In cases where the mTLS connection is terminated on a load balancer between the
    11  Fleetspeak client and the Fleetspeak server the client certificate has to be
    12  forwarded by other means.
    13  
    14  This sandbox demonstrates how this can be achieved by adding the certificate
    15  into an additional header (the `client_certificate_header` in the diagram
    16  below).
    17  
    18  Furthermore, this sandbox also demonstrates how the client certificate checksum
    19  (the `client_certificate_checksum_header` in the diagram below) that some load
    20  balancers provide can be used to verify that the certificate received in the
    21  additional header is the same that the load balancer received during the mTLS
    22  exchange. \
    23  Additional information on how the checksum is derived from the certificate can
    24  be
    25  [found here](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-17#section-3.1).
    26  
    27  ![HTTPS Header Mode](../diagrams/httpsHeaderMode_355.png "HTTPS Header Mode")
    28  
    29  ## Setup
    30  
    31  Before you run the commands below make sure that you successfully executed the
    32  steps outlined in the [setup instructions](../../sandboxes#setup-instructions).
    33  
    34  ## Bring up the test environment
    35  
    36  ```
    37  docker compose up --build -d
    38  
    39  [+] Running 5/5
    40   ✔ Network https-header-mode_default                Created                                                                                                          0.1s
    41   ✔ Container https-header-mode-mysql-server-1       Healthy                                                                                                          0.1s
    42   ✔ Container https-header-mode-front-envoy-1        Started                                                                                                          0.1s
    43   ✔ Container https-header-mode-fleetspeak-server-1  Healthy                                                                                                          0.0s
    44   ✔ Container https-header-mode-fleetspeak-client-1  Started                                                                                                          0.0s
    45  ```
    46  
    47  ## Find the client id
    48  
    49  ```
    50  docker logs https-header-mode-fleetspeak-client-1
    51  # The output should look similar to the below
    52  
    53  # config.go:44] Read 1 trusted certificates.
    54  # manager.go:103] initial load of writeback failed (continuing): open /fleetspeak-client.state: no such file or directory
    55  # manager.go:165] Using new client id: **33d0e02455c7be1b**
    56  # client.go:175] No signed service configs could be read; continuing: invalid signed services directory path: unable to stat path [/config/fleetspeak-client/services]: stat /config/fleetspeak-client/services: no such file or directory
    57  # services.go:146] Started service hello with config:
    58  #   name:"hello"  factory:"Daemon"  config:{[type.googleapis.com/fleetspeak.daemonservice.Config]:{argv:"/venv/FSENV/bin/python"  argv:"/config/hello.py"}}
    59  # system_service.go:251] Unable to get revoked certificate list: unable to retrieve file, last attempt failed with: failed with http response code: 404
    60  
    61  # Run the test app container
    62  docker run -it --name greeter --network https-header-mode_default -p 1337:1337 --rm greeter bash
    63  ```
    64  
    65  ## Run the test app
    66  
    67  ```
    68  # In the above find the client id and export it in a variable
    69  export CLIENT_ID=**33d0e02455c7be1b**
    70  
    71  # Start the test app, when it runs add your input and hit enter. You should see the string being ecohed.
    72  /venv/FSENV/bin/python ./greeter.py --client_id=$CLIENT_ID --fleetspeak_message_listen_address="0.0.0.0:1337" \
    73      --fleetspeak_server="fleetspeak-server:9091" --alsologtostderr
    74  
    75  ```
    76  
    77  ## Bring down the test environment
    78  
    79  ```
    80  docker compose down
    81  ```