ESMD FHIR Implementation Guide
1.0.0 - esmd
ESMD FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The esMD FHIR server implements multiple security mechanisms and best practices to ensure the confidentiality, integrity, and availability of the data that it processes. Those mechanisms and best practices include: OAuth2 authentication and authorization, client credentials management, IP whitelisting, Hypertext Transfer Protocol Secure (HTTPS) and Transport Layer Security (TLS) 1.2 Encryption, certificate validation, rate limiting, logging and monitoring, and token revocation.
The esMD System uses the Open Authorization (OAuth2) protocol to grant user access to the system without the need to share passwords or other credentials. The esMD team provides a Client ID and Client Secret when users onboard to esMD. This allows clients to authenticate with the FHIR API using the OAuth2 client_credentials grant type.
Clients must use the client credentials to request an access token. This token is used in the Authorization header of all FHIR API requests.
Request Example:
POST /oauth/token HTTP/1.1
Host: esmd.cms.hhs.gov
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
Response Example:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
Once the access token has been obtained, it must be included in the Authorization header for all esMD FHIR API requests.
Example API Request:
POST /fhir/Bundle HTTP/1.1
Host: api.esmd.fhir.server.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Tokens expire 1 hour after they were granted. A new token must be requested once the current token expires.
esMD provides each client with a Client ID and Client Secret during the HIH’s or provider’s initial onboarding process. The client must securely store these credentials to ensure they are kept confidential.
Users are encouraged to rotate their client secrets periodically for security. Requests for credential rotation must be submitted to the CMS esMD Service Desk - esMD_Support@cms.hhs.gov
In addition to OAuth2, esMD uses Internet Protocol (IP) address whitelisting to restrict API access to trusted IP addresses.
esMD collects the client’s trusted IP addresses during onboarding. Only traffic that originates from these trusted IPs is allowed to access the esMD FHIR APIs. esMD uses the following categories to classify trusted IPs:
Clients must notify esMD of any changes to their trusted IP addresses to avoid disruption in service.
All communications with esMD FHIR APIs must take place over a connection that has been secured using HTTPS and TLS 1.2 or higher protocols to protect data in transit.
Clients must validate the esMD FHIR server’s TLS certificates to protect against man-in-the-middle attacks.
esMD FHIR APIs enforce rate limits to prevent abuse and ensure fair usage.
Clients are subject to rate limits based on their expected traffic. Clients will receive a HTTP 429 Too Many Requests error when the rate limit is exceeded.
Clients may request rate a limit increase if their traffic volumes exceed expected levels. Rate limit increases must obtained by contacting the CMS esMD Service Desk - esMD_Support@cms.hhs.gov.
All API requests and responses are logged for monitoring and auditing purposes. esMD logs include the following information for each logged request or response:
Suspicious activity may result in access revocation and unauthorized IP addresses shall be blocked.
In the event that client credentials become compromised, esMD shall revoke access tokens immediately. Clients must notify the esMD team of any security incidents immediately.
Please contact the CMS esMD Service Desk for any security-related issues, including IP address changes, credential rotation, or token revocation.