go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/tokenserver/README.md (about)

     1  # The Token Server
     2  
     3  This directory contains an implementation of a service that generates and
     4  validates various tokens used in LUCI authentication protocol.
     5  
     6  In particular, this service implements so called "machine tokens" used for
     7  authenticating Swarming bots:
     8  
     9  1.  Each bot has a TLS private key and a certificate, signed by some trusted CA.
    10  1.  `luci_machine_tokend` executable periodically runs and uses the private key
    11      and certificate when calling `MintMachineToken` gRPC method of the token
    12      server.
    13  1.  The server verifies that the certificate is signed by a trusted CA, that it
    14      is not expired or revoked, and that the request was signed by the
    15      corresponding private key. If everything checks out, the server generates
    16      a short lived (1h by default) stateless machine token (basically,
    17      certificate Common Name and some additional data signed by the token
    18      server's own private key).
    19  1.  The bot uses this token when sending requests to Swarming (by putting it
    20      into `X-Luci-Machine-Token` header).
    21  1.  Swarming checks the signature of the token (using only local crypto) when
    22      authenticating requests from bots.
    23  
    24  
    25  ## Layout
    26  
    27  *   `api`: gRPC protocol definition and autogenerated Go code.
    28  *   `appengine`: server implementation (runs on Standard GAE).
    29  *   `auth/machine`: implementation of the token checking logic that can be used
    30      by backends that want to use machine tokens. Swarming service uses same
    31      logic (implemented in Python).
    32  *   `client`: library that wraps `TokenMinter` gRPC API into a usable form. It
    33      implements logic for reading and using TLS certificate and private keys.
    34  *   `cmd/luci_machine_tokend`: executable deployed on all bots. It knows how to
    35      generate machine tokens given a TLS certificate and private key.
    36  *   `testing`: local integration test that checks interaction of
    37      `luci_machine_tokend` with the server (and some other things, such as
    38      certificate revocation list updates).