Merge pull request #1027 from watson-developer-cloud/support-credentials-file

Support credential file

Author: germanattanasio

README.md

@@ -141,15 +141,53 @@ Watson services are migrating to token-based Identity and Access Management (IAM
 **Note:** Previously, it was possible to authenticate using a token in a header called `X-Watson-Authorization-Token`. This method is deprecated. The token continues to work with Cloud Foundry services, but is not supported for services that use Identity and Access Management (IAM) authentication. See [here](#iam) for details.
 
 ### 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.  Copy the credentials you need for authentication. Click **Show** if the credentials are masked.
+1.  Go to the IBM Cloud [Dashboard](https://cloud.ibm.com/) page.
+1.  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.
+1. 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.
 
-### IAM
+### Supplying credentials
+
+There are two ways to supply the credentials you found above to the SDK for authentication.
+
+#### Credential file (easier!)
+
+With a credential 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):
+
+- Your system's home directory
+- The top-level directory of the project you're using the SDK in
+
+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:
+
+```java
+Discovery service = new Discovery("2017-11-07");
+```
+
+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`.
+
+#### Manually
+
+If you'd prefer to set authentication values manually in your code, the SDK supports that as well. The way you'll do this depends on what type of credentials your service instance gives you.
+
+##### 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.
 
@@ -159,7 +197,8 @@ You supply either an IAM service **API key** or an **access token**:
 - 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. Then call the `setIamCredentials()` method again.
 
 
-#### Supplying the IAM API key
+Supplying the IAM API key:
+
 ```java
 // in the constructor, letting the SDK manage the IAM token
 IamOptions options = new IamOptions.Builder()
@@ -178,7 +217,8 @@ IamOptions options = new IamOptions.Builder()
 service.setIamCredentials(options);
 ```
 
-#### Supplying the access token
+Supplying the access token:
+
 ```java
 // in the constructor, assuming control of managing IAM token
 IamOptions options = new IamOptions.Builder()
@@ -196,7 +236,7 @@ IamOptions options = new IamOptions.Builder()
 service.setIamCredentials(options);
 ```
 
-### Username and password
+#### Username and password
 
 ```java
 // in the constructor

core/ibm-credentials.env

@@ -0,0 +1,2 @@
+NATURAL_LANGUAGE_CLASSIFIER_APIKEY=123456789
+NATURAL_LANGUAGE_CLASSIFIER_URL=https://gateway.watsonplatform.net/natural-language-classifier/api

core/src/main/java/com/ibm/watson/developer_cloud/service/WatsonService.java

@@ -117,7 +117,15 @@ public abstract class WatsonService {
    */
   public WatsonService(final String name) {
     this.name = name;
-    setCredentialFields(CredentialUtils.getCredentialsFromVcap(name));
+
+    // file credentials take precedence
+    CredentialUtils.ServiceCredentials fileCredentials = CredentialUtils.getFileCredentials(name);
+    if (!fileCredentials.isEmpty()) {
+      setCredentialFields(fileCredentials);
+    } else {
+      setCredentialFields(CredentialUtils.getCredentialsFromVcap(name));
+    }
+
     client = configureHttpClient();
   }
 

core/src/main/java/com/ibm/watson/developer_cloud/util/CredentialUtils.java

@@ -12,19 +12,25 @@
  */
 package com.ibm.watson.developer_cloud.util;
 
-import java.util.Hashtable;
-import java.util.Map.Entry;
-import java.util.logging.Level;
-import java.util.logging.Logger;
-
-import javax.naming.Context;
-import javax.naming.InitialContext;
-
 import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import com.google.gson.JsonSyntaxException;
+import org.apache.commons.io.IOUtils;
+
+import javax.naming.Context;
+import javax.naming.InitialContext;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Hashtable;
+import java.util.List;
+import java.util.Map.Entry;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 /**
  * CredentialUtils retrieves service credentials from the environment.
@@ -37,14 +43,16 @@ public final class CredentialUtils {
    */
   public static class ServiceCredentials {
     private String username;
+    private String password;
     private String oldApiKey;
     private String url;
     private String iamApiKey;
     private String iamUrl;
-    private String password;
 
-    private ServiceCredentials(String username, String oldApiKey, String url, String iamApiKey, String iamUrl,
-                               String password) {
+    private ServiceCredentials() { }
+
+    private ServiceCredentials(String username, String password, String oldApiKey, String url, String iamApiKey,
+                               String iamUrl) {
       this.username = username;
       this.password = password;
       this.oldApiKey = oldApiKey;
@@ -106,59 +114,43 @@ public String getIamApiKey() {
     public String getIamUrl() {
       return iamUrl;
     }
-  }
-
-  /** The Constant VCAP_SERVICES. */
-  private static final String VCAP_SERVICES = "VCAP_SERVICES";
 
-  /** The Constant APIKEY. */
-  private static final String APIKEY = "apikey";
+    /**
+     * Returns true if no fields are set on the object.
+     *
+     * @return whether the object has any set fields
+     */
+    public boolean isEmpty() {
+      return (username == null
+          && password == null
+          && oldApiKey == null
+          && url == null
+          && iamApiKey == null
+          && iamUrl == null);
+    }
+  }
 
-  /** The Constant CREDENTIALS. */
-  private static final String CREDENTIALS = "credentials";
+  static final String PLAN_STANDARD = "standard";
 
-  /** The Constant log. */
+  private static String services;
+  private static Context context;
   private static final Logger log = Logger.getLogger(CredentialUtils.class.getName());
 
-  /** The Constant PASSWORD. */
-  private static final String PASSWORD = "password";
-
-  /** The Constant PLAN. */
-  private static final String PLAN = "plan";
+  private static final String DEFAULT_CREDENTIAL_FILE_NAME = "ibm-credentials.env";
 
-  /** The services. */
-  private static String services;
-
-  /** The context. */
-  private static Context context;
+  private static final String VCAP_SERVICES = "VCAP_SERVICES";
+  private static final String LOOKUP_NAME_EXTENSION_API_KEY = "/credentials";
+  private static final String LOOKUP_NAME_EXTENSION_URL = "/url";
 
-  /** The Constant USERNAME. */
+  private static final String CREDENTIALS = "credentials";
+  private static final String PLAN = "plan";
   private static final String USERNAME = "username";
-
-  /** The Constant URL. */
+  private static final String PASSWORD = "password";
+  private static final String OLD_APIKEY = "api_key";
   private static final String URL = "url";
-
-  /** The Constant IAM_URL. */
+  private static final String IAM_APIKEY = "apikey";
   private static final String IAM_URL = "iam_url";
 
-  /** The Constant PLAN_EXPERIMENTAL. */
-  public static final String PLAN_EXPERIMENTAL = "experimental";
-
-  /** The Constant PLAN_FREE. */
-  public static final String PLAN_FREE = "free";
-
-  /** The Constant PLAN_STANDARD. */
-  public static final String PLAN_STANDARD = "standard";
-
-  /** The Constant API_KEY. */
-  private static final String API_KEY = "api_key";
-
-  /** The Constant LOOKUP_NAME_EXTENSION_API_KEY. */
-  private static final String LOOKUP_NAME_EXTENSION_API_KEY = "/credentials";
-
-  /** The Constant LOOKUP_NAME_EXTENSION_URL. */
-  private static final String LOOKUP_NAME_EXTENSION_URL = "/url";
-
   private CredentialUtils() {
     // This is a utility class - no instantiation allowed.
   }
@@ -190,7 +182,7 @@ public static boolean hasBadStartOrEndChar(String credentialValue) {
   public static ServiceCredentials getCredentialsFromVcap(String serviceName) {
     String username = getVcapValue(serviceName, USERNAME);
     String password = getVcapValue(serviceName, PASSWORD);
-    String oldApiKey = getVcapValue(serviceName, API_KEY);
+    String oldApiKey = getVcapValue(serviceName, OLD_APIKEY);
     if (username == null && password == null && oldApiKey == null) {
       oldApiKey = getJdniValue(serviceName, LOOKUP_NAME_EXTENSION_API_KEY);
     }
@@ -200,7 +192,7 @@ public static ServiceCredentials getCredentialsFromVcap(String serviceName) {
       url = getJdniValue(serviceName, LOOKUP_NAME_EXTENSION_URL);
     }
 
-    String iamApiKey = getVcapValue(serviceName, APIKEY);
+    String iamApiKey = getVcapValue(serviceName, IAM_APIKEY);
     String iamUrl = getVcapValue(serviceName, IAM_URL);
 
     return new ServiceCredentials(username, password, oldApiKey, url, iamApiKey, iamUrl);
@@ -352,4 +344,119 @@ public static void setContext(Hashtable<String, String> env) {
       log.fine("Error setting up JDNI context: " + e.getMessage());
     }
   }
+
+  // Credential file-related methods
+
+  /**
+   * Calls methods to find and parse a credential file in various locations.
+   *
+   * @param serviceName the service name
+   * @return ServiceCredentials object containing parsed values
+   */
+  public static ServiceCredentials getFileCredentials(String serviceName) {
+    List<File> files = getFilesToCheck();
+    List<String> credentialFileContents = getFirstExistingFileContents(files);
+    return setCredentialFields(serviceName, credentialFileContents);
+  }
+
+  /**
+   * Creates a list of files to check for credentials. The file locations are:
+   * * Location provided by user-specified IBM_CREDENTIALS_FILE environment variable
+   * * System home directory (Unix)
+   * * System home directory (Windows)
+   * * Top-level directory of the project this code is being called in
+   *
+   * @return list of credential files to check
+   */
+  private static List<File> getFilesToCheck() {
+    List<File> files = new ArrayList<>();
+
+    String userSpecifiedPath = System.getenv("IBM_CREDENTIALS_FILE");
+    String unixHomeDirectory = System.getenv("HOME");
+    String windowsFirstHomeDirectory = System.getenv("HOMEDRIVE") + System.getenv("HOMEPATH");
+    String windowsSecondHomeDirectory = System.getenv("USERPROFILE");
+    String projectDirectory = System.getProperty("user.dir");
+
+    if (userSpecifiedPath != null) {
+      files.add(new File(userSpecifiedPath));
+    }
+    files.add(new File(String.format("%s/%s", unixHomeDirectory, DEFAULT_CREDENTIAL_FILE_NAME)));
+    files.add(new File(String.format("%s/%s", windowsFirstHomeDirectory, DEFAULT_CREDENTIAL_FILE_NAME)));
+    files.add(new File(String.format("%s/%s", windowsSecondHomeDirectory, DEFAULT_CREDENTIAL_FILE_NAME)));
+    files.add(new File(String.format("%s/%s", projectDirectory, DEFAULT_CREDENTIAL_FILE_NAME)));
+
+    return files;
+  }
+
+  /**
+   * Looks through the provided list of files to search for credentials, stopping at the first existing file.
+   *
+   * @return list of lines in the credential file, or null if no file is found
+   */
+  private static List<String> getFirstExistingFileContents(List<File> files) {
+    List<String> credentialFileContents = null;
+
+    try {
+      for (File file : files) {
+        if (file.isFile()) {
+          credentialFileContents = IOUtils.readLines(new FileInputStream(file), StandardCharsets.UTF_8);
+          break;
+        }
+      }
+    } catch (IOException e) {
+      log.severe("There was a problem trying to read the credential file: " + e);
+    }
+
+    return credentialFileContents;
+  }
+
+  /**
+   * Parses provided list of strings to create and set values for a ServiceCredentials instance.
+   *
+   * @param serviceName the service name
+   * @param credentialFileContents list of lines in the user's credential file
+   * @return ServiceCredentials object containing the parsed values
+   */
+  private static ServiceCredentials setCredentialFields(String serviceName, List<String> credentialFileContents) {
+    ServiceCredentials serviceCredentials = new ServiceCredentials();
+
+    if (credentialFileContents == null) {
+      return serviceCredentials;
+    }
+
+    for (String line : credentialFileContents) {
+      String[] keyAndVal = line.split("=");
+      String lowercaseKey = keyAndVal[0].toLowerCase();
+      if (lowercaseKey.contains(serviceName)) {
+        String credentialType = lowercaseKey.substring(serviceName.length() + 1);
+        String credentialValue = keyAndVal[1];
+
+        switch (credentialType) {
+          case USERNAME:
+            serviceCredentials.username = credentialValue;
+            break;
+          case PASSWORD:
+            serviceCredentials.password = credentialValue;
+            break;
+          case OLD_APIKEY:
+            serviceCredentials.oldApiKey = credentialValue;
+            break;
+          case URL:
+            serviceCredentials.url = credentialValue;
+            break;
+          case IAM_APIKEY:
+            serviceCredentials.iamApiKey = credentialValue;
+            break;
+          case IAM_URL:
+            serviceCredentials.iamUrl = credentialValue;
+            break;
+          default:
+            log.warning("Unknown credential key found in credential file: " + credentialType);
+            break;
+        }
+      }
+    }
+
+    return serviceCredentials;
+  }
 }