Merge pull request #831 from watson-developer-cloud/load-creds-from-file

Load creds from file

Author: dpopp07

README.md

@@ -85,14 +85,55 @@ Watson services are migrating to token-based Identity and Access Management (IAM
 - In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
 
 ### Getting credentials
+
 To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
 
-1. Go to the IBM Cloud [Dashboard](https://console.bluemix.net/dashboard/apps?category=ai) page.
-1. Either click an existing Watson service instance or click [**Create resource > AI**](https://console.bluemix.net/catalog/?category=ai) and create a service instance.
-1. Click **Show** to view your service credentials.
-1. Copy the `url` and either `apikey` or `username` and `password`.
+1.  Go to the IBM Cloud [Dashboard](https://cloud.ibm.com/) page.
+2.  Either click an existing Watson service instance in your [resource list](https://cloud.ibm.com/resources) or click [**Create resource > AI**](https://cloud.ibm.com/catalog?category=ai) and create a service instance.
+3. Click on the **Manage** item in the left nav bar of your service instance.
+
+On this page, you should be able to see your credentials for accessing your service instance.
+
+In your code, you can use these values in the service constructor or with a method call after instantiating your service.
+
+### Supplying credentials
+
+There are two ways to supply the credentials you found above to the SDK for authentication:
+
+#### Credentials file (easier!)
+
+With a credentials file, you just need to put the file in the right place and the SDK will do the work of parsing it and authenticating. You can get this file by clicking the **Download** button for the credentials in the **Manage** tab of your service instance.
+
+The file downloaded will be called `ibm-credentials.env`. This is the name the SDK will search for and **must** be preserved unless you want to configure the file path (more on that later). The SDK will look for your `ibm-credentials.env` file in the following places (in order):
+
+- Directory provided by the environment variable `IBM_CREDENTIALS_FILE`
+- Your system's home directory
+- Your current working directory (the directory Node is executed from)
+
+As long as you set that up correctly, you don't have to worry about setting any authentication options in your code. So, for example, if you created and downloaded the credential file for your Discovery instance, you just need to do the following:
+
+```js
+const DiscoveryV1 = require('watson-developer-cloud/discovery/v1');
+const discovery = new DiscoveryV1({ version: '2019-02-01' });
+```
+
+And that's it!
+
+If you're using more than one service at a time in your code and get two different `ibm-credentials.env` files, just put the contents together in one `ibm-credentials.env` file and the SDK will handle assigning credentials to their appropriate services.
+
+If you would like to configure the location/name of your credential file, you can set an environment variable called `IBM_CREDENTIALS_FILE`. **This will take precedence over the locations specified above.** Here's how you can do that:
+
+```bash
+export IBM_CREDENTIALS_FILE="<path>"
+```
+
+where `<path>` is something like `/home/user/Downloads/<file_name>.env`. If you just provide a path to a directory, the SDK will look for a file called `ibm-credentials.env` in that directory.
+
+#### Manually
+
+The SDK also supports setting credentials manually in your code. You will either use IAM credentials or Basic Authentication (username/password) credentials.
 
-### IAM
+##### IAM
 
 Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
 
@@ -101,7 +142,7 @@ You supply either an IAM service **API key** or an **access token**:
 - Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
 - Use the access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html). If you want to switch to API key, override your stored IAM credentials with an IAM API key.
 
-#### Supplying the IAM API key
+###### Supplying the IAM API key
 
 ```js
 // in the constructor, letting the SDK manage the IAM token
@@ -113,7 +154,7 @@ const discovery = new DiscoveryV1({
 });
 ```
 
-#### Supplying the access token
+###### Supplying the access token
 
 ```js
 // in the constructor, assuming control of managing IAM token

examples/.env.example

@@ -0,0 +1,2 @@
+NATURAL_LANGUAGE_UNDERSTANDING_USERNAME=username
+NATURAL_LANGUAGE_UNDERSTANDING_PASSWORD=password

lib/base_service.ts

@@ -23,6 +23,7 @@ import semver = require('semver');
 import vcapServices = require('vcap_services');
 import { IamTokenManagerV1 } from '../iam-token-manager/v1';
 import { stripTrailingSlash } from './helper';
+import { readCredentialsFile } from './read-credentials-file';
 import { sendRequest } from './requestwrapper';
 
 // custom interfaces
@@ -308,7 +309,8 @@ export class BaseService {
     _options = extend(
       {},
       this.getCredentialsFromBluemix(this.name),
-      this.getCredentialsFromEnvironment(this.name),
+      this.getCredentialsFromEnvironment(process.env, this.name),
+      this.getCredentialsFromEnvironment(readCredentialsFile(), this.name),
       options,
       _options
     );
@@ -352,24 +354,24 @@ export class BaseService {
    * @param {string} name - the service snake case name
    * @returns {Credentials}
    */
-  private getCredentialsFromEnvironment(name: string): Credentials {
+  private getCredentialsFromEnvironment(envObj: any, name: string): Credentials {
     if (name === 'watson_vision_combined') {
-      return this.getCredentialsFromEnvironment('visual_recognition');
+      return this.getCredentialsFromEnvironment(envObj, 'visual_recognition');
     }
     // Case handling for assistant - should look for assistant env variables before conversation
-    if (name === 'conversation' && (process.env[`ASSISTANT_USERNAME`] ||  process.env[`ASSISTANT_IAM_APIKEY`])) {
-       return this.getCredentialsFromEnvironment('assistant');
+    if (name === 'conversation' && (envObj[`ASSISTANT_USERNAME`] ||  envObj[`ASSISTANT_IAM_APIKEY`])) {
+       return this.getCredentialsFromEnvironment(envObj, 'assistant');
     }
     const _name: string = name.toUpperCase();
     // https://github.com/watson-developer-cloud/node-sdk/issues/605
     const nameWithUnderscore: string = _name.replace(/-/g, '_');
-    const username: string = process.env[`${_name}_USERNAME`] || process.env[`${nameWithUnderscore}_USERNAME`];
-    const password: string = process.env[`${_name}_PASSWORD`] || process.env[`${nameWithUnderscore}_PASSWORD`];
-    const apiKey: string = process.env[`${_name}_API_KEY`] || process.env[`${nameWithUnderscore}_API_KEY`];
-    const url: string = process.env[`${_name}_URL`] || process.env[`${nameWithUnderscore}_URL`];
-    const iamAccessToken: string = process.env[`${_name}_IAM_ACCESS_TOKEN`] || process.env[`${nameWithUnderscore}_IAM_ACCESS_TOKEN`];
-    const iamApiKey: string = process.env[`${_name}_IAM_APIKEY`] || process.env[`${nameWithUnderscore}_IAM_APIKEY`];
-    const iamUrl: string = process.env[`${_name}_IAM_URL`] || process.env[`${nameWithUnderscore}_IAM_URL`];
+    const username: string = envObj[`${_name}_USERNAME`] || envObj[`${nameWithUnderscore}_USERNAME`];
+    const password: string = envObj[`${_name}_PASSWORD`] || envObj[`${nameWithUnderscore}_PASSWORD`];
+    const apiKey: string = envObj[`${_name}_API_KEY`] || envObj[`${nameWithUnderscore}_API_KEY`];
+    const url: string = envObj[`${_name}_URL`] || envObj[`${nameWithUnderscore}_URL`];
+    const iamAccessToken: string = envObj[`${_name}_IAM_ACCESS_TOKEN`] || envObj[`${nameWithUnderscore}_IAM_ACCESS_TOKEN`];
+    const iamApiKey: string = envObj[`${_name}_IAM_APIKEY`] || envObj[`${nameWithUnderscore}_IAM_APIKEY`];
+    const iamUrl: string = envObj[`${_name}_IAM_URL`] || envObj[`${nameWithUnderscore}_IAM_URL`];
 
     return {
       username,

lib/read-credentials-file.ts

@@ -0,0 +1,51 @@
+import dotenv = require('dotenv');
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
+
+const filename: string = 'ibm-credentials.env';
+
+export function readCredentialsFile() {
+  // first look for an env variable called IBM_CREDENTIALS_FILE
+  // it should be the path to the file
+
+  const givenFilepath: string = process.env['IBM_CREDENTIALS_FILE'] || '';
+  const homeDir: string = constructFilepath(os.homedir());
+  const workingDir: string = constructFilepath(process.cwd());
+
+  let filepathToUse: string;
+
+  if (givenFilepath) {
+    if (fileExistsAtPath(givenFilepath)) {
+      // see if user gave a path to a file named something other than `ibm-credentials.env`
+      filepathToUse = givenFilepath;
+    } else if (fileExistsAtPath(constructFilepath(givenFilepath))) {
+      // see if user gave a path to the directory where file is located
+      filepathToUse = constructFilepath(givenFilepath);
+    }
+  } else if (fileExistsAtPath(homeDir)) {
+    filepathToUse = homeDir;
+  } else if (fileExistsAtPath(workingDir)) {
+    filepathToUse = workingDir;
+  } else {
+    // file does not exist anywhere, will not be used
+    return {};
+  }
+
+  const credsFile = fs.readFileSync(filepathToUse);
+
+  return dotenv.parse(credsFile);
+}
+
+export function fileExistsAtPath(filepath): boolean {
+  return fs.existsSync(filepath) && fs.lstatSync(filepath).isFile();
+}
+
+export function constructFilepath(filepath): string {
+  // ensure filepath includes the filename
+  if (!filepath.endsWith(filename)) {
+    filepath = path.join(filepath, filename);
+  }
+
+  return filepath;
+}