Configuring SHRINE Webclient Obfuscation

{
  urlProxy: "/shrine-proxy/request",	
  urlFramework: "js-i2b2/",
  loginTimeout: 15, // in seconds
  //JIRA|SHRINE-519:Charles McGow
        username_label:"SHRINE Username:", //Username Label
        password_label:"SHRINE Password:", //Password Label
        clientHelpUrl: 'help/pdf/shrine-client-guide.pdf',
        networkHelpUrl:'help/pdf/shrine-network-guide.pdf',
        wikiBaseUrl:    'https://open.med.harvard.edu/wiki/display/SHRINE/',
        obfuscation: 10,
        resultName: "patients",
  //JIRA|SHRINE-519:Charles McGow
  // -------------------------------------------------------------------------------------------
  // THESE ARE ALL THE DOMAINS A USER CAN LOGIN TO
  lstDomains: [
                { domain: "i2b2demo",
                  name: "SHRINE",
                  urlCellPM: "http://127.0.0.1/i2b2/services/PMService/",
                  allowAnalysis: false,
                  debug: true,
                  isSHRINE: true
                }
  ]
  // -------------------------------------------------------------------------------------------
}

isQueryable = true

setSizeObfuscation = false

shrineDatabaseType = "mysql"

adapterLockoutAttemptsThreshold = 42

Durations

Durations in older parts of the code are specified as a block containing a single numeric property with a name of either milliseconds, seconds, minutes, hours, or days.  For example :

maxSignatureAge { days = 5 }

maxQueryWaitTime { minutes = 0.5 }

In 1.23 we will convert all of these blocks to a format that matches Typesafe Config and Scala Durations

maxSignatureAge = "5 days"

maxQueryWaitTime = "30 seconds"

Endpoints

Endpoints are URLs with parameters, specified as blocks with the following properties:

• url (mandatory string): the URL of the endpoint
• acceptAllCerts (optional boolean, default is false): determines whether SSL certs should be checked, or if all certs should be accepted regardless of being self-signed, expired, etc. (Useful for testing with self-signed certs).
• timeout (optional duration, default is infinity): how long should clients wait for responses from this endpoint before throwing an exception.

For example:

crcEndpoint { url = "http://example.com/i2b2" }

crcEndpoint {
  url = "http://example.com/i2b2"
  acceptAllCerts = true
  timeout { minutes = 1 }
}

Credentials

Credentials are specified as blocks with the following properties:

• domain (optional string): the user's domain, if any
• username (mandatory string): the user's username
• password (mandatory string): the user's password

For example:

sheriffCredentials {
  username = "sheriffUsername"
  password = "sheriffPassword"
}

fooCredentials {
  domain = "shrine"
  username = "foo"
  password = "bar"
}

i2b2 Hive Credentials

i2b2 hive credentials for use with a CRC or other i2b2 cell are specified as blocks with the following properties:

• domain (mandatory string): the user's i2b2 domain

• username (mandatory string): the user's username
• password (mandatory string): the user's password
• crcProjectId (mandatory string): the user's i2b2 project id for use when logging into the CRC
• ontProjectId (mandatory string): the user's i2b2 project id for use when logging into the Ontology cell

For example:

hiveCredentials {
  domain = "HarvardDemo"
  username = "demo"
  password = "demouser"
  crcProjectId = "Demo"
  ontProjectId = "SHRINE"
}

Keystore Parameters

Keystore parameters are expressed using a block with the following properties:

• file (mandatory string): the name of the keystore file on the classpath
• password (mandatory string): the keystore's passwordkeystoreType (String, default is 'JKS'): the type of the keystore.  Allowed values are 'JKS' and 'PKCS12'.
• privateKeyAlias (optional string): In the keystore, the alias of the cert with private key component used to identify this node.  The cert with this alias will be used to sign outbound queries.
• keyStoreType (optional string): A string describing the format of the keystore. Allowed values are 'JKS' and 'PKCS12'; the default is 'PKCS12'.
• caCertAliases (optional array of strings): In the keystore, the aliases, if any certs belonging to certificate authorities this node should trust

For example:

keystore {
  file = "shrine.keystore"
  password = "changethisplease"
  privateKeyAlias = "test-cert"
  keyStoreType = "PKCS12"
  caCertAliases = [shrine-ca, some-other-ca]
}

SHRINE Proxy

The SHRINE proxy is configured by a block with a single property, timeout, a duration.  Timeout specifies the amount of time the proxy should wait for a response from the url being proxied.  The default is to wait forever.

For example:

proxy {
  timeout {
    minutes = 5
  }
}

Shrine.conf Example

An example shrine.conf can be found here:

https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/commons/config/src/test/resources/shrine.conf

Shrine.conf Property Reference

• hiveCredentials (mandatory i2b2 credentials block): The credentials to use when talking to the i2b2 hive.
• pmEndpoint (mandatory endpoint block): An endpoint containing the URL of the i2b2 PM cell SHRINE should authenticate users against.
• ontEndpoint (mandatory endpoint block): An endpoint containing the URL of the i2b2 ontology cell SHRINE should communicate with.
• networkStatusQuery (mandatory string): A string representing a term from the SHRINE ontology that should be used when making test queries to verify the status of the adapter.
• humanReadableNodeName (mandatory string): A string containing the descriptive name this node should use to identify itself.
• shrineDatabaseType (mandatory string): A name identifying the type of database system used by SHRINE. (Note that this is distinct from the i2b2 db.)  Allowed values are 'mysql', 'oracle', and 'sqlserver'.
• keystore (mandatory keystore block): parameters pertaining to this node's keystore.
• adapterConfig (optional adapter config block): used if this node is an adapter.
• hubConfig (optional hub config block): used if this node is a hub (broadcaster).
• queryEntryPointConfig (optional entry point config block): used if queries can originate from this node.
• proxyConfig (optional proxy config block): optionally used to configure the SHRINE proxy.
• breakdownResultOutputTypes (optional block): describes breakdown result output types; must match i2b2

Adapter Config

If a node is an adapter, add an adapter block to shrine.conf:

adapter {
  create = true 
  ...
}

Adapter Config Property Reference

• create (boolean, default is true): true to create an adapter at this node.
• crcEndpoint (optional endpoint block): the location of the i2b2 CRC this SHRINE node should run queries against, if this node is queryable.
• setSizeObfuscation (mandatory boolean): should this node obfuscate results obtained from the CRC.
• adapterLockoutAttemptsThreshold (mandatory integer): How many times should a user be able to run the same query in the recent past before they are prevented from making further queries.
• adapterMappingsFileName (mandatory string): The name of a file on the classpath that SHRINE should load to obtain mappings between terms in the SHRINE and local i2b2 ontologies.  Usually, this is called 'AdapterMappings.xml'.
• maxSignatureAge (mandatory duration): The length of time the signature on an incoming query should be considered valid.  Queries with signatures older than this value will be rejected.
• auidit.database.slickProfileClassName (A Slick driver class name. One of "slick.driver.MySQLDriver$", "freeslick.OracleProfile$", or "freeslick.MSSQLServerProfile$" . Default is "slick.driver.MySQLDriver$" .): The name of the appropriate Slick driver for your JDBC driver.

For example:

 adapter {
    crcEndpoint {
      url = "http://services.i2b2.org/i2b2/rest/QueryToolService/"
      acceptAllCerts = true
      timeout {
        seconds = 1
      }
    }
    
    setSizeObfuscation = true
    
    adapterLockoutAttemptsThreshold = 10

    adapterMappingsFileName = "AdapterMappings.xml"
    
    maxSignatureAge {
      minutes = 5
    }
  }

Hub (Broadcaster) Config

If a node is a hub (broadcaster), add a hub block to shrine.conf:

hub {
  create = true
  ...
}

Hub Config Property Reference

• create (boolean, default is false): true to create a hub at this node.
• maxQueryWaitTime (mandatory duration): When querying, how long to wait for results from all downstream nodes before timing out.
• downstreamNodes (optional downstream node block): a mapping of node names to URLs of downstream nodes.  Nodes in this mapping will have queries broadcast to them.  If this property is omitted, the node will not broadcast queries to any other nodes.
• shouldQuerySelf (optional boolean, default is false): If this value is true, the node will proadcast to itself.

For example:

 hub {
    create = true
    maxQueryWaitTime {
      minutes = 4.5
    }
    
    downstreamNodes {
      "some hospital" = "http://example.com/foo"
      CHB = "http://example.com/chb"
      PHS = "http://example.com/phs"
    }
    
    shouldQuerySelf = true
  }

Query Entry Point Config

If a node is an entry point—a node that can receive queries from a web UI and perform them on the network—add a queryEntryPoint block to shrine.conf:

queryEntryPoint {
  create = true
  ...
}

Query Entry Point Config Reference

• create (boolean, default is true): true to create a query entry point at this node.
• authenticationType (optional authentication type, default is "pm"): Describes how the query entry point should authenticate incoming queries
• authorizationType (optional authorization type, default is "none"): Describes how the query entry point should perform additional authorization of incoming queries.
• sheriffEndpoint (optional endpoint block, HMS only): the location of the Shrine Sheriff application to use for authorizing users.
• sheriffCredentials (optional credentials block, HMS only): the credentials to use when authenticating with the Sheriff application, if applicable.
• includeAggregateResults (mandatory boolean): Should this node include an aggregate result with total counts.  In the past, this has been false.
• maxQueryWaitTime (mandatory duration): When querying, how long to wait for results from the hub (broadcaster) before timing out.
• broadcasterServiceEndpoint (optional endpoint): An optional endpoint containing the URL of the remote hub (broadcaster) to submit queries to.  If this property is omitted, a local broadcaster is used.
• attachSigningCert (optional boolean): An optional boolean describing whether the cert used to sign outgoing queries should be attached to the outbound query.  If this value is true, the cert used to sign outbound queries must be signed by a certificate authority that is trusted by the adapters that will receive the query.  The default value is false.
• auidit.database.slickProfileClassName (A Slick driver class name. One of "slick.driver.MySQLDriver$", "freeslick.OracleProfile$", or "freeslick.MSSQLServerProfile$" Default is "slick.driver.MySQLDriver$"): The name of the appropriate Slick driver for your JDBC driver.

Authentication types

• "ecommons" (only usable by nodes on the HMS deployment of Shrine): authenticates users against an i2b2 PM and checks that users have a property specifying a Harvard ecommons username)
• "pm": authenticates users against an i2b2 PM
• "none": no authentication of incoming queries is performed

Note: the "ecommons" and "pm" authentication schemes will use the i2b2 PM described by the shrine.pmEndpoint property.

Authorization types

• "shrine-steward": use the SHRINE Data Steward introduced in SHRINE 1.19.x. Requires deployment and configuration of steward.war as well as Tomcat 7 or newer. The shrineSteward block in shrine.conf must also be set up properly.
• "hms-steward" (only usable by nodes on the HMS deployment of Shrine): use a data steward (Sheriff) instance to authorize incoming queries.  For this to work, the sheriffEndpoint and sheriffCredentials properties must be set.
• "none": Don't perform additional authorization of incoming queries.

Note: the "hms-steward" authorization type is compatible ONLY with the "ecommons" authentication type.

For example:

 queryEntryPoint {

   authenticationType = "pm"

   authorizationType = "shrine-steward"

// BEGIN properties for hms-steward
//   sheriffEndpoint {
//      url = "http://localhost:8080/shrine-hms-authorization/queryAuthorization"
//      acceptAllCerts = true
//      timeout {
//        seconds = 1
//      }
//    }
//    
//    sheriffCredentials {
//      username = "sheriffUsername"
//      password = "sheriffPassword"
//    }
// END properties for hms-steward
 
// BEGIN properties for shrine-steward
      shrineSteward {
        qepUserName = "qep" // name of user the steward will submit queries as
        qepPassword = "trustme"
        stewardBaseUrl = "https://localhost:6443" // typically hostname+port of Tomcat server running steward.war
      }
// END properties for shrine-steward
    
    includeAggregateResults = false
    
    maxQueryWaitTime {
      minutes = 5
    }
    
    broadcasterServiceEndpoint {
      url = "http://example.com/shrine/rest/broadcaster/broadcast"
      acceptAllCerts = true
      timeout {
        seconds = 1
      }
    }
    
    attachSigningCert = true
 }

Breakdown Result Output Types Config

As of Shrine 1.18.0+, it is required to specify the names of result types corresponding to breakdown queries.  There names must match the names of result output types defined in the i2b2 DB of every node on your Shrine network.  For example, on a network comprised of nodes backed by i2b2 demo VMs, add this to shrine.conf:

shrine {
  ...
 
  breakdownResultOutputTypes {
    PATIENT_AGE_COUNT_XML {
      description = "Age patient breakdown"
    }
      
    PATIENT_RACE_COUNT_XML {
      description = "Race patient breakdown"
    }
 
    PATIENT_VITALSTATUS_COUNT_XML {
      description = "Vital Status patient breakdown"
    }
 
    PATIENT_GENDER_COUNT_XML {
      description = "Gender patient breakdown"
    }
  }
 
  ...
}

the format is

breakdownResultOutputTypes {
  <breakdown-result-output-type-name 0> {
    description = <string human-readable-description 0>
  }
  ...
  <breakdown-result-output-type-name N> {
      description = <string human-readable-description N>
  }
}

note that shrine.breakdownResultOutputTypes can contain 0 or more child elements.

Since this breakdown result output type information will be shared by many nodes on a network, it's also possible to define it in its own file, breakdowns.conf, which can be shared among sites without revealing URLs or credentials.  That file should contain only the enclosing shrine { ... } block and the breakdownResultOutputTypes {... } block, like

shrine {
  breakdownResultOutputTypes {
    PATIENT_AGE_COUNT_XML {
      description = "Age patient breakdown"
    }
      
    PATIENT_RACE_COUNT_XML {
      description = "Race patient breakdown"
    }
 
    PATIENT_VITALSTATUS_COUNT_XML {
      description = "Vital Status patient breakdown"
    }
 
    PATIENT_GENDER_COUNT_XML {
      description = "Gender patient breakdown"
    }
  }
}

If breakdowns.conf is present and no shrine.breakdownResultOutputTypes block is defined in shrine.conf, values from breakdowns.conf will be used.