T3.2: Authorizes Users and Roles

Overview

When HealthShare delegates authentication to an external identity provider (LDAP/AD, OAuth, SAML), it must determine which HealthShare roles to assign to the authenticated user. External systems do not know about HealthShare roles directly, so a mapping layer is required to translate external identity attributes (group memberships, claims, assertion attributes) into HealthShare role assignments.

Effective role mapping ensures that users receive exactly the permissions they need based on their organizational identity, without requiring manual role assignment by HealthShare administrators.

LDAP Group-to-Role Mapping

The most common approach in enterprise environments is mapping LDAP/AD groups to HealthShare roles:

1. Identify AD Groups: Work with the AD administrator to identify or create groups that correspond to HealthShare access levels (e.g., "HS_Clinicians", "HS_Administrators", "HS_ReadOnly") 2. Retrieve Group Memberships: During authentication, query the user's memberOf attribute to get their AD group list 3. Define Mapping Table: Create a mapping that associates each AD group DN or name with one or more HealthShare roles 4. Apply Mappings: In the ZAUTHENTICATE routine or delegated authentication class, iterate through the user's groups and assign the corresponding HealthShare roles

Example mapping table:

AD Group	HealthShare Role(s)
CN=HS_Clinicians,OU=Groups,DC=hospital,DC=org	%HS_Clinician, %HS_ClinicalViewer
CN=HS_Admins,OU=Groups,DC=hospital,DC=org	%HS_Administrator, %HS_UserManager
CN=HS_LabTechs,OU=Groups,DC=hospital,DC=org	%HS_Clinician, %HS_LabViewer
CN=HS_SystemAdmins,OU=Groups,DC=hospital,DC=org	%All

AD Attribute-Based Role Assignment

Beyond group memberships, AD attributes can drive role assignment:

• Department: Assign department-specific roles (e.g., Radiology department gets radiology viewing role)
• Title/Job Function: Assign roles based on job title (e.g., "Physician" title gets prescribing role)
• Organizational Unit (OU): Use the user's OU in the directory tree to determine facility-based access
• Custom Attributes: Some organizations extend the AD schema with custom attributes for healthcare-specific role indicators

// Attribute-based role assignment in ZAUTHENTICATE
Set department = ##class(Custom.LDAPUtils).GetAttribute(username, "department")
If department = "Pharmacy" { Set roles = roles _ ",%HS_PharmacyViewer" }
Set Properties("Roles") = roles

OAuth Claim-to-Role Mapping

When using OAuth 2.0/OIDC for authentication, role information is typically conveyed through claims in the ID token or access token:

• groups claim: An array of group names or IDs the user belongs to
• roles claim: An array of application-specific role names assigned in the IdP
• scope: OAuth scopes can indicate access levels (though scopes are more commonly used for API permissions)

Mapping process: 1. Configure the IdP to include group or role claims in the token 2. In HealthShare's OAuth callback handler, extract the claims from the validated token 3. Map each claim value to the corresponding HealthShare role 4. Assign the mapped roles to the user session

SAML Attribute-to-Role Mapping

SAML assertions carry attribute statements that can include role information:

• Group attributes: The IdP includes the user's group memberships as a multi-valued attribute
• Role attributes: The IdP includes explicit role assignments as attribute values
• Custom attributes: Any attribute the IdP is configured to release can be used for role decisions

Configuration steps: 1. Configure the SAML IdP to release group or role attributes in the assertion 2. Define the attribute name (e.g., "http://schemas.xmlsoap.org/claims/Group") in HealthShare's SAML configuration 3. Create a mapping from attribute values to HealthShare roles 4. Apply the mapping during assertion processing

---

Overview

HealthShare provides a comprehensive role-based access control (RBAC) system. Roles are named collections of privileges that determine what a user can do within the system. HealthShare includes many built-in roles designed for common healthcare access patterns, and administrators can create custom roles for specialized needs.

Understanding the role system is essential for implementing proper access control in a UCR environment, where different user types (clinicians, administrators, lab technicians, system operators) require different levels of access.

Built-In Roles

HealthShare includes numerous predefined roles. Key roles include:

• %HS_Clinician: Clinical user who can view patient data in the Clinical Viewer
• %HS_Administrator: Administrative access to HealthShare management functions
• %HS_UserManager: Ability to create and manage HealthShare user accounts
• %HS_Nurse: Nursing-specific clinical access (where applicable)
• %HS_Pharmacist: Pharmacy-specific clinical access
• %HS_ClinicalViewer: Access to the Clinical Viewer web application
• %HS_DashboardUser: Access to dashboards and analytics
• %HS_RESTClient: Access to REST API endpoints
• %DB_HSLIB: Database access for HealthShare library namespace
• %All: Superuser role granting all privileges (use with extreme caution)

Role Hierarchy

Roles can include other roles, creating an inheritance hierarchy:

• A parent role automatically includes all privileges of its child roles
• For example, %HS_Administrator may include %HS_ClinicalViewer, meaning administrators automatically have clinical viewing access
• Hierarchy simplifies management: assign one role that encompasses multiple capability sets
• View the role hierarchy in the Management Portal under System Administration > Security > Roles

Assigning Roles to Users

Roles can be assigned through multiple mechanisms:

1. Management Portal: Navigate to System Administration > Security > Users, select the user, and modify their role assignments 2. Programmatic Assignment: Use ObjectScript to assign roles:

   Set user = ##class(Security.Users).%OpenId(username)
   Set user.Roles = user.Roles _ ",%HS_Clinician"
   Do user.%Save()

3. ZAUTHENTICATE: Set the Properties("Roles") output during delegated authentication 4. External Mapping: Map from LDAP groups, OAuth claims, or SAML attributes (see Section 1) 5. Matching Roles: Configure role matching rules that automatically assign roles based on user properties

Reviewing Effective Permissions

To understand what a user can actually do, review their effective permissions:

1. Navigate to System Administration > Security > Users in the Management Portal 2. Select the target user 3. View the Roles tab to see directly assigned roles 4. View the Effective Roles to see all roles including inherited ones 5. View the Privileges tab to see the cumulative set of privileges granted by all effective roles 6. Check specific resources to verify whether the user has the required access

---

Overview

While HealthShare's built-in roles cover many common access patterns, organizations frequently need custom roles that match their specific operational requirements. Custom roles allow administrators to define precisely which resources, services, and data a group of users can access, implementing the principle of least privilege.

Creating custom roles is particularly important in UCR environments where different user populations (emergency clinicians, specialists, researchers, quality reviewers, system integrators) require different data access levels.

When Custom Roles Are Needed

Common scenarios requiring custom roles:

• Departmental Access Control: Different departments need access to different subsets of patient data or features
• Research Roles: Researchers need read-only access to de-identified data without full clinical access
• Integration Roles: External system service accounts need API access without human-facing application access
• Audit Roles: Compliance officers need access to audit logs and reports without clinical data access
• Facility-Based Roles: In a multi-facility federation, restrict users to data from their home facility
• Temporary Access: Locum tenens or visiting clinicians need time-limited access to specific functions

Defining Role Privileges

To create a custom role in the Management Portal:

1. Navigate to System Administration > Security > Roles 2. Click Create New Role 3. Enter a descriptive role name (e.g., "CustomRole_EmergencyPhysician" or "CustomRole_QualityReviewer") 4. Optionally provide a description explaining the role's purpose 5. On the Resources tab, add resource privileges:

• Select each resource the role should access
• Set the permission level (Read, Write, Use)

6. On the SQL Privileges tab, add SQL-level access if needed:

• Grant SELECT on specific tables or views
• Grant EXECUTE on specific stored procedures

7. On the Member Of tab, optionally include other roles 8. Save the role

Resource-Based Permissions

HealthShare uses a resource-based permission model. Resources are named objects that protect access to specific functionality:

• Database Resources: Control access to specific namespaces and databases (e.g., %DB_HSLIB, %DB_HSCUSTOM)
• Service Resources: Control access to system services (e.g., %Service_WebGateway, %Service_Terminal)
• Application Resources: Control access to web applications (e.g., /csp/healthshare/*, /csp/healthshare/clinical/viewer)
• Custom Resources: Organization-defined resources for custom access control (e.g., "CustomResource_PatientMerge")

Permission levels for each resource:

Permission	Meaning
Read (R)	View or read the protected resource
Write (W)	Modify or write to the protected resource
Use (U)	Execute or use the protected resource (services, applications)

SQL Privileges in Roles

Roles can include SQL-level privileges for fine-grained data access control:

• SELECT: Read data from specific tables or views
• INSERT: Add new records to specific tables
• UPDATE: Modify existing records in specific tables
• DELETE: Remove records from specific tables
• EXECUTE: Run specific stored procedures

SQL privileges are particularly useful for:

• Restricting report users to read-only access on reporting views
• Allowing integration service accounts to write to specific staging tables
• Preventing unauthorized access to sensitive tables (e.g., audit logs, security configuration)

Example: A "QualityReviewer" role might grant SELECT on clinical data views but no INSERT, UPDATE, or DELETE, and no access to administrative tables.

---

Overview

HealthShare's privilege architecture is built on the InterSystems IRIS security model, which uses a resource-based access control framework. Every protected entity in the system is associated with a named resource, and privileges are grants of specific permissions (Read, Write, Use) on those resources. Roles aggregate privileges, and users receive permissions through their assigned roles.

Understanding this architecture is essential for designing a security model that properly protects patient data while enabling legitimate access for clinical and administrative users.

Database Privileges

Database privileges control access to IRIS databases, the storage containers for namespaces:

• Each database has an associated resource (e.g., %DB_HSLIB, %DB_HSSYS, %DB_HSCUSTOM)
• Read permission: Allows reading globals and running queries
• Write permission: Allows writing globals, modifying data, and creating/modifying classes
• Key database resources: %DB_HSSYS (system), %DB_HSLIB (library), %DB_HSCUSTOM (custom), %DB_IRISSYS (IRIS system), plus facility-specific databases

Service Privileges

Service privileges control access to system services (%Service_WebGateway, %Service_Terminal, %Service_Console, %Service_ODBC, %Service_Callin, %Service_ECP). They determine which connection methods a user can use. A clinical user might have WebGateway access but no Terminal access, while a system administrator might have both.

Application Privileges

Web applications in HealthShare are protected by application resources:

• Each CSP/web application can be associated with a resource
• Users must have Use permission on the application's resource to access it
• Common HealthShare web applications:
• Clinical Viewer application
• Management Portal application
• REST API endpoints
• Custom web applications

Application privileges provide the outermost layer of access control. Even if a user has database and service privileges, they cannot reach a web application without the appropriate application privilege.

Resource-Based Access Control Model

The complete access control evaluation follows this chain:

1. Service Check: Does the user have Use permission on the connection service? (e.g., %Service_WebGateway) 2. Application Check: Does the user have Use permission on the web application resource? 3. Namespace Check: Does the user have access to the target namespace's databases? 4. Data Check: Does the user have the required SQL or global-level permissions for the specific data being accessed?

If any check fails, access is denied. This layered approach provides defense in depth.

Namespace-Level Permissions

Namespace access is controlled through the database resources associated with the namespace's default globals database, routines database, and any mapped databases:

• A user needs Read on the database resource to query data in that namespace
• A user needs Write on the database resource to modify data
• HealthShare namespaces may map databases from multiple sources, requiring access to all mapped databases
• The HSLIB namespace is read-only for most users and provides shared HealthShare code

---

Overview

Implementing role-based access control (RBAC) effectively requires more than just creating roles and assigning them to users. It requires a governance framework that ensures roles are properly designed, consistently applied, regularly reviewed, and aligned with organizational security policies. In a healthcare environment, proper RBAC is critical for HIPAA compliance, patient privacy, and operational security.

Principle of Least Privilege

The principle of least privilege states that each user should have only the minimum permissions necessary to perform their job function:

• Start by identifying the specific tasks each user type performs
• Determine the minimum set of resources and permissions required for those tasks
• Create roles that grant exactly those permissions and no more
• Resist the temptation to grant broad access "just in case"
• When in doubt, start with fewer permissions and add them based on documented need

Common violations to avoid:

• Assigning %All to non-superuser accounts
• Giving write permissions when read-only is sufficient
• Granting access to all namespaces when users only need one or two
• Including administrative privileges in clinical roles

Role Naming Conventions

Consistent role naming improves manageability:

• Prefix by scope: Use prefixes to indicate the role's origin (e.g., "Custom_" for organization-defined, "HS_" for HealthShare-specific)
• Include function: Indicate the functional area (e.g., "Custom_ClinicalViewer", "Custom_LabReporting")
• Include access level: Indicate the permission level (e.g., "Custom_PatientData_ReadOnly", "Custom_PatientData_ReadWrite")
• Document the convention: Publish the naming convention so all administrators follow it consistently

Periodic Access Reviews

Regular access reviews are essential for maintaining proper RBAC:

• Frequency: Conduct reviews quarterly for high-privilege roles and annually for standard roles
• Review Process: Generate user-role reports, verify assignments match current positions, remove stale roles, identify dormant accounts, disable departed employee accounts
• Accountability: Assign a role owner (department manager or security officer) responsible for reviewing and approving role assignments
• Audit Trail: Document the review process and any changes made

Separation of Duties

Separation of duties prevents conflicts of interest and reduces the risk of unauthorized actions:

• Clinical vs. Administrative: Users who view patient data should not also modify security configurations
• Data Entry vs. Approval: Users who enter data should not approve their own entries
• System Access vs. Audit: System administrators should not have the ability to modify audit logs
• Create separate roles for each function in a separation pair and document incompatible role pairs
• Use audit logging to detect violations of separation policies

Documentation and Governance

• Role Catalog: Document all roles, their purpose, included privileges, and intended user population
• Mapping Matrix: Document which external groups/attributes map to which HealthShare roles
• Change Management: Define processes for requesting, approving, and implementing role changes
• Compliance Mapping: Document how RBAC supports HIPAA, HITECH, and organizational policies

---