Merged in apikey (pull request #16)

CC-3383: Update cql-services to support API keys for authentication

Approved-by: Chris Moesel

README.md

@@ -45,16 +45,30 @@ To use this project in a development environment, you should perform the followi
 
 The CQL Services require a free Unified Medical Language System (UMLS) account from the National Library of Medicine (NLM).  If you do not yet have an account, [sign up here](https://uts.nlm.nih.gov//license.html).
 
-Once you have your NLM credentials, you must assign them to the `UMLS_USER_NAME` and `UMLS_PASSWORD` environment variables.
+Once you have your NLM credentials, you must assign your API Key to the `UMLS_API_KEY` environment variable.  Your API Key may be found in your [UMLS Profile](https://uts.nlm.nih.gov//uts.html#profile).
+
+Alternatively, you may set the `UMLS_USER_NAME` and `UMLS_PASSWORD` environment variables.  If all three environment variables are present, the `UMLS_API_KEY` will be used.
+
+**NOTE:** As of January 1 2021, NLM will no longer accept username and password for authentication.  You MUST use an API Key to download value sets from VSAC after this date.
 
 Mac/Linux:
 ```
+$ export UMLS_API_KEY=myapikey
+```
+
+Alternative Mac/Linux (deprecated, expires Jan 1 2021):
+```
 $ export UMLS_USER_NAME=myusername
 $ export UMLS_PASSWORD=mypassword
 ```
 
 Windows:
 ```
+> set UMLS_API_KEY=myapikey
+```
+
+Alternative Windows (deprecated, expires Jan 1 2021):
+```
 > set UMLS_USER_NAME=myusername
 > set UMLS_PASSWORD=mypassword
 ```
@@ -206,15 +220,21 @@ $ docker build -t cql-services .
 
 To ceate and run a `cql-services` container:
 ```
+$ docker run --name cql-services -d -p "3000:3000" -e "UMLS_API_KEY=myKey" -e "CQL_SERVICES_MAX_REQUEST_SIZE=2mb" -v /data/cql-services/config:/usr/src/app/config cql-services:latest
+```
+
+Alternatively, you may pass UMLS user name and password credentials (deprecated, expires Jan 1 2021):
+```
 $ docker run --name cql-services -d -p "3000:3000" -e "UMLS_USER_NAME=myUser" -e "UMLS_PASSWORD=myPass" -e "CQL_SERVICES_MAX_REQUEST_SIZE=2mb" -v /data/cql-services/config:/usr/src/app/config cql-services:latest
 ```
 
 * `docker run` creates and runs a new container based on the requested image.
 * `--name cql-services` gives the container a name by which it can be referred to via other Docker commands.
 * `-d` indicates that the container should run as a daemon (instead of blocking the current thread).
 * `-p "3000:3000"` indicates that port 3000 of the container should be mapped to port 3000 of the host.  Without this, the service is not accesible outside the container.
-* `-e "UMLS_USER_NAME=myUser"` passes the UMLS user name as an environment variable.  This is required to download value sets for execution.
-* `-e "UMLS_PASSWORD=myPass"` passes the UMLS password as an environment variable.  This is required to download value sets for execution.
+* `-e "UMLS_API_KEY=apiKey"` passes the UMLS API Key as an environment variable.  This is required, and the preferred credential to download value sets for execution.
+* `-e "UMLS_USER_NAME=myUser"` **DEPRECATED** passes the UMLS user name as an environment variable.  This is required to download value sets for execution.
+* `-e "UMLS_PASSWORD=myPass"` **DEPRECATED** passes the UMLS password as an environment variable.  This is required to download value sets for execution.
 * `-e "CQL_SERVICES_MAX_REQUEST_SIZE=2mb"` passes the max request size allowed as an environment variable.  This flag is optional and defaults to 1mb if not passed in.
 * `-v /data/cql-services/config:/usr/src/app/config` maps the host's `/data/cql-services/config` folder as a read-only volume in the container.  This allows the CQL and Hooks configs to be configured on the host and persist across container upgrades.
 * `cql-services:latest` indicates the image name (`cql-services`) and tag (`latest`) to run.

package.json

@@ -22,7 +22,7 @@
     "cookie-parser": "~1.4.3",
     "cors": "^2.8.4",
     "cql-exec-fhir": "^1.3.1",
-    "cql-exec-vsac": "^1.1.1",
+    "cql-exec-vsac": "^1.2.0",
     "cql-execution": "^1.3.8",
     "debug": "~2.6.0",
     "express": "^4.16.3",

routes/api/library.js

@@ -6,6 +6,7 @@ const fhir = require('cql-exec-fhir');
 const csLoader = require('../../lib/code-service-loader');
 const libsLoader = require('../../lib/libraries-loader');
 const router = express.Router();
+const process = require('process');
 
 // Establish the routes
 router.get('/:library', resolver, get);
@@ -71,8 +72,11 @@ function valuesetter(req, res, next) {
   // If the calling library has valuesets, crosscheck them with the local
   // codeservice. Any valuesets not found in the local cache will be
   // downloaded from VSAC.
-  csLoader.get().ensureValueSetsInLibrary(library)
-    .then( () => next() )
+  // Use of API Key is preferred, as username/password will not be supported on Jan 1 2021
+  const ensureValueSets = process.env['UMLS_USER_NAME'] && !process.env['UMLS_API_KEY']
+    ? csLoader.get().ensureValueSetsInLibrary(library)
+    : csLoader.get().ensureValueSetsInLibraryWithAPIKey(library);
+  ensureValueSets.then( () => next() )
     .catch( (err) => {
       logError(err);
       if (req.app.locals.ignoreVSACErrors) {

routes/cds-services.js

@@ -9,6 +9,7 @@ const isPlainObject = require('lodash/isPlainObject');
 const csLoader = require('../lib/code-service-loader');
 const hooksLoader = require('../lib/hooks-loader');
 const libsLoader = require('../lib/libraries-loader');
+const process = require('process');
 
 // Middleware to setup response headers with CORS
 router.use((request, response, next) => {
@@ -98,9 +99,12 @@ function valuesetter(req, res, next) {
   // If the calling library has valuesets, crosscheck them with the local
   // codeservice. Any valuesets not found in the local cache will be
   // downloaded from VSAC.
-  csLoader.get().ensureValueSetsInLibrary(library)
-    .then( () => next() )
-    .catch( (err) => {
+  // Use of API Key is preferred, as username/password will not be supported on Jan 1 2021
+  const ensureValueSets = process.env['UMLS_USER_NAME'] && !process.env['UMLS_API_KEY']
+    ? csLoader.get().ensureValueSetsInLibrary(library)
+    : csLoader.get().ensureValueSetsInLibraryWithAPIKey(library);
+  ensureValueSets.then(() => next())
+    .catch((err) => {
       logError(err);
       if (req.app.locals.ignoreVSACErrors) {
         next();

yarn.lock

@@ -432,15 +432,15 @@ cql-exec-fhir@^1.3.1:
   dependencies:
     xml2js "~0.4.19"
 
-cql-exec-vsac@^1.1.1:
-  version "1.1.1"
-  resolved "https://registry.yarnpkg.com/cql-exec-vsac/-/cql-exec-vsac-1.1.1.tgz#2ba2e9cae923f896292c86148fe6668ecc0afef4"
-  integrity sha512-yggzgTqYW5uAfvfhlB16lHgfQFLOqm8rL80hCZ6whmllgBCeRoXBpg6paHCCo91RC4JK29leu5OVdcqv9dTU3w==
+cql-exec-vsac@^1.2.0:
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/cql-exec-vsac/-/cql-exec-vsac-1.2.0.tgz#1243d639b8185d94ed2d323527e0b0a99482cf5f"
+  integrity sha512-98CMTxZOa4pcQEK8tL8p6iBHjCphItWj2/vHqd99vksOkWanbS/5JGdYJTg//i0nJa2Ck7Gk8dDbm7qzlaMHGw==
   dependencies:
-    debug "^4.1.1"
-    mkdirp "^1.0.3"
+    debug "^4.2.0"
+    mkdirp "^1.0.4"
     request "^2.88.2"
-    request-promise-native "^1.0.8"
+    request-promise-native "^1.0.9"
     xml2js "^0.4.23"
 
 cql-execution@^1.3.8:
@@ -484,13 +484,20 @@ [email protected], debug@^3.1.0:
   dependencies:
     ms "2.0.0"
 
-debug@^4.0.1, debug@^4.1.1:
+debug@^4.0.1:
   version "4.1.1"
   resolved "https://registry.yarnpkg.com/debug/-/debug-4.1.1.tgz#3b72260255109c6b589cee050f1d516139664791"
   integrity sha512-pYAIzeRo8J6KPEaJ0VWOh5Pzkbw/RetuzehGM7QRRX5he4fPHx2rdKMB256ehJCkX+XRQm16eZLqLNS8RSZXZw==
   dependencies:
     ms "^2.1.1"
 
+debug@^4.2.0:
+  version "4.2.0"
+  resolved "https://registry.yarnpkg.com/debug/-/debug-4.2.0.tgz#7f150f93920e94c58f5574c2fd01a3110effe7f1"
+  integrity sha512-IX2ncY78vDTjZMFUdmsvIRFY2Cf4FnD0wRs+nQwJU8Lu99/tPFdb0VybiiMTPe3I6rQmwsqQqRBvxU+bZ/I8sg==
+  dependencies:
+    ms "2.1.2"
+
 decamelize@^1.0.0:
   version "1.2.0"
   resolved "https://registry.yarnpkg.com/decamelize/-/decamelize-1.2.0.tgz#f6534d15148269b20352e7bee26f501f9a191290"
@@ -1172,7 +1179,7 @@ levn@^0.3.0, levn@~0.3.0:
     prelude-ls "~1.1.2"
     type-check "~0.3.2"
 
-lodash@^4.17.11, lodash@^4.17.15, lodash@^4.17.4:
+lodash@^4.17.11, lodash@^4.17.15, lodash@^4.17.19, lodash@^4.17.4:
   version "4.17.15"
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.15.tgz#b447f6670a0455bbfeedd11392eff330ea097548"
   integrity sha512-8xOcRHvCjnocdS5cpwXQXVzmmh5e5+saE2QGoeQmbKmRS6J3VQppPOIt0MnmE+4xlZoumy0GPG0D0MVIQbNA1A==
@@ -1244,10 +1251,10 @@ [email protected], mkdirp@^0.5.1:
   dependencies:
     minimist "0.0.8"
 
-mkdirp@^1.0.3:
-  version "1.0.3"
-  resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-1.0.3.tgz#4cf2e30ad45959dddea53ad97d518b6c8205e1ea"
-  integrity sha512-6uCP4Qc0sWsgMLy1EOqqS/3rjDHOEnsStVr/4vtAIK2Y5i2kA7lFFejYrpIyiN9w0pYf4ckeCYT9f1r1P9KX5g==
+mkdirp@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-1.0.4.tgz#3eb5ed62622756d79a5f0e2a221dfebad75c2f7e"
+  integrity sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==
 
 mocha@^5.2.0:
   version "5.2.0"
@@ -1288,7 +1295,7 @@ [email protected]:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.1.tgz#30a5864eb3ebb0a66f2ebe6d727af06a09d86e0a"
 
-ms@^2.1.1:
+ms@2.1.2, ms@^2.1.1:
   version "2.1.2"
   resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.2.tgz#d09d1f357b443f493382a8eb3ccd183872ae6009"
   integrity sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==
@@ -1600,19 +1607,19 @@ repeat-string@^1.5.2:
   version "1.6.1"
   resolved "https://registry.yarnpkg.com/repeat-string/-/repeat-string-1.6.1.tgz#8dcae470e1c88abc2d600fff4a776286da75e637"
 
-[email protected].3:
-  version "1.1.3"
-  resolved "https://registry.yarnpkg.com/request-promise-core/-/request-promise-core-1.1.3.tgz#e9a3c081b51380dfea677336061fea879a829ee9"
-  integrity sha512-QIs2+ArIGQVp5ZYbWD5ZLCY29D5CfWizP8eWnm8FoGD1TX61veauETVQbrV60662V0oFBkrDOuaBI8XgtuyYAQ==
+[email protected].4:
+  version "1.1.4"
+  resolved "https://registry.yarnpkg.com/request-promise-core/-/request-promise-core-1.1.4.tgz#3eedd4223208d419867b78ce815167d10593a22f"
+  integrity sha512-TTbAfBBRdWD7aNNOoVOBH4pN/KigV6LyapYNNlAPA8JwbovRti1E88m3sYAwsLi5ryhPKsE9APwnjFTgdUjTpw==
   dependencies:
-    lodash "^4.17.15"
+    lodash "^4.17.19"
 
-request-promise-native@^1.0.8:
-  version "1.0.8"
-  resolved "https://registry.yarnpkg.com/request-promise-native/-/request-promise-native-1.0.8.tgz#a455b960b826e44e2bf8999af64dff2bfe58cb36"
-  integrity sha512-dapwLGqkHtwL5AEbfenuzjTYg35Jd6KPytsC2/TLkVMz8rm+tNt72MGUWT1RP/aYawMpN6HqbNGBQaRcBtjQMQ==
+request-promise-native@^1.0.9:
+  version "1.0.9"
+  resolved "https://registry.yarnpkg.com/request-promise-native/-/request-promise-native-1.0.9.tgz#e407120526a5efdc9a39b28a5679bf47b9d9dc28"
+  integrity sha512-wcW+sIUiWnKgNY0dqCpOZkUbF/I+YPi+f09JZIDa39Ec+q82CpSYniDp+ISgTTbKmnpJWASeJBPZmoxH84wt3g==
   dependencies:
-    request-promise-core "1.1.3"
+    request-promise-core "1.1.4"
     stealthy-require "^1.1.1"
     tough-cookie "^2.3.3"