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 and secret that Zato exchanges for short-lived OAuth tokens with the server's authorization service

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 the moment 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, the same way as with Basic Auth. To learn about every field of the definition, JWT verification and identity provider walkthroughs, see Bearer tokens.

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