Securing communication between participants

Owned by Martin Valldeby (Unlicensed)
Last updated: 2022-08-23 by Tobias Hägglund
3 min read

Securing communication between participants - Authentication keys

All requests to BoB APIs (except the Participant Metadata API and Authentication API that have other types of authentication) must include a X-BoB-AuthToken header containing the JWT (auth token). For extra security, the JWT should contain the Holder of Key claim (bobHok) which is the fingerprint of the TLS client certificate used in the communication.

Setup - Authentication keys and BoB Authentication Service

In order for a participant to be able to access BoB services the participant needs to implement it's own authentication service as well as creating an auth token key pair and publish the public part of that key pair to the participant metadata service. The steps included when setting up the authentication service for use is described here:

  1. A participant that wants to call a BoB service other than participant metadata service will have to implement it's own authentication service.
    The authentication service shall have an API that fullfills the specification defined by the BoB Authentication API.
    The role of the authentication service is to create JSON Web Tokens (JWT) that shall be included in the X-BoB-AuthToken header and validated for each request to other BoB services .
  2. The communication with the authentication service must be perfomed using a client certificate. Such a certificate has to be set up by Participant-1 for any internal client that is a trusted client allowed to requesting a JWT from the authentication service. For more information please see  BoB Authentication API.
  3. Auth token key pair will have to be created by Participant-1.
    The private part of the key pair, in this example called P1-authtoken-private-key, will be used by the authentication service when creating JWTs. The public part of the key pair, in this example called P1-authtoken-public-key, will be used by other participants when authenticating Participant-1 access to BoB services.
  4. Set up the  P1-authtoken-private-key for use by Participant-1's authentication service
  5. Store the P1-authtoken-public-key in Participant Metadata Service by calling the authTokenPublicKey operation of that service using method POST. The processes for managing Participant Meta Data is descibed in Management of own Participant metadata section above.
  6. Response of the POST authTokenPublic is returned to Participant-1.

Mechanism - Use of Authentication keys and JWT

In communication among BoB-participants the authentication keys described in the previous section will be used for the security mechanism to work. The mechanism is described in the following example where Participant-1 calls a BoB service hosted by another participant, Participant-2.

  1. This sequence starts with a call from the "Participant-1 BoB client" to the "Participant-1 authentication service".
    The reason for that is that a JWT has to be created so that it can be included in the X-BoB-AuthToken header when the "Participant-1 BoB client" calls the "Participant-2 BoB service".
    The call from Participant-1 to the authentication service is made using a TLS-client certificate.
  2. The authentication service recievs the call This call requires a TLS client certificate and the authentication service will 
    1. Retrieve the finger print of the TLS client certificate
    2. Create JWT (JSON Web Token) including the mandatory and optional attribues as described in API Authentication and Authorization. This includes logging as well as setting the TLS client certificate fingerprint as value of attribute bobHok if applicable. When creating the JWT the private key of the auth token key pair, called P1-authtoken-private-key in the example above, is used. 
  3. The JWT is returned to the client
  4. The JWT is added to the X-BoB-AuthToken header of the request
  5. The request is sent från BoB client to BoB service. If bobHok was created in step 2 this call requires a TLS client certificate.
  6. The request is terminated by proxy, if there is a client certificate that is valid, a SHA1 fingerprint of that certificate is added to http header
  7. Response returned
  8. Response to client