nvflare.private.fed.authenticator module

class Authenticator(cell: Cell, project_name: str, client_name: str, client_type: str, expected_sp_identity: str, secure_mode: bool, root_cert_file: str, private_key_file: str, cert_file: str, msg_timeout: float, retry_interval: float, timeout=None, site_config=None)

Bases: object

Authenticator is to be used to register a client to the Server.

Parameters:

• cell – the communication cell

• project_name – name of the project

• client_name – name of the client

• client_type – type of the client: regular or relay

• expected_sp_identity – identity of the service provider (i.e. server)

• secure_mode – whether the project is in secure training mode

• root_cert_file – file path of the root cert

• private_key_file – file path of the private key

• cert_file – file path of the client’s certificate

• msg_timeout – timeout for authentication messages

• retry_interval – interval between tries

• timeout – overall timeout for the authentication.

• site_config – optional validated site config to report to the server during registration.

authenticate(shared_fl_ctx: FLContext, abort_signal: Signal)

Register the client with the FLARE Server.

Note that the client no longer needs to be directly connected with the Server!

Since the client may be connected with the Server indirectly (e.g. via bridge nodes or proxy), in the secure mode, the client authentication cannot be based on the connection’s TLS cert. Instead, the server and the client will explicitly authenticate each other using their provisioned PKI credentials, as follows:

1. Make sure that the Server is authentic. The client sends a Challenge request with a random nonce. The server is expected to return the following in its reply:

• its cert and common name (Server_CN)

• signature on the received client nonce + Server_CN

• a random Server Nonce. This will be used for the server to validate the client’s identity in the

Registration request.

The client then validates to make sure:

• the Server_CN is the same as presented in the server cert

• the Server_CN is the same as configured in the client’s config (fed_client.json)

• the signature is valid

2. Client sends Registration request that contains:

   • client cert and common name (Client_CN)

   • signature on the received Server Nonce + Client_CN

The Server then validates to make sure:

• the Client_CN is the same as presented in the client cert

• the signature is valid

NOTE: we do not explicitly validate certs’ expiration time. This is because currently the same certs are also used for SSL connections, which already validate expiration.

Parameters:

• shared_fl_ctx – the FLContext content to be shared with peer

• abort_signal – signal to notify abort

Returns: A tuple of (token, token_signature, ssid, token_verifier)

validate_auth_headers(message: Message, token_verifier: TokenVerifier, logger, client_fqcn_resolver: Callable[[str, str], str | None] | None = None)

Validate auth headers from messages that go through the server.

Parameters:

• message – the message to validate

• token_verifier – the TokenVerifier to be used to verify the token and signature

• client_fqcn_resolver – optional resolver used to bind a client token to its registered CellNet origin. Return None only when the token/name cannot be resolved; return MISSING_CLIENT_FQCN for a registered client with no stored origin so validation fails closed.

Returns: