T12.3: Manages Users and Roles

Overview

User provisioning is the process of creating and configuring user accounts in the UCR federation. Each person who needs access to UCR components (Clinical Viewer, Management Portal, administrative tools) must have a provisioned user account. The provisioning process involves creating the account, setting credentials, assigning roles and permissions, and associating the user with appropriate facilities and security groups.

Effective user provisioning ensures that clinicians and administrators have the access they need while maintaining security and compliance with organizational policies.

User Creation Process

1. Access the user management interface in the UCR Management Portal 2. Create a new user account 3. Set the username (typically following organizational naming conventions) 4. Enter user details: full name, email address, phone number 5. Set initial credentials (temporary password requiring change on first login) 6. Associate the user with their facility or facilities 7. Assign appropriate roles and security groups 8. Activate the account 9. Notify the user of their credentials and login instructions

User Properties

• Username: Unique login identifier for the user
• Full Name: Display name (first name, last name)
• Email: Email address for notifications and password reset
• Facility Association: Which facilities the user is affiliated with
• Department: User's department or unit
• Status: Active, inactive, locked, or suspended
• Creation Date: When the account was created
• Last Login: Most recent login timestamp

Account Lifecycle Management

• Creation: Initial account setup with minimal required information
• Activation: Account enabled for login (may require email verification)
• Modification: Update properties, roles, or facility associations as needed
• Deactivation: Disable account while preserving records (for temporary leave)
• Reactivation: Re-enable a deactivated account
• Deletion: Permanent removal (subject to retention policies)

---

Overview

Roles are the primary mechanism for controlling user access and capabilities in UCR. A role defines a set of privileges that determine what actions a user can perform, what data they can access, and which system features are available to them. UCR includes standard roles for common user types, and organizations can create custom roles to match their specific access requirements.

Proper role configuration is critical for security, as it ensures users have the minimum necessary access to perform their job functions (principle of least privilege).

Standard Roles

• Physician/Clinician: Access to Clinical Viewer, patient data, clinical features
• Nurse: Access to Clinical Viewer with nursing-relevant chartbooks and data
• Pharmacist: Access to medication-related data and pharmacy-specific views
• Administrator: Access to Management Portal, registries, configuration, and reports
• System Administrator: Full system access including technical configuration
• Report User: Access to management reports without clinical data access
• Auditor: Read-only access to audit logs and compliance reports

Custom Role Creation

1. Identify the access requirements for the custom role 2. Create a new role in the user management interface 3. Assign permissions to the role:

• System resources (Management Portal sections, registries)
• Data access (clinical data categories, facilities)
• Features (print, export, annotation, emergency access)

4. Name the role descriptively 5. Document the role's intended purpose and target users 6. Test the role by assigning it to a test user and verifying access

Role-Permission Mapping

• Each role has an explicit list of granted permissions
• Permissions are additive: a user with multiple roles gets the union of all role permissions
• No explicit deny in the standard model (absence of permission means no access)
• Permissions can be scoped to specific facilities, data categories, or system components

---

Overview

The UCR federated security model addresses the challenge of authenticating users across multiple components (Hub, Edge Gateways, Access Gateways) that may be deployed on different servers or in different networks. The security model defines how user identity is established at one component and trusted by other components, how security domains are configured, and how authentication flows work across the federation.

Understanding the federated security model is essential for configuring secure access to UCR components and troubleshooting authentication issues.

Security Domain Boundaries

• Each UCR component (Hub, Edge Gateway, Access Gateway) may define its own security domain
• A security domain encompasses the authentication mechanism, user store, and session management for a component
• Security domains can be:
• Shared: Multiple components use the same security domain (common in single-server deployments)
• Separate: Each component has its own security domain (common in distributed deployments)
• Cross-domain authentication requires federation mechanisms (SSO, SAML)

Trust Relationships

• Components in the federation establish trust with each other
• Trust is based on shared certificates, tokens, or federation protocols
• An authenticated session at one component can be recognized by trusted components
• Trust configuration includes certificate exchange and endpoint registration

Authentication Flow

1. User authenticates at the initial component (e.g., Login App for Clinical Viewer) 2. Authentication produces a token/session that identifies the user 3. When the user accesses other federation components, the token is presented 4. The receiving component validates the token against the trust relationship 5. If valid, the user is granted access based on their roles and permissions 6. Token expiration and renewal follow configured policies

---

Overview

Federated Single Sign-On (SSO) allows UCR users to authenticate once and then access all federation components (Clinical Viewer, Management Portal, Hub, Edge Gateway, Access Gateway) without being prompted to log in again. SSO improves usability for clinicians who may access multiple components during their workflow and reduces password fatigue.

Configuring federated SSO involves setting up web application paths, configuring the web server for SSO cookie handling, and establishing trust between components.

Enabling Federated SSO

1. Configure the Login App as the central authentication point 2. Set up web application paths for each component to be included in SSO 3. Configure the web server (Apache or IIS) for SSO cookie domains and paths 4. Establish trust between components for SSO token validation 5. Configure session parameters (timeout, renewal, max lifetime) 6. Test SSO across all components

Public-Facing Web Application Paths

• Each UCR component exposed through SSO must have a configured web application path
• Web application paths determine how URLs are routed to the correct component
• Configure paths to be consistent and predictable for users and automated systems
• Ensure paths are properly secured with SSL/TLS

Web Server Configuration

• Configure the web server to handle SSO cookies across component paths
• Set cookie domain to encompass all components (e.g., *.organization.com)
• Configure secure cookie attributes (Secure, HttpOnly, SameSite)
• Set up URL rewriting or reverse proxy rules as needed
• Ensure the web server passes SSO tokens to backend components

Session Management

• SSO sessions have configurable timeout and renewal settings
• Idle timeout: session expires after period of inactivity
• Maximum lifetime: session expires regardless of activity
• Session renewal: extend session on activity (sliding expiration)
• Global logout: terminating the SSO session logs out from all components

---

Overview

SAML (Security Assertion Markup Language) integration allows UCR to authenticate users through external Identity Providers (IdPs) such as Microsoft Entra ID (Azure AD), Okta, Ping Identity, or other SAML-compliant IdPs. This enables organizations to use their existing enterprise identity infrastructure for UCR authentication, providing a seamless experience for users who are already authenticated through their organization's IdP.

Setting up SAML integration involves obtaining IdP metadata, creating a security domain, configuring UCR as a SAML Service Provider, and testing the authentication flow.

Step 1: Obtain IdP Metadata

• Request the SAML metadata XML document from the external IdP administrator
• Metadata contains: IdP entity ID, SSO endpoint URLs, signing certificates, and supported bindings
• Verify the metadata is for the correct IdP environment (production vs. test)
• Import the metadata into the UCR configuration

Step 2: Create Security Domain

1. Navigate to security domain management in the UCR Management Portal 2. Create a new security domain for SAML authentication 3. Configure the domain to use SAML as the authentication mechanism 4. Import the IdP metadata into the security domain 5. Set the domain's user matching rules (how SAML attributes map to UCR users)

Step 3: Configure Service Provider Settings

1. Generate or import the Service Provider (SP) signing certificate 2. Configure the SP entity ID (unique identifier for UCR as a Service Provider) 3. Set the Assertion Consumer Service (ACS) URL (where the IdP sends authentication responses) 4. Configure attribute mapping (how IdP attributes map to UCR user properties) 5. Set authentication request parameters (NameID format, requested attributes) 6. Export SP metadata to share with the IdP administrator

Step 4: Testing

1. Configure a test user in both the IdP and UCR 2. Initiate a login through the UCR Login App 3. Verify redirect to the IdP login page 4. Authenticate at the IdP 5. Verify redirect back to UCR with successful authentication 6. Confirm user roles and permissions are correctly applied 7. Test logout flow (single logout if supported)

---

Overview

Authentication domains define security boundaries within the UCR federation, specifying how different groups of users are authenticated. A federation may have multiple authentication domains: one for internal users (local authentication), one for clinicians from a partner hospital (SAML), and another for users authenticated through Active Directory (LDAP). The Login App routes users to the correct authentication domain based on configuration.

Understanding authentication domains is essential for configuring a multi-organization federation where different user populations authenticate through different mechanisms.

Domain Types

• Local Authentication: Users authenticate against credentials stored in the UCR user database. Suitable for standalone deployments or users without an external IdP.
• LDAP/Active Directory: Users authenticate against an LDAP directory or Active Directory. UCR validates credentials against the external directory.
• SAML: Users authenticate through an external SAML Identity Provider. Covered in detail in the SAML Integration section.
• Delegated Authentication: Authentication is delegated to a custom authentication class that can implement any authentication logic.

Domain-Based Login Routing

• The Login App presents domain selection to users (dropdown or automatic detection)
• Users select or are assigned to their authentication domain
• The Login App routes the authentication request to the correct domain
• Each domain handles authentication according to its configuration
• After successful authentication, the user receives a session token regardless of domain

Configuring Authentication Domains

1. Create a new authentication domain in the security configuration 2. Select the domain type (local, LDAP, SAML, delegated) 3. Configure the domain-specific settings:

• Local: password policy, account lockout rules
• LDAP: server address, bind credentials, search base, attribute mapping
• SAML: IdP metadata, SP configuration, attribute mapping
• Delegated: custom authentication class reference

4. Set the domain name and description (shown to users in the Login App) 5. Configure user matching rules (how to find the UCR user record for an authenticated identity) 6. Test the domain with sample credentials

---

Overview

Two-factor authentication (2FA) adds an additional layer of security to the UCR login process by requiring users to provide a second form of verification beyond their username and password. This significantly reduces the risk of unauthorized access from compromised credentials. UCR supports two-factor authentication through the Login App, which can be configured to require a second factor for all users or specific user groups.

Enabling Two-Factor Authentication

1. Access the Login App security configuration 2. Enable the two-factor authentication feature 3. Select the type of second factor (TOTP, email, SMS) 4. Configure the second factor parameters:

• TOTP: Token validity period, number of digits
• Email: Email template, verification timeout
• SMS: SMS provider configuration, message template

5. Set the enrollment policy (required for all users, optional, or required for specific roles) 6. Deploy the configuration

User Enrollment Process

1. User logs in with username and password (first factor) 2. System prompts user to enroll in two-factor authentication (if not already enrolled) 3. For TOTP: User scans a QR code with their authenticator app (Google Authenticator, Microsoft Authenticator, etc.) 4. For email/SMS: User confirms their email address or phone number 5. User enters the verification code to complete enrollment 6. Subsequent logins require both password and second factor

Configuration Considerations

• Grace Period: Allow a grace period for users to enroll before 2FA is enforced
• Recovery Codes: Provide backup codes for users who lose access to their second factor
• Bypass Rules: Consider bypass rules for service accounts or emergency access
• Timeout: Configure how long a second factor code is valid
• Rate Limiting: Limit the number of failed second factor attempts before account lockout

---

Overview

The Login App is the authentication entry point for UCR users and is often the first interface they encounter. Customizing the Login App with organization branding and clear messaging improves the user experience and reinforces organizational identity. Customization options include modifying the domain selector behavior, changing text and graphics, and applying stylesheet changes.

Domain Selector Behavior

• Dropdown Selection: Users choose their authentication domain from a dropdown list
• Auto-Detection: The system determines the domain based on the user's network, URL, or other criteria
• Hidden Domain: Single-domain deployments can hide the domain selector entirely
• Default Domain: Set a default domain for the majority of users
• Configure domain selector behavior in the Login App settings

Text and Graphics Modification

• Welcome Message: Customize the text displayed on the login page
• Field Labels: Change labels for username, password, and other fields
• Help Text: Add or modify help text and instructions
• Error Messages: Customize error messages for failed login attempts
• Logo: Replace the default logo with the organization's logo
• Background Image: Set a custom background image for the login page
• Favicon: Set the browser tab icon

Stylesheet Changes

• Override the default Login App CSS with custom stylesheets
• Customize colors to match organizational branding
• Modify fonts and text sizing
• Adjust layout for different screen sizes
• Apply responsive design for mobile/tablet access
• Place custom stylesheets in the appropriate configuration directory

---

Overview

Password reset functionality allows users to recover access to their accounts when they forget their passwords. Configuring password reset in UCR involves populating user email addresses, enabling the Forgot Password workflow on the Login App, and configuring the reset process parameters. A well-configured password reset workflow reduces help desk calls and improves user productivity.

Populating Email IDs

• Ensure all user records have valid email addresses
• Email addresses are required for email-based password reset
• Populate email during user provisioning
• For existing users, bulk update email addresses from an external source (HR system, Active Directory)
• Validate email addresses to prevent undeliverable reset links

Enabling Forgot Password Workflow

1. Access the Login App configuration 2. Enable the "Forgot Password" feature 3. Configure the password reset email template (subject, body, branding) 4. Set the reset link expiration time (how long the link is valid) 5. Configure the reset page (new password entry, complexity requirements) 6. Test the workflow with a test user account

Password Reset Process

1. User clicks "Forgot Password" on the Login App 2. User enters their username or email address 3. System sends a password reset email with a secure link 4. User clicks the link (valid for a configured time period) 5. User enters a new password meeting complexity requirements 6. System updates the password and confirms the change 7. User logs in with the new password

Security Considerations

• Link Expiration: Reset links should expire after a short period (e.g., 15-60 minutes)
• One-Time Use: Each reset link should be usable only once
• Rate Limiting: Limit the number of reset requests per time period to prevent abuse
• Password Policy: Enforce password complexity rules on reset passwords
• Password History: Prevent reuse of recent passwords
• Notification: Send confirmation email when a password is changed via reset
• Audit: Log all password reset events for security monitoring

---

Overview

UCR security configuration involves three related but distinct concepts: authentication domains, security domains, and SAML service providers. Understanding the relationships between these concepts is critical for properly configuring security in a UCR federation, especially when integrating with external identity providers. Confusion between these concepts is a common source of configuration errors.

Authentication Domain

• Defines the method by which users prove their identity
• Specifies the authentication mechanism: local, LDAP, SAML, or delegated
• Users are associated with an authentication domain (explicitly or by routing rules)
• The Login App uses the authentication domain to determine how to authenticate each user
• Multiple authentication domains can coexist in a single federation

Security Domain

• Defines a security boundary and user store
• Contains the user accounts and their associated credentials
• May map to a specific authentication domain or span multiple domains
• Controls session management, password policies, and account lockout rules
• Security domains provide the context for authorization decisions

SAML Service Provider

• Represents UCR's identity in a SAML federation with an external IdP
• Contains SP metadata (entity ID, certificates, endpoints)
• Each SAML-based authentication domain has an associated SAML Service Provider configuration
• The SP configuration determines how UCR communicates with the IdP

How They Relate

1. An authentication domain for SAML authentication references a security domain that stores user records 2. The security domain is configured with the SAML Service Provider settings for communicating with the external IdP 3. When a user authenticates via SAML:

• The authentication domain determines that SAML is the mechanism
• The SAML Service Provider configuration handles the SAML protocol exchange with the IdP
• The security domain matches the authenticated identity to a UCR user record
• The user's roles and permissions from the security domain determine their access

Configuration Sequence

1. Create the security domain (user store and security boundary) 2. Configure the SAML Service Provider (if SAML authentication is used) 3. Create the authentication domain referencing the security domain and SAML SP 4. Configure the Login App to route users to the correct authentication domain 5. Test the full authentication flow from Login App through IdP and back

Common Configuration Errors

• Mismatched Domains: Authentication domain references wrong security domain
• Missing SP Configuration: SAML authentication domain created without SAML SP configuration
• Certificate Mismatch: SP signing certificate does not match what IdP expects
• Attribute Mapping: SAML attributes from IdP do not map to UCR user properties
• User Not Found: Authenticated SAML identity cannot be matched to a UCR user record in the security domain

---