STSSettings

These parameters will be used to configure the behaviour of the STS application or provide global parameters that can complete the SAML token in scenarios where the source application or a directory cannot provide the required parameters.

Where operation or settings differ from v1.7 it will be clearly stated.

 

Version

This value indicates the version of the STS solution.

 

ConfigurationDatabase

Provides the location for the configuration database for Orbital STS Lite (STS Version 1.9 and greater).

 

SAMLSpecificationVersion

This value indicates which SAML Specification is used when generating the SAML assertion.  Accepted values are:

• For ConnectingOntario/ConnectingGTA:
  • connectinggtav1 – original specification (default), generates SAML in ConnectingGTA SAML v0.1 format
  • connectinggtav1.1 - generates SAML in ConnectingGTA SAML v0.2 format
  • connectinggtav1.2 - generates SAML in ConnectingGTA SAML v0.2 format with mandatory RID attributes
  • connectinggtav1.3 – ConnectingGTA SAML v0.2 format original specification with multi-UAO value modifier
  • ehealthontario141 - generates eHealth Ontario SAML 1.4 format (STS Version 1.8 and greater)
  •  ehealthontario15 - generates eHealth Ontario SAML 1.5 format (STS Version 1.9 and greater)
  • telus14 - parses comma-delimited UAO values from input, and generates eHealth Ontario SAML 1.4 format (STS Version 1.8 and greater)
• salesforcev1 - general OAuth/SAML SalesForce SAML specifications (STS Version 1.91 and greater)
• adfs - standard default Active Directory Federation Services SAML assertions (STS Version 1.92 and greater)
• qhn - Quality Health Network (STS Version 1.93 and greater)
• cchie - Clinical Connect HIE (STS Version 1.93 and greater)
• crisp - State Designated Health Information Exchange (HIE) for Maryland (STS Version 1.94 and greater)
• ethin -  East Tennessee Health Information Network (STS Version 1.94 and greater)

 

SessionExpiry

This parameter sets the time limit (in minutes) under which the HIS-generated request is valid.  This should be set to a reasonable amount (e.g. 60 minutes) to ensure that an unauthorized party cannot replay an old request.

 

TokenTimeSpan

This parameter sets the SAML Token parameters NotBefore (Current Time – TokenTimeSpan) and NotOnOrAfter (Current Time + TokenTimeSpan).  It is recommended that this time be set to 10 minutes or less.  Consideration should be given to any potential discrepancy in system clocks or response times between systems.

 

ClearSession

 

STS Version 1.94 and greater. This parameter indicates if the STS should purge the session object (and expire the associated cookie) once the user is re-directed to the Service Provider.  This impacts primarily users that are authenticated with UserContextModes 4 and 5 as the authentication process is a two-step process and the session is used to store user information temporarily.

 

Key

This parameter sets the global secret that will be used for UserContextMode 2.

 

Debug

This parameter will activate the debug mode in STS.  It will provide extended auditing in the Audit file.  Please note that this should not be enabled on the Production server as the file size will increase very quickly.

 

PrimaryADGroupCheck

STS Version 1.94 and greater. This parameter will enable checking for the "Domain Users" primary group nested within a group that has been assigned permission in STS. Note that this is an expensive recursive check that does not use the default .NET directory searcher or identity principal objects which do not return members of a primary group. 

 

SanitizeLog

STS Version 1.9 and greater. Specifies if the STS should sanitize patient context attributes in the audit and operation logs.

The values are:

• 0 - don’t log any patient attributes
• 1 - store patient attributes hashed with a salt as set in SanitizeSalt; hash(attribute +salt)
• 2 - store only last two characters of the attributes; note that for Gender the single character will be captured in its entirety
• 3 - store all patient attributes unchanged (not recommended for PHI)

 

SanitizeSalt

STS Version 1.9 and greater. String to be used to hash patient attributes in logs (if SantizeLog value is set to “1”)

 

EnableFriendlyUserError

This attribute specifies if the user will see a customized error page (specified in “FriendlyErrorURL”). It is recommended that the user not see the extended debugging messages as this may expose information that can be manipulated to gain unauthorized access.  Enabling customized errors will not have an impact on the ability to log errors or debug so the administrator can still refer to the log files to obtain detailed error information.  For environments that provide access to PHI, this should be disabled.

 

FriendlyErrorURL

The URL that will display an error message.  This can be the provided HTML page (“NiceError.html”) or any alternate URL.

 

EnableHashDisplay

When debugging (i.e. Debug is set to “true”) the SHA256 hash used in UserContextModes 1 and 2 that should be used is displayed for troubleshooting and convenience purposes.  This can potentially grant an unauthorized party access.  It is recommended that this is set to “false” once the integration and testing efforts have been completed.

 

IncludeBlankSAMLAttributes

This attribute will determine if SAML attributes that are blank or null will be omitted when the SAML Assertion is generated.  This is implemented for systems that require all attributes to be provided regardless of their validity or content.

 

QueryStringRequestsAllowed

This parameter will enable/disable the ability of the STS solution to process GET requests.  In this scenario, all values are submitted as a QueryString as part of the URL that the application will parse.

 

EncryptSAMLAttributes

This parameter will specify if the SAML attributes sent to Service Providers will be encrypted using the their provided public key. The certificate to be used will be specified in the “SAMLConfiguration” section.

Since STS Version 1.8 and greater this flag cannot be overriden in the “SAMLConfiguration” section.

 

NameIDCase

Indicates which string modification will be applied to the NameID value provided by the HIS before being used in the SAML token.  Accepted values are:

• none – value will not be modified (default)
• lower – value will be converted to lower-case
• upper – value will be converted to upper-case

 

 

EnablePatientContextNames

STS Version 1.71 and greater. This parameter will specify if the PatientContextLastNames must and that the PatientContextFirstName be included as part of the values to validate the healthcard number.   This value should be set to “true”.

 

CertificateValidationEnabled

This defines if the STS solution will check the validity of the certificate as per the period defined in “CertificateValidationFrequency”.  It is recommended, for the Production Environment, that this check is enabled.

 

CertificateValidationFrequency

Specifies the time (in minutes) after which the certificate verification is skipped.  This is only applicable to the certificate used to sign the SAML token.  Due to potential performance impacts in accessing external systems, it is recommended that this value is not set too low (i.e. less than 5 minutes).

 

CertificateValidationCRLEnabled

This defines if the STS solution will validate that the certificate is still valid with the external service that provides the Certificate Revocation List (CRL).  It is recommended, for the Production Environment, that this check is enabled.

 

CertificateValidationCRLTimeOut

The maximum duration (in seconds) of CRL check until time out.  Note that this value may need to be increased if a third party with a significant CRL does not respond fast enough with necessary information.

 

EnableFormsAuthentication

This parameter specifies if the Forms-based authentication is used when the Windows Integrated Authentication option fails. 

 

FormAuthentication

This parameter specifies the URL of the login page that will be used to authenticate users in UserMode4.   This value should not be altered.

 

FormLoginPageTitle

The title of the HTML title page that should appear on the Forms Login Page.

 

FormLoginPageImage

The image URL that should appear on the page.

 

FormLoginPageMessage

The message that should appear at the top of the page.

 

FormLoginPageUsername

The label that should preface the field where the username is entered.

 

FormLoginPagePassword

The label that should preface the field where the password is entered.

 

FormLoginPageButton

The text that should appear on the form submit button.

 

FormLoginPageMessage2

An additional message that should appear at the bottom of the page. This can be left blank.

 

AssertingParty

This parameter identifies the originating STS server and should be a fully qualified domain. It is preferred that individual STS servers, rather than clusters, be identified.

 

AudienceRestriction

This parameter identifies the default domain that will consume the SAML token.  This should be set to the FQD of the organization.

 

URL

The SAML token will provide this URL in order when identifying the STS Solution.  This should be the URL that the HIS/EMR application links to.

 

Service

This parameter identifies the default service that will receive SAML assertions from the STS Solution (it should matche a value in SAMLConfiguration section of the STS Solution). 

 

OrganizationName

This value is used to generate the metadata file and should provide the name of the organization for which the STS Solution is generating SAML assertions.  This can be the organization’s legal name. Note that version 1.7 has a typo in this attribute; OrganizatioName! This was corrected in v1.71 onwards.

 

OrganizationContactName

This value is used to generate the metadata file and should provide the name of the individual (or role) that is the primary owner of, or operational support for, the STS Solution.

 

OrganizationContactEmail

This value is used to generate the metadata file and should provide the e-mail address of the individual (or role) that is the primary owner of, or operational support for, the STS Solution.

 

UserNameSpace

This is the Uniform Resource Namespace (URN) that all SAML user attributes should use.

 

PatientNameSpace

This is the Uniform Resource Namespace (URN) that all SAML patient context attributes should use.

 

ClinicalNameSpace

Specifies the namespace that will be prefixed to all clinical context attributes.

 

ServerAvailabilityCheck

Specifies if the STS application should check for the availability of a directory server used in “RoundRobin” and “Random” modes.  If the server is unavailable, it will attempt to obtain an alternate value.

 

ServerAvailabilityRetries

Specifies the number of attempts to retrieve an alternate server set in “RoundRobin” or “Random” modes before returning a value (which may be unavailable and cause an error).

 

SMTPHost

The IP address or DNS name of the SMTP gateway that will be used to send e-mail alerts.

 

SMTPPort

The TCP port that should be used to send SMTP e-mails.  This is typically TCP port 25.

 

SMTPAvailable

A value of “true” or “false” indicating if STS should use the server to send e-mail alerts.  Setting it to “false” will disable the e-mail functionality for alerts.

 

SMTPTimeout

The amount of time (in seconds) that the STS solution will wait before it times out and indicates an error, resulting in an SMTP e-mail message.

 

SMTPUseSSL

Attribute set to “true” or “false” indicating if the SMTP expects the transmission and authentication to use SSL or TLS.

 

SMTPUsername

The username that should be used for SMTP gateways that require authentication. If none is required, then the username should be blank.

 

SMTPPassword

The password that should be used for SMTP gateways that require authentication. This is ignored if the username is blank.

 

SMTPRecipient

The e-mail address of the intended recipient of the e-mail message.

 

SMTPFrom

The e-mail address of the sender of the message.  Please note that some SMTP servers will not relay a message unless the “From” address is from an accepted domain name.

 

SPMLTracking

This will control the SPML functionality in the STS solution and allow the service to trigger ConnectingGTA Provider Registry changes when user info changes.  This value can be set as “false” to simplify the deployment.

 

SPMLModifiers

Allows the administrator to disable AddRequest or ModifyRequests in the SPML component.  Accepted values are:

• “disableAddRequest” – the SPML component will not trigger SPML requests for new users
• “disableModifyRequest” – the SPML component will not trigger SPML requests for users who have had their information modified
• “disableAddRequest,disableModifyRequest” – this disabled both types of requests

 

 

SPMLTrackingSalt

Instead of storing user attributes in a database, the SPML component stores hashes.  In order to complicate the potential use of rainbow tables to determine the actual values, an additional values is hashed with each attribute.  This can be any random sequence of characters and/or numbers.

 

SPMLTrackingDatabase

This specifies the local SQLite database that the SPML component should use to store the hashes.

 

SPMLDatabaseConnection

For environments that wish to use a central MSSQL database (especially where multiple STS instances exist), the connection string can be provided here.  Note that the SPMLTrackingDatabase value should be null (“”) for this value to be in effect.

 

DoSClientThreshold

This parameter is used to prevent Denial of Service attacks on both the STS and the Service Provider.  This sets the threshold of how many requests one single system (on an unique IP address) can generate within a certain amount of time (see DoSClientPeriod).

 

DoSClientPeriod

This parameter is used to prevent Denial of Service attacks on both the STS and the Service Provider. This sets the length of time until the STS counter for a client system is reset.  This value is expressed in minutes.

 

DoSUserThreshold

This parameter is used to prevent Denial of Service attacks on both the STS and the Service Provider.  This sets the threshold of how many requests one single user (determined by the NameID) can generate within a certain amount of time (see DoSUserPeriod).

 

DoSUserPeriod

This parameter is used to prevent Denial of Service attacks on both the STS and the Service Provider. This sets the length of time until the STS counter for a specific user is reset.  This value is expressed in minutes.

 

ValidateEachPerson

STS Version 1.8 and greater. In scenarios where the users provides their own UAO (single clinical practice) setting this value to false will bypass the UAO validation.

 

Example STSSettings Section

<STSSettings Version="v1.93" ConfigurationDatabase="~/App_Data/Orbital.sqlite" SAMLSpecificationVersion="qhn1" SessionExpiry="60" TokenTimeSpan="10" Key="UATSTSSecret" Debug="true" SanitizeLog="2" SanitizeSalt="6377836388" EnableFriendlyUserError="false" FriendlyErrorURL="~/NiceError.html" EnableHashDisplay="true" IncludeBlankSAMLAttributes="true" AssertingParty="sts.grhd.org" AudienceRestriction="grhd.org" Service="QHNTest" URL="https://oursts.internal.hospital.on.ca" OrganizationName="Participating Hospital in ConnectingGTA" OrganizationContactName="Emmanuel Goldstein" OrganizationContactEmail="Emmanuel.Goldstein@hospital.on.ca" EnableFormAuthentication="true" FormAuthentication="~/FormLogin.aspx" FormLoginPageTitle="QHN Login Page" FormLoginPageImage="~/images/sts_banner.jpg" FormsLoginPageMessage="Please enter your username and password." FormsLoginPageUsername="Username:" FormsLoginPagePassword="Password:" FormsLoginPageButton="Log In to ConnectingGTA" FormsLoginPageMessage2="Please contact the Service Desk for support." QueryStringRequestsAllowed="true" EncryptSAMLAttributes="false" NameIDCase="none" EnablePatientContextNames="true" CertificateValidationEnabled="false" CertificateValidationFrequency="120" CertificateValidationCRLEnabled="false" CertificateValidationCRLTimeOut="10" CertificateOverride="encryption" UserNamespace="" PatientNamespace="" ClinicalNamespace="" ServerAvailabilityCheck="true" ServerAvailabilityRetries="2" SMTPAvailable="false" SMTPHost="mail.hospital.on.ca" SMTPPort="25" SMTPTimeout="5" SMTPUseSSL="false" SMTPUsername="" SMTPPassword="" SMTPRecipient="monitoring@hospital.on.ca" SMTPFrom="qhn-sts@hospital.on.ca" SPMLTracking="true" SPMLModifiers="disableAddRequest" SPMLTrackingSalt="ThisIsAVeryComplexString73527352" SPMLTrackingDatabase="~/App_Data/CGTA_STS.sqlite" SPMLDBConnection="" DoSClientThreshold="1001" DoSClientPeriod="61" DoSUserThreshold="101" DoSUserPeriod="61" ValidateEachPerson="false">