feat: introduce new container authenticator

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2021-07-26T18:11:07Z",
+  "generated_at": "2021-08-07T17:12:28Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -25,6 +25,7 @@
       "name": "CloudantDetector"
     },
     {
+      "ghe_instance": "github.ibm.com",
       "name": "GheDetector"
     },
     {
@@ -69,23 +70,23 @@
         "hashed_secret": "47fcf185ee7e15fe05cae31fbe9e4ebe4a06a40d",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 170,
+        "line_number": 192,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "98635b2eaa2379f28cd6d72a38299f286b81b459",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 198,
+        "line_number": 316,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "91dfd9ddb4198affc5c194cd8ce6d338fde470e2",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 226,
+        "line_number": 348,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -103,43 +104,43 @@
         "hashed_secret": "d4c3d66fd0c38547a3c7a4c6bdc29c36911bc030",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 42,
+        "line_number": 43,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "8318df9ecda039deac9868adf1944a29a95c7114",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 44,
+        "line_number": 45,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "9a66213cc16d178fdbf9f4da6b7bd92497fda404",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 50,
+        "line_number": 51,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "src/main/java/com/ibm/cloud/sdk/core/security/IamAuthenticator.java": [
+    "src/test/java/com/ibm/cloud/sdk/core/test/security/BasicAuthenticatorTest.java": [
       {
-        "hashed_secret": "d4c3d66fd0c38547a3c7a4c6bdc29c36911bc030",
+        "hashed_secret": "ffac6ba71b03ca5f5012197511d76fbcfcf62fbf",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 39,
+        "line_number": 36,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "src/test/java/com/ibm/cloud/sdk/core/test/security/BasicAuthenticatorTest.java": [
+    "src/test/java/com/ibm/cloud/sdk/core/test/security/ContainerAuthenticatorTest.java": [
       {
-        "hashed_secret": "ffac6ba71b03ca5f5012197511d76fbcfcf62fbf",
+        "hashed_secret": "360c23c1ac7d9d6dad1d0710606b0df9de6e1a18",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 36,
+        "line_number": 64,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -149,15 +150,15 @@
         "hashed_secret": "789cbe0407840b1c2041cb33452ff60f19bf58cc",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 63,
+        "line_number": 62,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "2207d3f3ac68743290fe4affc71c10bec4962232",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 64,
+        "line_number": 63,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -167,7 +168,7 @@
         "hashed_secret": "ca3f35fa1a5cb92b242c2b42d6d902d43b4816f0",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 62,
+        "line_number": 61,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -255,7 +256,7 @@
         "hashed_secret": "e4f50034475acff058e17b35679f8ef1e54f86c5",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 73,
+        "line_number": 85,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -321,7 +322,7 @@
       }
     ]
   },
-  "version": "0.13.1+ibm.31.dss",
+  "version": "0.13.1+ibm.40.dss",
   "word_list": {
     "file": null,
     "hash": null

Authentication.md

@@ -1,9 +1,10 @@
 # Authentication
 The java-sdk-core project supports the following types of authentication:
 - Basic Authentication
-- Bearer Token 
-- Identity and Access Management (IAM)
-- Cloud Pak for Data
+- Bearer Token Authentication
+- Identity and Access Management (IAM) Authentication
+- Container Authentication
+- Cloud Pak for Data Authentication
 - No Authentication
 
 The SDK user configures the appropriate type of authentication for use with service instances.  
@@ -23,15 +24,20 @@ configuration information.  The configuration examples below will use
 environment variables, although the same properties could be specified in a
 credentials file instead.
 
+
 ## Basic Authentication
 The `BasicAuthenticator` is used to add Basic Authentication information to
 each outbound request in the `Authorization` header in the form:
 ```
    Authorization: Basic <encoded username and password>
 ```
+
 ### Properties
+
 - username: (required) the basic auth username
+
 - password: (required) the basic auth password
+
 ### Programming example
 ```java
 import com.ibm.cloud.sdk.core.security.BasicAuthenticator;
@@ -48,6 +54,7 @@ ExampleService service = new ExampleService(authenticator);
 
 // 'service' can now be used to invoke operations.
 ```
+
 ### Configuration example
 External configuration:
 ```
@@ -69,14 +76,18 @@ ExampleService service = new ExampleService(authenticator);
 // 'service' can now be used to invoke operations.
 ```
 
+
 ## Bearer Token Authentication
 The `BearerTokenAuthenticator` will add a user-supplied bearer token to
 each outbound request in the `Authorization` header in the form:
 ```
     Authorization: Bearer <bearer-token>
 ```
+
 ### Properties
+
 - bearerToken: (required) the bearer token value
+
 ### Programming example
 ```java
 import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
@@ -96,6 +107,7 @@ ExampleService service = new ExampleService(authenticator);
 newToken = // ... obtain new bearer token value
 authenticator.setBearerToken(newToken);
 ```
+
 ### Configuration example
 External configuration:
 ```
@@ -120,13 +132,15 @@ ExampleService service = new ExampleService(authenticator);
 newToken = // ... obtain new bearer token value
 ((BearerTokenAuthenticator) authenticator).setBearerToken(newToken);
 ```
+
 Note that the use of external configuration is not as useful with the `BearerTokenAuthenticator` as it
 is for other authenticator types because bearer tokens typically need to be obtained and refreshed
 programmatically since they normally have a relatively short lifespan before they expire.  This
 authenticator type is intended for situations in which the application will be managing the bearer 
 token itself in terms of initial acquisition and refreshing as needed.
 
-## Identity and Access Management Authentication (IAM)
+
+## Identity and Access Management (IAM) Authentication
 The `IamAuthenticator` will accept a user-supplied api key and will perform
 the necessary interactions with the IAM token service to obtain a suitable
 bearer token for the specified api key.  The authenticator will also obtain 
@@ -136,18 +150,25 @@ form:
 ```
    Authorization: Bearer <bearer-token>
 ```
+
 ### Properties
+
 - apikey: (required) the IAM api key
+
 - url: (optional) The URL representing the IAM token service endpoint.  If not specified, a suitable
 default value is used.
+
 - clientId/clientSecret: (optional) The `clientId` and `clientSecret` fields are used to form a 
 "basic auth" Authorization header for interactions with the IAM token server. If neither field 
 is specified, then no Authorization header will be sent with token server requests.  These fields 
 are optional, but must be specified together.
+
 - disableSSLVerification: (optional) A flag that indicates whether verificaton of the server's SSL 
 certificate should be disabled or not. The default value is `false`.
+
 - headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
 made to the IAM token service.
+
 ### Programming example
 ```java
 import com.ibm.cloud.sdk.core.security.IamAuthenticator;
@@ -163,6 +184,7 @@ ExampleService service = new ExampleService(authenticator);
 
 // 'service' can now be used to invoke operations.
 ```
+
 ### Configuration example
 External configuration:
 ```
@@ -183,7 +205,99 @@ ExampleService service = new ExampleService(authenticator);
 // 'service' can now be used to invoke operations.
 ```
 
-##  Cloud Pak for Data
+
+## Container Authentication
+The `ContainerAuthenticator` is intended to be used by application code
+running inside a compute resource managed by the IBM Kubernetes Service (IKS)
+in which a secure compute resource token (CR token) has been stored in a file
+within the compute resource's local file system.
+The CR token is similar to an IAM apikey except that it is managed automatically by
+the compute resource provider (IKS).
+This allows the application developer to:
+- avoid storing credentials in application code, configuraton files or a password vault
+- avoid managing or rotating credentials
+
+The `ContainerAuthenticator` will retrieve the CR token from
+the compute resource in which the application is running, and will then perform
+the necessary interactions with the IAM token service to obtain an IAM access token
+using the IAM "get token" operation with grant-type `cr-token`.
+The authenticator will repeat these steps to obtain a new IAM access token when the
+current access token expires.
+The IAM access token is added to each outbound request in the `Authorization` header in the form:
+```
+   Authorization: Bearer <IAM-access-token>
+```
+
+### Properties
+
+- crTokenFilename: (optional) the name of the file containing the injected CR token value.
+If not specified, then `/var/run/secrets/tokens/vault-token` is used as the default value.
+The application must have `read` permissions on the file containing the CR token value.
+
+- iamProfileName: (optional) the name of the linked trusted IAM profile to be used when obtaining the
+IAM access token (a CR token might map to multiple IAM profiles).
+One of `iamProfileName` or `iamProfileID` must be specified.
+
+- iamProfileID: (optional) the id of the linked trusted IAM profile to be used when obtaining the
+IAM access token (a CR token might map to multiple IAM profiles).
+One of `iamProfileName` or `iamProfileID` must be specified.
+
+- url: (optional) The base endpoint URL of the IAM token service.
+The default value of this property is the "prod" IAM token service endpoint
+(`https://iam.cloud.ibm.com`).
+
+- clientId/clientSecret: (optional) The `clientId` and `clientSecret` fields are used to form a 
+"basic auth" Authorization header for interactions with the IAM token service. If neither field 
+is specified, then no Authorization header will be sent with token server requests.  These fields 
+are optional, but must be specified together.
+
+- scope: (optional) the scope to be associated with the IAM access token.
+If not specified, then no scope will be associated with the access token.
+
+- disableSSLVerification: (optional) A flag that indicates whether verificaton of the server's SSL 
+certificate should be disabled or not. The default value is `false`.
+
+- headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
+made to the IAM token service.
+
+### Programming example
+```java
+import com.ibm.cloud.sdk.core.security.ContainerAuthenticator;
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+// Create the authenticator.
+ContainerAuthenticator authenticator = new ContainerAuthenticator.Builder()
+    .iamProfileName("iam-user123")
+    .build();
+
+// Create the service instance.
+ExampleService service = new ExampleService(authenticator);
+
+// 'service' can now be used to invoke operations.
+```
+
+### Configuration example
+External configuration:
+```
+export EXAMPLE_SERVICE_AUTH_TYPE=container
+export EXAMPLE_SERVICE_IAM_PROFILE_NAME=iam-user123
+```
+Application code:
+```java
+import com.ibm.cloud.sdk.core.security.ConfigBaseAuthenticatorFactory;
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+// Create the authenticator.
+Authenticator authenticator = ConfigBasedAuthenticatorFactory.getAuthenticator("example_service");
+
+// Create the service instance.
+ExampleService service = new ExampleService(authenticator);
+
+// 'service' can now be used to invoke operations.
+```
+
+
+##  Cloud Pak for Data Authentication
 The `CloudPakForDataAuthenticator` will accept user-supplied values for the username and either a password or apikey, and will 
 perform the necessary interactions with the Cloud Pak for Data token service to obtain a suitable
 bearer token.  The authenticator will also obtain a new bearer token when the current token expires.
@@ -192,15 +306,23 @@ form:
 ```
    Authorization: Bearer <bearer-token>
 ```
+
 ### Properties
+
 - username: (required) the username used to obtain a bearer token.
+
 - password: (required if apikey is not specified) the password used to obtain a bearer token.
+
 - apikey: (required if password is not specified) the apikey used to obtain a bearer token.
+
 - url: (required) The base URL associated with the Cloud Pak for Data token service.
+
 - disableSSLVerification: (optional) A flag that indicates whether verificaton of the server's SSL 
 certificate should be disabled or not. The default value is `false`.
+
 - headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
 made to the IAM token service.
+
 ### Programming example
 ```java
 import com.ibm.cloud.sdk.core.security.CloudPakForDataAuthenticator;