T2.1: Secures UCR

Overview

SSL/TLS is the foundation of secure communication in a UCR deployment. Every component — Registry, Edge Gateways, Access Gateways, and Clinical Viewer — must use encrypted connections to protect patient data in transit.

Creating SSL/TLS Configurations

To create a configuration: navigate to System Administration > Security > SSL/TLS Configurations, click "Create New Configuration", provide a name, select Server or Client type, specify the certificate file (.cer/.pem), private key file (.key), and CA certificate file. Set TLS 1.2 as minimum (TLS 1.3 preferred) and configure cipher suites as needed.

%SuperServer Configuration

The %SuperServer configuration is a reserved system-level SSL/TLS configuration that secures the SuperServer port. When enabled, all SuperServer connections (mirrors, ECP, Studio/IDE) require TLS. After enabling, all connecting clients must also use TLS.

Enabling TLS on Production Components

Open the production in the Management Portal, select a business host, locate the SSL/TLS configuration property, and select the appropriate configuration. SOAP-based components use SSL in SOAP connection settings; TCP-based components use TLS in TCP adapter settings.

---

Loading Certificates via Management Portal

In the SSL/TLS configuration, provide paths to the certificate file, private key file, and CA certificate file. Enter the private key password if the key is encrypted. Save and verify the configuration.

The iris.cer and iris.key Files

These are self-signed certificates installed with each IRIS instance for development and testing only. In production, replace them with certificates signed by your organization's CA. Each UCR component should have its own properly signed certificate.

Certificate Chains and Renewal

Bundle leaf, intermediate, and root CA certificates into a single PEM file (leaf-to-root order). Incomplete chains cause TLS validation failures. For renewal: generate a CSR before expiration, obtain the new certificate from your CA, replace the file on each component, restart services, and verify connectivity.

---

SSO Flow

1. User accesses Clinical Viewer or another UCR component 2. Component redirects user to the Registry for authentication 3. User authenticates at the Registry (via username/password, LDAP, OAuth, etc.) 4. Registry generates a SAML security token with the user's identity and roles 5. Token is passed back to the requesting component 6. Component validates the token (checking signature, expiration, issuer) 7. User is granted access; token is reused for subsequent component access until it expires

Federation Trust Model

The Registry is the sole token issuer. Trust is established by loading the Registry's signing certificate on each Edge Gateway, Access Gateway, and Clinical Viewer. Token lifetime is configurable (typically 8 hours, matching a clinical shift). Tokens are passed via HTTP headers or SOAP message headers.

---

Configuration Steps

Step 1 — Registry as IdP: Enable SSO, configure SAML IdP settings, specify signing certificate and private key, set entity ID and authentication endpoint URL, configure token lifetime.

Step 2 — Register SPs: For each component, register it at the Registry with its entity ID and assertion consumer service (ACS) URL. Configure audience restrictions and attribute mappings for roles and facility assignments.

Step 3 — Configure Components: On each component, enable SSO, load the Registry's signing certificate, configure the IdP metadata URL, set SP entity ID to match the Registry registration, and configure the ACS URL.

Step 4 — SAML Token Attributes: Tokens should include user identity, assigned roles (%HS_Clinician, %HS_Administrator, etc.), facility assignments, session identifier, and custom attributes.

Step 5 — Testing: Test login through each component, verify redirection to Registry, confirm cross-component access without re-login, test token expiration and single logout (SLO).

---

Common Failures and Resolutions

Certificate Mismatches: "Signature validation failed" errors. Verify the same public key is loaded on all components. Re-export and redistribute if needed.

Clock Skew: Tokens rejected as "not yet valid" or "expired" even when just issued. Configure NTP on all servers; clocks must be within 5 minutes of each other.

Token Expiration: Users unexpectedly redirected to login during active sessions. Increase token lifetime in the IdP configuration; implement token refresh.

Redirect Loops: "Too many redirects" error. Verify entity IDs and ACS URLs match exactly between Registry and component configurations.

Diagnostic Tools

Use SAML tracer (browser extension) to capture SAML requests/responses, the HealthShare Event Log for authentication events, the System Audit Log for login attempts, Web Gateway logs for HTTP-level issues, and ^%ISCLOG for low-level SSL/TLS debugging.

---

Method Comparison

Internal: Managed in Management Portal under System Administration > Security > Users. Simple to configure but hard to scale. Best for system administrators and service accounts.

LDAP/AD: Configured at System Administration > Security > System Security > LDAP Configuration. Specify server address, base DN, search filter, and bind credentials. Enables enterprise-wide password management.

OAuth 2.0: UCR acts as a Relying Party to an external Authorization Server. Uses authorization code flow with PKCE. Ideal for modern web-based access and cloud identity providers.

SAML 2.0: UCR acts as a Service Provider receiving signed assertions from an IdP. Widely used in healthcare with existing SAML infrastructure.

ZAUTHENTICATE: Custom ObjectScript routine in %SYS namespace called on each login attempt. Maximum flexibility for multi-factor authentication or custom databases. Requires custom development.

---

Internal Security Domains

Navigate to HealthShare > Security > Security Domains, create a new domain with "Internal" type. Configure password policies (minimum length, complexity, expiration, history), set default roles. Used for system administrators, service accounts, and dedicated HealthShare users.

External Security Domains

Create a new domain with LDAP, OAuth, or SAML type. Configure the connection to the external identity provider (server address, client credentials, metadata URL). Set up attribute mapping, default roles, and enable auto-provisioning if desired. Auto-provisioning automatically creates HealthShare accounts on first login from the external source.

Domain Properties

Key properties include: authentication method, password policy (internal domains only), default roles, auto-provisioning toggle, and domain priority (determines evaluation order when multiple domains exist).

---

OAuth 2.0 Configuration

Register UCR at the authorization server (Azure AD, Okta, Keycloak) to obtain client ID and secret. In the Management Portal (System Administration > Security > OAuth 2.0 > Client Configuration), enter the issuer URL, endpoints (or discovery URL), client credentials, and redirect URI. Configure scope requirements and map OAuth claims to HealthShare user properties and roles.

SAML 2.0 Configuration

Export UCR's SP metadata (entity ID, ACS URL, signing certificate) and import it into the IdP. Import the IdP's metadata into UCR. Configure attribute mappings (NameID to user identifier, attributes to roles). Set NameID format, assertion validity period, and signature requirements (signed assertions, signed responses, or both).

Redirect URI Best Practices

URIs must match exactly between UCR and the IdP registration. Use HTTPS in production. Avoid wildcards. Update URIs if the UCR hostname changes. Document all configured redirect URIs.

---

Standard TLS vs Mutual TLS

Standard TLS authenticates only the server. Mutual TLS requires both parties to present certificates, establishing client identity at the TLS layer before application traffic flows.

Configuring mTLS

1. Web Server: Enable client certificate verification (e.g., SSLVerifyClient require in Apache). Specify the CA certificate file and configure CRL/OCSP for revocation checking. 2. Web Gateway: Enable client certificate forwarding to pass certificate information to IRIS. Map the client certificate's Subject DN or SAN to a HealthShare user identity. 3. IRIS: Create an SSL/TLS configuration requiring client certificates. Set up user mapping from certificate attributes to HealthShare accounts.

Certificate-Based Authentication Flow

Client initiates HTTPS, Web Gateway presents its server certificate, Web Gateway requests the client's certificate, validates it against the trusted CA and CRL/OCSP, extracts the client identity, passes it to HealthShare, and HealthShare maps it to a user account with assigned roles.

---