Clarify authentication and token management

[nflaig]

Based on the discussion on discord, clarifies authentication (token format) and adds a few more notes on how the token should be managed by the binary (validator client / remote signer).

These are just the basic requirements a client should support, and ideally be backward compatible for all clients and not break existing tooling (e.g dappnode). The goal is to make it clearer for consumers on what to expect and improve client interoperability.

Additional protections can be implemented based on client specific requirements such as application layer HTTPS or a more secure approach to store the token on the file system.

Related

• Authentication #9
• Consensus-layer Call 129 pm#973 (comment)

[dapplion]

I would omit the stdout part, focus on the file parameter and follow jwt-secret spec:

Suggested change

	- Log the token file path to stdout when running the binary with the key manager API enabled
	- Read the token from a file available to the binary, the path to the token file should be configurable
	- If the token file does not exist or is empty, generate a new token and write it to the file
	- The token should remain the same across multiple restarts of the binary
	The keymanager binary SHOULD accept a configuration parameter: `keymanager-secret`, which designates a file containing the hex-encoded token of at least 256 bits. If such a parameter is not given, the client SHOULD generate such a token, valid for the duration of the execution. If such a parameter is given, but the file or token cannot be read, the client SHOULD treat this as an error: either abort the startup, or show error and continue without exposing the keymanager routes.

[nflaig]

keymanager-secret

What about keymanager-token? this would make it clearer that it's the actual token and not a signing key

If such a parameter is not given, the client SHOULD generate such a token, valid for the duration of the execution

Does this mean if the token is not explicitly set by the user it should be regenerated on every restart? or what is meant by "duration of the execution"?

I think we want to make sure that the token remains the same across multiple process restarts, unless a user explicitly regenerates it by deleting the token file.

[james-prysm]

is there a better name? one of the regrets was to call this the keymanager apis in the first place... maybe it can be simplified to just token or api-token?

[nflaig]

maybe it can be simplified to just token or api-token?

Not many clients follow the flag name in the engine auth spec either, I don't mind using just token as the flag name here and each client can use their preferred name in the end.

I don't think there is much value in standardizing the name as there are already plenty of flags that are different across clients, so you will have to look at the CLI reference docs either way. The more important part is to have consistent behavior.

[rolfyone]

I'm not against changing our api flags but do we really need to be so prescriptive about the exact flag to use?

The key points are

• ssl by default, especially non localhost interactions
• must be authenticated due to the nature of the interactions by default
• any supplied token should be able to be set by command line argument (reference to existing file).
  • reporting the location that the key is read from would help users and should be considered.
• some kind of ability to disable ssl purely for devops and testing would be ideal.

For teku at least, our file is just loaded and used as the token value, we've no extra data in that file we're referencing... one of the reasons I think i'd prefer not being prescriptive on the actual flag name is that its possible people have conflicting standards and it might be difficult to find something that satisfies existing standards (as well as potential breaking changes for people needing to rename flags).

[dapplion]

@rolfyone we can just have a recommendation of MUST have a flag, and SHOULD be named api-token

[james-prysm]

or token-file realized it might be confusing that it's a path to a file and not providing the token itself

[nflaig]

or token-file realized it might be confusing that it's a path to a file and not providing the token itself

depends on if we wanna use similar naming convention as jwt-secret, generally speaking token-file is definitely less ambiguous

[barnabasbusa]

--keymanager-token-file is already implemented by nimbus, and is a very descriptive flag imo.

[rolfyone]

teku's is --validator-api-bearer-file if that works? could potentially alias it if it makes life easier in a future release...

[james-prysm]

should we add a new endpoint that shows the token location like what lighthouse did? https://lighthouse-book.sigmaprime.io/api-vc-endpoints.html#get-lighthouseauth

[nflaig]

should we add a new endpoint that shows the token location like what lighthouse did? https://lighthouse-book.sigmaprime.io/api-vc-endpoints.html#get-lighthouseauth

It was brought up in #9 as well but what's the expected use case for this?

[james-prysm]

should we add a new endpoint that shows the token location like what lighthouse did? https://lighthouse-book.sigmaprime.io/api-vc-endpoints.html#get-lighthouseauth

It was brought up in #9 as well but what's the expected use case for this?

we just print it in the logs, if it's auto generated there's usually a default path, it might be useful for someone to want to get that value if they lose it. that's mostly it i think?

[nflaig]

we just print it in the logs, if it's auto generated there's usually a default path, it might be useful for someone to want to get that value if they lose it. that's mostly it i think?

Having a hard time seeing anyone using this, especially since all clients should have a configuration parameter now to set the file path. Could add this later if there is demand for it.