HL7 FHIR security

To authenticate to a FHIR server, assign a security definition to the connection's Security field - Zato attaches the credentials to every request the connection makes. Which definition to create depends on what the server requires:

• Basic Auth - a username and password, allocated in advance by the server's maintainers
• Bearer tokens - a client ID with a secret or a private key that Zato exchanges for short-lived OAuth tokens with the server's authorization service, the private key being what SMART Backend Services and the EHRs behind them call for

The two are mutually exclusive on one connection - HTTP reserves a single Authorization header for credentials. TLS is independent of either and applies when the connection's address starts with https://.

Basic Auth

To create the credentials, go to Security > Basic Auth in the Dashboard, click Create a Basic Auth definition and fill in the form:

1. Name: FHIR.Credentials
2. Username: the username the server's maintainers allocated
3. Password: the matching password
4. Click OK

Then select the definition in the Security field of a new or existing FHIR connection - the change takes effect as soon as you click OK, with no restarts:

OAuth bearer tokens

With OAuth, your Zato server holds a client ID and secret, exchanges them for a short-lived token with the server's authorization service, and sends that token in the Authorization header. The token is scoped - it grants access to the subset of the FHIR API the definition's scopes name.

Zato acquires and refreshes the tokens for you. When a token expires, the next request obtains a fresh one from the authorization service - no configuration and no code are required for the renewal.

To create the definition, go to Security > Bearer tokens in the Dashboard, click Create a Bearer token definition and fill in the form:

1. Name: FHIR.Identity
2. Auth. endpoint: the token endpoint, e.g. https://identity.hospital.example.com/oauth/token
3. Client ID: the client ID the authorization service issued
4. Client secret: the matching client secret
5. (Optional) OAuth scopes: the scopes the FHIR server expects, e.g. system/*.read
6. Click OK

Then select the definition in the connection's Security field, as described for Basic Auth. To learn about every field of the definition, JWT verification and identity provider walkthroughs, see Bearer tokens.

SMART Backend Services with a private key

Epic, Oracle Health, eClinicalWorks and the other certified EHRs let backend applications log in without a client secret, under the name SMART Backend Services. Your Zato server holds a private key, signs each token request with it and the EHR verifies the signature with the public key you registered - no secret is ever sent over the wire, and the EHR never holds anything that could be used to impersonate your application.

The same bearer token definition covers it, with Authentication switched to Private key JWT:

1. Name: FHIR.Identity
2. Auth. endpoint: the EHR's token URL - it is the token_endpoint of the server's .well-known/smart-configuration document, e.g. https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
3. Client ID: the client ID the EHR issued when the application was registered
4. Authentication: Private key JWT
5. Private key: the PEM private key - generate one with openssl genrsa -out fhir.key 2048, paste the file's contents here
6. Algorithm: RS384, as SMART Backend Services require
7. Key ID: a name for the key, e.g. fhir-key-1
8. OAuth scopes: the system/ scopes the application needs, e.g. system/Patient.read
9. Click OK

Once the definition is saved, open it again and follow its Public key link - it serves the key's public half as a JWK set, which is the format the EHRs' developer portals take when the application is registered. Epic and Oracle Health pick the verification key by its kid, so the Key ID is what ties the registered key to the signed requests.

The connection itself does not change - select the definition in its Security field and every request obtains its token with a signed assertion, including a bulk export of the connection, which the system/*.read scopes above authorize. The Epic and Oracle Health page shows the full flow from registration to the first patient read.

TLS

A connection whose address starts with https:// encrypts all traffic and validates the server's certificate against the publicly trusted certificate authorities - the same set that web browsers use. A certificate that fails the validation stops the request with an error before any data is exchanged.

If the server's certificate comes from an internal, non-public CA, point the REQUESTS_CA_BUNDLE environment variable of the Zato server process at the CA's certificate bundle in the PEM format - the connection then validates certificates against that bundle.

See also

Learn more