feat(MCSPAuthenticator): add new authenticator for Multi-Cloud Saas Platform

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2023-10-02T14:55:09Z",
+  "generated_at": "2023-11-08T23:43:16Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -70,23 +70,23 @@
         "hashed_secret": "91dfd9ddb4198affc5c194cd8ce6d338fde470e2",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 71,
+        "line_number": 72,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "98635b2eaa2379f28cd6d72a38299f286b81b459",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 406,
+        "line_number": 407,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "47fcf185ee7e15fe05cae31fbe9e4ebe4a06a40d",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 441,
+        "line_number": 510,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -104,23 +104,23 @@
         "hashed_secret": "d4c3d66fd0c38547a3c7a4c6bdc29c36911bc030",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 45,
+        "line_number": 46,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "8318df9ecda039deac9868adf1944a29a95c7114",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 48,
+        "line_number": 49,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "9a66213cc16d178fdbf9f4da6b7bd92497fda404",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 54,
+        "line_number": 55,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -231,6 +231,24 @@
         "verified_result": null
       }
     ],
+    "src/test/resources/mcsp_token.json": [
+      {
+        "hashed_secret": "c84e7dce51eabfc0564ac2d513b8070f03ff889e",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 2,
+        "type": "SoftLayer Credentials",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "d03d939c22ad66a948ec8b4649add9b12b8a3cf6",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 2,
+        "type": "JSON Web Token",
+        "verified_result": null
+      }
+    ],
     "src/test/resources/my-credentials.env": [
       {
         "hashed_secret": "edbd5e119f94badb9f99a67ac6ff4c7a5204ad61",
@@ -265,18 +283,18 @@
         "verified_result": null
       },
       {
-        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
+        "hashed_secret": "e4f50034475acff058e17b35679f8ef1e54f86c5",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 96,
+        "line_number": 98,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
-        "hashed_secret": "e4f50034475acff058e17b35679f8ef1e54f86c5",
+        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 98,
+        "line_number": 115,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -301,6 +319,24 @@
         "verified_result": null
       }
     ],
+    "src/test/resources/refreshed_mcsp_token.json": [
+      {
+        "hashed_secret": "5dcb6cb71ea20f1a58387e3d36d77bd123eb9f3b",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 2,
+        "type": "JSON Web Token",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "c84e7dce51eabfc0564ac2d513b8070f03ff889e",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 2,
+        "type": "SoftLayer Credentials",
+        "verified_result": null
+      }
+    ],
     "src/test/resources/vcap_services.json": [
       {
         "hashed_secret": "0ee6f3a69b36c1bcac73c25350a7414a53397ecd",

Authentication.md

@@ -6,6 +6,7 @@ The java-sdk-core project supports the following types of authentication:
 - Container Authentication
 - VPC Instance Authentication
 - Cloud Pak for Data Authentication
+- Multi-Cloud Saas Platform (MCSP) Authentication
 - No Authentication (for testing)
 
 The SDK user configures the appropriate type of authentication for use with service instances.  
@@ -453,6 +454,74 @@ ExampleService service = ExampleService.newInstance("example_service");
 ```
 
 
+## Multi-Cloud Saas Platform (MCSP) Authentication
+The `MCSPAuthenticator` can be used in scenarios where an application needs to
+interact with an IBM Cloud service that has been deployed to a non-IBM Cloud environment (e.g. AWS).
+It accepts a user-supplied apikey and performs the necessary interactions with the
+Multi-Cloud Saas Platform token service to obtain a suitable MCSP access token (a bearer token)
+for the specified apikey.
+The authenticator will also obtain a new bearer token when the current token expires.
+The bearer token is then added to each outbound request in the `Authorization` header in the
+form:
+```
+   Authorization: Bearer <bearer-token>
+```
+
+### Properties
+
+- apikey: (required) the apikey to be used to obtain an MCSP access token.
+
+- url: (required) The URL representing the MCSP token service endpoint's base URL string. Do not include the
+operation path (e.g. `/siusermgr/api/1.0/apikeys/token`) as part of this property's value.
+
+- 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 MCSP token service.
+
+### Usage Notes
+- When constructing an MCSPAuthenticator instance, you must specify the apikey and url properties.
+
+- The authenticator will use the token server's `POST /siusermgr/api/1.0/apikeys/token` operation to
+exchange the user-supplied apikey for an MCSP access token (the bearer token).
+
+### Programming example
+```java
+import com.ibm.cloud.sdk.core.security.MCSPAuthenticator;
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+// Create the authenticator.
+MCSPAuthenticator authenticator = new MCSPAuthenticator.Builder()
+    .apikey("myapikey")
+    .url("https://example.mcsp.token-exchange.com")
+    .build();
+
+// Create the service instance.
+ExampleService service = new ExampleService(ExampleService.DEFAULT_SERVICE_NAME, authenticator);
+
+// 'service' can now be used to invoke operations.
+```
+
+### Configuration example
+External configuration:
+```
+export EXAMPLE_SERVICE_AUTH_TYPE=mcsp
+export EXAMPLE_SERVICE_APIKEY=myapikey
+export EXAMPLE_SERVICE_AUTH_URL=https://example.mcsp.token-exchange.com
+```
+Application code:
+```java
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+
+// Create the service instance.
+ExampleService service = ExampleService.newInstance("example_service");
+
+// 'service' can now be used to invoke operations.
+```
+
+
 ## No Auth Authentication
 The `NoAuthAuthenticator` is a placeholder authenticator which performs no actual authentication function.
 It can be used in situations where authentication needs to be bypassed, perhaps while developing

src/main/java/com/ibm/cloud/sdk/core/security/Authenticator.java

@@ -32,6 +32,7 @@ public interface Authenticator {
   String AUTHTYPE_BEARER_TOKEN = "bearerToken";
   String AUTHTYPE_CONTAINER = "container";
   String AUTHTYPE_VPC = "vpc";
+  String AUTHTYPE_MCSP = "mcsp";
 
   /**
    * Constants which define the names of external config propreties (credential file, environment variable, etc.).

src/main/java/com/ibm/cloud/sdk/core/security/ConfigBasedAuthenticatorFactory.java

@@ -96,6 +96,8 @@ protected static Authenticator createAuthenticator(Map<String, String> props) {
       authenticator = ContainerAuthenticator.fromConfiguration(props);
     } else if (authType.equalsIgnoreCase(Authenticator.AUTHTYPE_VPC)) {
       authenticator = VpcInstanceAuthenticator.fromConfiguration(props);
+    } else if (authType.equalsIgnoreCase(Authenticator.AUTHTYPE_MCSP)) {
+        authenticator = MCSPAuthenticator.fromConfiguration(props);
     } else if (authType.equalsIgnoreCase(Authenticator.AUTHTYPE_NOAUTH)) {
       authenticator = new NoAuthAuthenticator(props);
     } else {