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.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

== Node identification ==
AdministratorA->NodeA: Register federated node B.
AdministratorA-->AdministratorB: Send node URI.
note right of AdministratorA
Administrator A sends the node URI
to administrator B via a secure channel.
end note
...
AdministratorB->NodeB: Register federated node A.
note left of AdministratorB
Administrator B registers node A
using the node URI.
end note


== Node handshake ==
AdministratorB->NodeB: Initialize the handshake.
note over NodeB #FFAAAA
Initialize node B for the federated network.
Create a system user, generate authentication
token, and configure the system.
end note

NodeB->NodeA: Request the handshake.
NodeA-->AdministratorA: Notify administrator A.
note right of AdministratorA #ffffff
Administrator A must manually
approve the handshake request.
end note
...
AdministratorA->NodeA: Approve the handshake request.
note over NodeA #FFAAAA
Initialize node A for the federated network.
Create a system user, generate authentication
token, and configure the system.
end note
NodeA->NodeB: Complete the handshake.
@enduml

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.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

AdministratorA->NodeA: Register federated node B.
AdministratorA-->AdministratorB: Send node URI.
note right of AdministratorA
Administrator A sends the node URI
to administrator B via a secure channel.
end note
...
AdministratorB->NodeB: Register federated node A.
note left of AdministratorB
Administrator B registers node A
using the node URI.
end note
@enduml

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.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

AdministratorB->NodeB: Initialize the handshake.
note over NodeB #FFAAAA
Initialize node B for the federated network.
Create a system user, generate authentication
token, and configure the system.
end note

NodeB->NodeA: Request the handshake.
NodeA-->AdministratorA: Notify administrator A.
note right of AdministratorA #ffffff
Administrator A must manually
approve the handshake request.
end note
...
AdministratorA->NodeA: Approve the handshake request.
note over NodeA #FFAAAA
Initialize node A for the federated network.
Create a system user, generate authentication
token, and configure the system.
end note
NodeA->NodeB: Complete the handshake.
@enduml

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.