Inbound Connections - API mutual authentication (mTLS)


Roche Diabetes Care APIs are secured with mutual TLS for identifying both parties and for securing communication between systems. Roche validates the identity of the client (middleware) and middleware verifies the identity of the server (Roche).


EMR-patient-create

Introduction

In the typical one-way TLS Authentication, the client verifies the identity of the server. In Mutual TLS Authentication (mTLS), also known as two-way TLS, the server also validates the identity of the client so that they can trust each other.

Mutual TLS Authentication

The Server must authenticate itself to the Client and the Client must authenticate itself to the Server. Both Client and Server present and validate each other’s certificates as part of the handshake in SSL/TLS protocol. Client and Server start with the handshake before the actual API messages are sent / received.


API Access

Pre-conditions:

Roche Diabetes Care needs to provide the following information:

  • Organization ID: Public identifier of the organization that is consuming FHIR API. If this ID is not available, Roche will provide one.

  • Client ID / Secret: Client ID is a public identifier generated by Roche identifying the organization. Client Secret is a secret known only to the application and Roche ecosystem. This key pair will be provided by Roche.

  • Client Certificate for mutual Authentication: Client certificate for the trusted middleware that is acting on behalf of an Organization. This client certificate will be generated by Roche once the Certificate Request *.csr file is provided by the client.

EMR middleware needs to provide the following information:

  • Client IP: Public client IP of EMR Middleware.

  • Client Certificate Signing Request: Client Certificate Signing Request in order to create the Client certificate issued by Roche CA.

Client Certificate generation and configuration

Roche DC has its own Certificate Authority and it is responsible for generating the client certificates when Certificate Request is provided by the client. The certificates are generated as 2048-bit RSA key pair and SHA-256.

The following steps are required in order to generate the client certificate and establish the connection with Roche:

Generate Client Certificate Signing Request

  1. Generate Key (Example): openssl genrsa -out company.qaeu.client.key 2048

  2. Generate Client Certificate Request (Example): openssl req -new -sha256 -key company.qaeu.client.key -subj "/C=ES/ST=Barcelona/L=Sant Cugat del Valles/O=Roche Diabetes Care Spain SL/OU=Roche Diabetes Care Spain SL/CN=_EMAIL.{env}@COMPANY.COM" -out company.qaeu.client.req.pem

    {env} possible values:

    • demo
    • prodeu

Subject Fields

C = Country ST = Test State or Province L = Test Locality O = Organization Name OU = Organizational Unit Name CN = Email Company System (Must have the environment code in the email)

  1. Provide *.csr file to Roche DC (and NOT the private key)

Configure client keystore and truststore

In order to connect to Roche ecosystem using mutual authentication, there are two main elements it is needed to work with: keystores, which contain a client’s private key, and truststore, which contain public certificates (Root CA and intermediates) to validate the certificate chain.

Root CA: Roche DC Global Digital Root CA

Intermediate level 1: Roche DC Global Digital Intermediate TESTUS CA

Intermediate level 2: Roche DC Global Digital Intermediate TESTUS ServerCert CA

Roche DC root and intermediates public certificates are available here: https://ca.rochedcplatform.com/



Outbound Connections - One-way authentication (HTTPS)

EMR middleware provides an endpoint in order to allow Roche notify new changes. In this case Roche is acting as a client in order to notify EMR Middleware.

Basic Authentication (HTTPS)

Notification interface should use HTTP Basic Authentication. EMR middleware, acting as a server, needs to provide username and password to client application (Roche)

Server certificate for EMR Middleware

For the server certificate, the Certificate Authority can be Roche and not an external 3rd party CA. Roche sign certificates used in HTTPS so it is responsible for generating and sharing the server certificate based on the Certificate Signing Request (CSR) provided by EMR middleware.

EMR middleware is responsible for generating a Private Key, maintaining in a Private Keystore and providing to Roche the CSR in order to issue the certificate.

Generate Server Certificate Signing Request

  1. Generate Key (Example): openssl genrsa -out company.qaeu.server.key 2048

  2. Generate Server Certificate Signing Request (Example): openssl req -new -sha256 -key company.qaeu.server.key -subj "/C=Country/ST=State or Province/L=Locality/O=Organization/CN=DOMAIN_FQDN" -out company.qaeu.server.req.pem

Subject Fields

C = Country ST = Test State or Province L = Test Locality O = Organization Name OU = Organizational Unit Name CN = DOMAIN_FQDN

  1. Provide *.csr file to Roche DC (and NOT the private key)