You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

Node pairing

Node pairing is the process of establishing a federated network between two Corteza instances (nodes).

Node pairing consists of node identification which identifies the two nodes — enables communication; and node handshake which exchanges authentication credentials for secure communication.

The diagram outlines the entire node pairing process. This is later broken down into node identification and node handshake and described in detail.
Figure 1. The diagram outlines the entire node pairing process. This is later broken down into node identification and node handshake and described in detail.

Node identification

The node identification step exchanges information about the nodes required to establish a connection (URL address, node name, and some other metadata).

The node identification step doesn’t exchange any authentication tokens apart from the OTT token.
The diagram outlines the node identification step which exchanges the information that are required to establish a connection.
Figure 2. The diagram outlines the node identification step which exchanges the information that are required to establish a connection.
Node A administrator registers node B and generates a node URI

Node registration step lets node A know about node B. The generated node URI identifies node A and looks like this: corteza://$NODE_ID_A:$OTT@$DOMAIN_A?name=$NAME.

$OTT lets us perform initial authentication when performing the handshake below.
Node A administrator sends the node URI to the node B administrator

The transferred node URI lets node B administrator quickly register node A.

This step is performed manually by the node administrators. The two administrators should use a secure channel to exchange this information.
Node B administrator registers node A using the node URI

Node registration step lets node B know about node A. Both nodes have been identified and are prepared to perform the node handshake.

Node handshake

The node handshake step configures the nodes and exchanges authentication tokens that the nodes use to access protected resources.

Corteza Federation leverages Corteza’s already established authentication facility, using system users and JWT tokens (later referred as a token).

This enables us to reduce potential security holes and leverage our RBAC access control facility.

All authentication tokens are unique, even the ones in the same node pair.
The diagram outlines the node handshake step which exchanges the authentication tokens used to access protected resources.
Figure 3. The diagram outlines the node handshake step which exchanges the authentication tokens used to access protected resources.
Node B administrator initializes the handshake with node A

Node B initializes the state and generates a $TOKEN_B that can be used by node A when accessing protected resources.

Node B sends a handshake request to node A

Node A administrator is notified (via email) that node B wishes to establish a federated network. The handshake request must be manually confirmed by the node A administrator.

This request is authenticated by the $OTT token (generated in the node identification step), outside of the standard authentication facility.

The actual authentication tokens authenticate all following requests.
Node A administrator confirms the handshake request

Node A initializes the state and generates a $TOKEN_A that can be used by node B when accessing protected resources.

Node A completes the handshake step

Node A sends the generated $TOKEN_A to node B with a confirmation that the handshake was successful.