Sormas2Sormas (or S2S for short) is a feature that allows sharing of entities (e.g., cases, contacts, events, etc.) between two or more SORMAS instances.
A SORMAS instance is a running instance of the SORMAS application. A SORMAS instance which is configured to participate
in S2S is obviously the main component of the Sormas2Sormas feature. It is the one that initiates the sharing process
and the one that receives the shared entities. Each instance has a unique S2S identifier which is an arbitrary string.
We do not enforce a certain scheme, but it is strongly encouraged to use a meaningful and consistent identifiers
(e.g., 2.sormas.id.sormas_a in Germany which is the dedicated SurvNet ID for the public health office).
A server descriptor is a struct which contains the information needed to connect to a SORMAS instance (see the
SormasServerDescriptor class). It consists of the S2S ID, a human-readable name used in the UI, and the hostname.
Descriptors centrally distributed via a dedicated etcd keyspace (e.g., /s2s/).
{
"id":"2.sormas.id.sormas_a",
"name":"sormas_a_org_name",
"hostName":"sormas_a:6080"
}Each instance receives a dedicated x509 certificate and private key pair which is used to encrypt all S2S communication.
The certificate is signed by a common S2S CA. The certificate and private key are stored in a pkcs12 keystore under the
S2S ID of the instance. See here
for an example of how to generate a keystore.
Each instance receives a truststore which contains the S2S CA certificate under the sormas2sormas.rootCaAlias.
See here for an example of
how to generate a truststore.
The following properties are required to be set in the sormas.properties file:
| Property | Description |
|---|---|
central.oidc.url |
URL of the OIDC server authenticating instances and authorizing S2S requests. |
central.etcd.host= |
The hostname of the etcd instance providing data like server descriptors. |
central.etcd.clientName |
The client name of the instance used in authentication towards etcd. |
central.etcd.clientPassword |
The client password of the instance used in authentication towards etcd. |
central.etcd.caPath |
The full filesystem path to the CA trusted by etcd clients when creating a TLS connection to the etcd server. |
central.location.sync |
If set to true, all infrastructure data from the central server will be synchronized into the local SORMAS database at (re)start and on a daily basis. |
sormas2sormas.path |
Filesystem path to a directory where certificates and files related to SORMAS2SORMAS are stored. |
sormas2sormas.id= |
The S2S ID of this instance. The identifier can be arbitrary, but should be meaningful. |
sormas2sormas.keystoreName |
Name of the key store file relative to sormas2sormas.path. |
sormas2sormas.keystorePass |
Password of the key store file. |
sormas2sormas.rootCaAlias |
The alias of the trusted root CA which secures the S2S communication. This is NOT used for TLS. |
sormas2sormas.truststoreName |
Name of the truststore file relative to sormas2sormas.path. |
sormas2sormas.truststorePass |
Password of the truststore. |
sormas2sormas.oidc.realm |
Name of our S2S authorization realm provided by the OIDC server. |
sormas2sormas.oidc.clientId |
The client ID used in authentication of the instance towards the OIDC server. |
sormas2sormas.oidc.clientSecret |
The client secret used in authorization of the instance towards the OIDC server. |
sormas2sormas.etcd.keyPrefix |
The etcd key space prefix which is used to store s2s related information. |
sormas2sormas.ignoreProperty.additionalDetails |
Controls whether the value in additionalDetails field should be sent or not to the other instances. Possible values: true/false(default). |
sormas2sormas.ignoreProperty.externalId |
Controls whether the value in externalId field should be sent or not to the other instances. Possible values: true/false(default). |
sormas2sormas.ignoreProperty.externalToken |
Controls whether the value in externalToken field should be sent or not to the other instances. Possible values: true/false(default). |
sormas2sormas.ignoreProperty.internalToken |
Controls whether the value in internalToken field should be sent or not to the other instances. Possible values: true/false(default). |
#sormas2sormas.districtExternalId |
External ID of the district to which the cases/contacts to be assigned when accepting a share request |
Keycloak is an open source identity and access management solution. It is used to manage the users and their permissions. In our case, we use the OIDC client credentials flow to authenticate the S2S enabled instances and to authorize the S2S share operations. It consists of a dedicated S2S realm which contains all the necessary configurations, namely dedicated clients and client scopes. Connections to Keycloak must be protected by TLS.
Each S2S instance receives a dedicated client in the S2S realm. An S2S instance is acting as client and is configured to use the OIDC client credentials.
For each client, a similar client scope is created. Each S2S instance A which should be able to send data to another
instance B must be assigned the client scope of instance B. This way, instance A is allowed to send data to instance B.
The client scope must be prefixed with s2s- and must contain the S2S ID of the instance it is assigned to (e.g.,
s2s-2.sormas.id.sormas_b).
etcd is a distributed key-value store. It is used to store the server descriptors of all S2S enabled instances. They are
all stored under a dedicated S2S key space prefix (e.g., /s2s/) at a path like /s2s/2.sormas.id.sormas_b.
The etcd server is expected to be secured by TLS with a trusted CA announced to instances via central.etcd.caPath.
The etcd client name and password are used to authenticate the S2S instances towards the etcd server.
etcd is also used to store the infrastructure data of the central server. This data is used to synchronize the local DB
to have a consistent view of the infrastructure data. The infrastructure data is stored under a dedicated key space of
the form /central/location/${entity} where entity is one of continent, subcontinent, country, region, district,
and community. A complete key could look like /central/location/continent/3fab2b69-31cd-5765-91e3-d68826a6dd48 where
the uuid is the uuid assigned to the continent in the central server. The values are expected to mirror the JSON values
of the DTOs (e.g., ContinentDto, etc.).
The S2S communication is expected to be secured by TLS. For additional security, the S2S communication is also
encrypted. Each instance receives a dedicated keystore and truststore. The keystore contains the instance's private and
public key. The truststore contains a root CA certificate (i.e., sormas2sormas.rootCaAlias) which is used to sign all
instance certificates. The connection to Keycloak must be secured by TLS. The connection to etcd must be secured by
TLS. The CA trusted by etcd clients when creating a TLS connection to the server is set via central.etcd.caPath.
- Stop the instance and create backup
- The instance on which S2S will be deactivated has to revoke all outgoing pending requests AND has to accept or reject all incoming pending request. Please note that as of now, users won't be able to see the whole sharebox or share directory. Therefore, they cannot track if the case/contact was shared with/by another instance or not.
- Deactivate the S2S feature by commenting all relevant properties in
sormas.properties:sormas2sormas.*central.oidc.url- Optional if GA wants to disable central infra sync:
central.*. Strongly discouraged.
- Remove service descriptor of the deactivated instance from central
etcdto prevent further discovery. - Reset feature configuration table.
- Remove client and client scope of the instance from central Keycloak.
shredthe instance's key material.- Restart the instance.