T3.1: Authentication Domains for External Providers

Overview

In enterprise healthcare environments, organizations rarely want HealthShare to manage its own user credentials database. Instead, they require HealthShare to integrate with existing identity management infrastructure such as Microsoft Active Directory (AD), LDAP directories, or cloud-based identity providers. Federated authentication allows HealthShare to delegate the process of verifying user credentials to these external systems while retaining control over authorization (what the authenticated user is permitted to do).

This approach reduces password fatigue for clinicians, centralizes credential management for IT administrators, and ensures that HealthShare complies with the organization's security policies.

Federated Authentication Flow

1. User Request: A user attempts to access a HealthShare application (e.g., Clinical Viewer, Management Portal) 2. Redirect to IdP: HealthShare redirects the user to the configured identity provider for authentication 3. Credential Verification: The user provides credentials to the IdP (username/password, MFA, smart card, etc.) 4. Token/Assertion Issuance: Upon successful verification, the IdP issues a security token (OAuth access token) or assertion (SAML assertion) 5. Token Delivery: The token or assertion is delivered to HealthShare (via browser redirect, callback URL, or direct API call) 6. Session Establishment: HealthShare validates the token/assertion, extracts user identity information, maps the user to HealthShare roles, and creates a session 7. Access Granted: The user is granted access based on their mapped HealthShare roles and privileges

Identity Provider Types

• LDAP/Active Directory: The most common enterprise IdP. HealthShare connects to the LDAP directory to verify credentials and retrieve user attributes.
• SAML 2.0 IdP: A standards-based identity provider that issues SAML assertions. Common in healthcare organizations that use identity federation services (ADFS, Okta, Ping Identity).
• OAuth 2.0 Authorization Server: Issues access tokens and optionally ID tokens (OpenID Connect). Used for modern web and API-based authentication scenarios.
• Kerberos: Ticket-based authentication common in Windows domain environments. HealthShare can accept Kerberos tickets for seamless desktop SSO.

Architecture Considerations

• High Availability: The IdP must be highly available since all authentication depends on it. Consider redundant IdP servers.
• Network Connectivity: HealthShare servers must have reliable network access to the IdP. Firewall rules must allow authentication traffic.
• Certificate Management: SSL/TLS certificates are required for secure communication between HealthShare and the IdP. Certificate expiration can cause authentication failures.
• Failover Strategy: Define behavior when the IdP is unreachable (deny all access vs. fallback to local authentication).

---

Overview

While HealthShare provides built-in LDAP/AD authentication, many organizations require custom logic during the authentication process. Custom authentication callbacks allow implementers to execute ObjectScript code at specific points in the authentication flow, enabling attribute transformation, additional validation, dynamic role assignment, and audit logging.

LDAP Authentication Sequence

1. User presents credentials (username and password) to HealthShare 2. HealthShare constructs an LDAP bind request using the configured LDAP server settings 3. The LDAP bind request is sent to the directory server 4. If the bind succeeds, HealthShare retrieves user attributes (display name, email, group memberships, etc.) 5. Custom callback code executes (if configured) to process attributes and apply business logic 6. HealthShare creates or updates the local user record with information from LDAP 7. Roles are assigned based on LDAP group memberships (via mapping configuration or custom code) 8. The user session is established

Implementing Custom Callbacks

Custom callbacks are typically implemented in the ZAUTHENTICATE routine (see Section 5) or in a delegated authentication class. Key extension points include:

• Pre-Authentication: Execute logic before the LDAP bind (e.g., check if the user is in an allowed OU, transform the username)
• Post-Authentication: Execute logic after successful LDAP bind (e.g., retrieve additional attributes, update local user record)
• Role Assignment: Custom logic to map LDAP attributes to HealthShare roles beyond simple group mapping
• Error Handling: Custom responses to authentication failures (e.g., distinguish between wrong password, locked account, expired password)

Handling AD-Specific Attributes

Active Directory provides attributes that require special handling:

• memberOf: Multi-valued attribute listing group DNs. Parse to extract group names for role mapping.
• userAccountControl: Bitmask attribute encoding account status (disabled, locked, password expired, etc.). Decode to determine if the account should be allowed access.
• pwdLastSet: Timestamp of last password change. Calculate password age and enforce expiration policies.
• accountExpires: Timestamp when the account expires. Block access for expired accounts.
• lockoutTime: Timestamp of account lockout. Prevent access for locked-out accounts even if LDAP bind succeeds with cached credentials.

Example Callback Logic

// In ZAUTHENTICATE routine - post-authentication callback
// Retrieve additional LDAP attributes
Set displayName = $Get(Properties("FullName"))
Set email = $Get(Properties("Email"))
Set department = $Get(Properties("Department"))

// Enforce department-based access policy
If department = "Radiology" {
    // Assign radiology-specific role
    Set Properties("Roles") = Properties("Roles") _ ",HS_Radiology_Viewer"
}

// Log authentication event
Do ##class(Custom.AuthAudit).LogLogin(username, department, $H)

---

Overview

Password policy enforcement in a federated authentication environment requires coordination between HealthShare and the external identity provider. When using LDAP/AD as the authentication backend, the directory server enforces password policies (complexity, history, age, lockout). HealthShare must be configured to properly detect and respond to these policy states rather than silently failing or providing confusing error messages.

Credential Expiration Configuration

Active Directory enforces password expiration through Group Policy settings:

• Maximum Password Age: The number of days before a password must be changed (e.g., 90 days)
• Minimum Password Age: The minimum number of days before a password can be changed again
• Password History: The number of previous passwords remembered to prevent reuse

HealthShare detects password expiration during LDAP authentication by examining the bind response and AD attributes:

1. Expired Password: The LDAP bind may fail with a specific error code (data 532) indicating the password has expired 2. Near-Expiration Warning: Custom callback code can read pwdLastSet and calculate remaining days, then display a warning to the user 3. Must-Change-Password: AD can flag accounts requiring password change at next logon (pwdLastSet = 0)

Password Complexity Rules

AD Group Policy defines complexity requirements:

• Minimum length (e.g., 8 characters)
• Character class requirements (uppercase, lowercase, digits, special characters)
• Cannot contain the username or display name

HealthShare defers to AD for complexity enforcement. When a user changes their password through HealthShare (if supported), the change request is forwarded to AD, which validates it against the policy. If the password does not meet complexity requirements, AD rejects the change, and HealthShare displays an appropriate error message.

Account Lockout Policies

AD Group Policy defines lockout settings:

• Lockout Threshold: Number of failed attempts before lockout (e.g., 5 attempts)
• Lockout Duration: How long the account remains locked (e.g., 30 minutes, or until admin unlocks)
• Lockout Observation Window: Time window for counting failed attempts

HealthShare should: 1. Detect lockout conditions from LDAP bind error codes (data 775) 2. Display a clear message indicating the account is locked 3. Optionally log lockout events for security monitoring 4. Avoid caching credentials that bypass the lockout check

LDAP Password Policy Integration

To provide meaningful password-related messages, custom authentication code can query AD for policy details:

// Read password policy attributes from AD
Set maxPwdAge = ##class(Custom.LDAPUtils).GetDomainPolicy("maxPwdAge")
Set pwdLastSet = ##class(Custom.LDAPUtils).GetUserAttr(username, "pwdLastSet")
Set daysRemaining = ##class(Custom.LDAPUtils).CalcDaysRemaining(pwdLastSet, maxPwdAge)

If daysRemaining < 14 {
    Set warningMsg = "Your password expires in " _ daysRemaining _ " days. Please change it soon."
}

---

OAuth 2.0 Authorization Code Flow

OAuth 2.0 is the modern standard for delegated authorization, and with OpenID Connect (OIDC), it also provides authentication. The authorization code flow is the recommended approach for web applications like the HealthShare Clinical Viewer.

Flow Steps:

1. User navigates to HealthShare Clinical Viewer 2. HealthShare redirects to the OAuth authorization endpoint with client_id, redirect_uri, scope, and state parameters 3. User authenticates at the IdP (if not already authenticated) 4. IdP redirects back to HealthShare's callback URL with an authorization code 5. HealthShare exchanges the authorization code for an access token (and optionally ID token) via a back-channel request 6. HealthShare validates the tokens and extracts user identity claims 7. HealthShare maps the user identity to a local user and establishes a session

Configuration Requirements:

• Register HealthShare as an OAuth client in the IdP (obtain client_id and client_secret)
• Configure the authorized redirect URI in the IdP
• In HealthShare, configure the OAuth client settings: authorization endpoint, token endpoint, client_id, client_secret
• Define the requested scopes (openid, profile, email, groups)
• Configure token validation (signing key, issuer, audience)

SAML 2.0 Assertion Flow

SAML 2.0 is a mature standard widely used in healthcare for federated SSO. HealthShare acts as the Service Provider (SP) and relies on an external SAML Identity Provider (IdP) such as ADFS, Okta, or Shibboleth.

Flow Steps:

1. User navigates to HealthShare (SP-initiated flow) or clicks a link in the IdP portal (IdP-initiated flow) 2. For SP-initiated: HealthShare generates a SAML AuthnRequest and redirects to the IdP 3. User authenticates at the IdP 4. IdP generates a SAML Response containing a signed Assertion with user attributes 5. The SAML Response is POSTed to HealthShare's Assertion Consumer Service (ACS) URL 6. HealthShare validates the assertion signature, checks conditions (audience, time validity) 7. HealthShare extracts identity attributes and maps them to a local user

Configuration Requirements:

• Exchange metadata between IdP and SP (entity IDs, endpoints, certificates)
• Configure HealthShare as a SAML SP with the ACS URL and entity ID
• Import the IdP's signing certificate into HealthShare for assertion verification
• Define attribute mappings: which SAML attributes map to HealthShare user properties (username, display name, email, roles)
• Configure NameID format (email, persistent identifier, or Windows domain name)

Token/Assertion Mapping to HealthShare Identities

After receiving a valid token (OAuth) or assertion (SAML), HealthShare must map the external identity to a local user:

• Username Mapping: The primary identifier claim (e.g., "sub" in OAuth, "NameID" in SAML) is mapped to the HealthShare username
• Auto-Provisioning: If the user does not exist locally, HealthShare can auto-create the user record using attributes from the token/assertion
• Role Mapping: Group or role claims in the token/assertion are mapped to HealthShare roles (see T3.2)
• Session Properties: Additional claims (department, facility, display name) are stored in the session context

---

Overview

The ZAUTHENTICATE routine is a special ObjectScript routine that serves as the entry point for delegated authentication in InterSystems IRIS (and by extension, HealthShare). When delegated authentication is enabled for a HealthShare instance, the system calls the ZAUTHENTICATE routine whenever a user attempts to log in. This routine contains custom code that determines how authentication is performed, what user properties are set, and what roles are assigned.

ZAUTHENTICATE is the most powerful and flexible authentication customization point in HealthShare, but it also carries significant responsibility. Errors in this routine can lock out all users or create security vulnerabilities.

Routine Structure

The ZAUTHENTICATE routine must follow a specific structure:

ZAUTHENTICATE(ServiceName, Namespace, Username, Password, Credentials, Properties) PUBLIC {
    // Authentication logic goes here

    // Set user properties
    Set Properties("FullName") = fullName
    Set Properties("Email") = email
    Set Properties("Roles") = roleList
    Set Properties("Namespace") = namespace

    // Return status
    // $$$OK = authentication successful
    // Error status = authentication failed
    Quit $$$OK
}

Parameters:

• ServiceName: The service being accessed (e.g., "%Service_WebGateway", "%Service_Console")
• Namespace: The namespace being accessed
• Username: The username provided by the user
• Password: The password provided by the user
• Credentials: Additional credential information (may be empty)
• Properties: Output array for setting user properties and roles

Return Value:

• $$$OK ($System.Status.OK()): Authentication succeeded
• Error status: Authentication failed (provide a meaningful error message)

When and How to Modify ZAUTHENTICATE

When to modify:

• The organization requires LDAP/AD authentication for HealthShare
• Custom role mapping logic is needed beyond simple group-to-role mapping
• Additional authentication factors must be checked (MFA token, IP address, time-of-day restrictions)
• Custom audit logging of authentication events is required
• User properties need to be dynamically populated from external sources

How to modify: 1. Edit the routine in the %SYS namespace (where it must reside) 2. Implement the authentication logic using standard ObjectScript 3. Set the Properties array with user attributes and roles 4. Return the appropriate status code 5. Thoroughly test with valid and invalid credentials 6. Test edge cases: locked accounts, expired passwords, network failures

Common Customizations

• LDAP Bind Authentication: Perform an LDAP bind with the user's credentials against the directory server
• Group-to-Role Mapping: Query LDAP group memberships and map to HealthShare roles
• Multi-Factor Validation: Check a secondary factor (TOTP code, smart card certificate) in addition to the password
• IP Address Restrictions: Allow or deny access based on the client IP address
• Time-Based Restrictions: Restrict access to certain hours or days
• Audit Logging: Log every authentication attempt (success and failure) to a custom audit table
• Session Properties: Populate session-level properties (facility, department, user type) from directory attributes

Security Considerations

• Elevated Privileges: ZAUTHENTICATE runs in the %SYS namespace with system-level access. Any code in this routine has full access to all namespaces and resources.
• Error Handling: Unhandled errors in ZAUTHENTICATE can cause authentication to fail for all users. Always wrap code in try/catch blocks.
• Credential Handling: Never log or store plaintext passwords. The Password parameter must be used only for verification (e.g., LDAP bind) and never persisted.
• Code Review: All changes to ZAUTHENTICATE should undergo security code review before deployment to production.
• Testing: Test in a non-production environment first. Verify that both successful and failed authentication scenarios work correctly.
• Backup: Always keep a backup copy of the working ZAUTHENTICATE routine before making changes.
• Fallback: Consider implementing a fallback mechanism (e.g., a local admin account that bypasses delegated auth) to prevent complete lockout.

---