Security Best Practices

OAuth credentials and access tokens grant access to protected clinical data. Implementations must follow secure handling practices to protect client credentials, user data, and tenant context.

Secure Storage of client_secret

The client_secret is a confidential credential used to authenticate your client application.

You must:

• Store the client_secret securely on a server-side system
• Restrict access to authorized systems and personnel only
• Never embed the client_secret in client-side code (such as browser JavaScript or mobile apps)
• Rotate credentials if compromise is suspected

Exposure of a client_secret may allow unauthorized access to protected APIs.

Secure Handling of Refresh Tokens

Refresh tokens provide the ability to obtain new access tokens without repeating the full authorization flow.

You must:

• Store refresh tokens securely using the same protections as the client_secret
• Never expose refresh tokens in client-side code
• Transmit refresh tokens only over secure channels
• Invalidate and re-authorize if compromise is suspected

Refresh tokens should be treated as long-lived credentials and protected accordingly.

Use of the state Parameter

The state parameter should be included in authorization requests to prevent CSRF (Cross-Site Request Forgery) and related attacks.

Implementations should:

• Generate a cryptographically random state value per request
• Persist the state value server-side
• Validate that the returned state matches the original request before exchanging the authorization code

Failure to validate state may allow unauthorized request injection.

Prefer Authorization Code for User-Facing Applications

For user-facing integrations, Authorization Code Grant is recommended over Implicit Grant.

If public clients are supported, use Authorization Code with PKCE when applicable to reduce the risk of authorization code interception.

Validation of Tokens Returned via Redirect

For flows that return access tokens directly in the redirect response (such as Implicit Grant):

• Validate the token using /oauth/info before using it
• Confirm that the returned client_id matches the expected client
• Confirm that the granted scope matches expected permissions

For Authorization Code Grant, token validation occurs during the server-side token exchange process.

Tokens received through redirects must not be trusted without validation.

Avoid Logging Access Tokens

Access tokens are bearer credentials. Anyone in possession of a valid token may be able to access protected resources within its scope.

Implementations should:

• Avoid writing access tokens to logs
• Redact tokens from error messages
• Avoid including tokens in monitoring or tracing systems

If token logging cannot be fully avoided, ensure logs are properly secured and access-controlled.

Avoid Transmitting Tokens in URLs

Access tokens should not be transmitted in query parameters for production integrations.

Tokens included in URLs may:

• Be stored in browser history
• Be captured in server logs
• Be exposed in referrer headers

Always use the Authorization: Bearer header to transmit access tokens.

Enforce TLS for All Requests

All OAuth and API requests must be transmitted over TLS (HTTPS).

Do not:

• Send tokens over unsecured HTTP
• Terminate TLS in untrusted network segments
• Allow mixed-content requests in browser-based integrations

TLS protects tokens and credentials from interception in transit.

Adhering to these security practices reduces the risk of credential compromise and protects access to sensitive clinical data.