feat(auth): add support for MCSP V2 authentication

This commit adds the MCSPV2Authenticator implementation.
This authenticator will invoke the MCSP V2 POST
/api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token
operation to obtain an access token for a user-supplied
apikey.

Signed-off-by: Phil Adams <[email protected]>

Author: padamstx

Authentication.md

@@ -7,7 +7,8 @@ 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
+- Multi-Cloud Saas Platform (MCSP) V1 Authentication
+- Multi-Cloud Saas Platform (MCSP) V2 Authentication
 - No Authentication (for testing)
 
 The SDK user configures the appropriate type of authentication for use with service instances.
@@ -575,11 +576,11 @@ ExampleService service = ExampleService.newInstance("example_service");
 ```
 
 
-## Multi-Cloud Saas Platform (MCSP) Authentication
+## Multi-Cloud Saas Platform (MCSP) V1 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)
+It accepts a user-supplied apikey and invokes the Multi-Cloud Saas Platform token service's
+`POST /siusermgr/api/1.0/apikeys/token` operation 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
@@ -643,6 +644,106 @@ ExampleService service = ExampleService.newInstance("example_service");
 ```
 
 
+## Multi-Cloud Saas Platform (MCSP) V2 Authentication
+The `MCSPV2Authenticator` 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 invokes the Multi-Cloud Saas Platform token service's
+`POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token` operation 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.
+
+- scopeCollectionType: (required) The scope collection type of item(s).
+The valid values are: `accounts`, `subscriptions`, `services`, `products`, `externalservices`
+
+- scopeId: (required) The scope identifier of item(s).
+
+- includeBuiltinActions: (optional) A flag to include builtin actions in the `actions` claim in the MCSP token (default: false).
+
+- includeCustomActions: (optional) A flag to include custom actions in the `actions` claim in the MCSP token (default: false).
+
+- includeRoles: (optional) A flag to include the `roles` claim in the MCSP token (default: true).
+
+- prefixRoles: (optional) A flag to add a prefix with the scope level where 
+the role is defined in the `roles` claim (default: false).
+
+- callerExtClaim: (optional) A map containing keys and values to be injected into the returned access token
+as the `callerExt` claim. The keys used in this map must be enabled in the apikey by setting the
+`callerExtClaimNames` property when the apikey is created.
+
+- disableSSLVerification: (optional) A flag that indicates whether verification 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 MCSPV2Authenticator instance, the apikey, url, scopeCollectionType, and scopeId properties are required.
+
+- If you specify the callerExtClaim map, the keys used in the map must have been previously enabled in the apikey
+by setting the `callerExtClaimNames` property when you created the apikey.
+The entries contained in this map will appear in the `callerExt` field (claim) of the returned access token.
+
+- The authenticator will invoke the token server's `POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token` operation to
+exchange the apikey for an MCSP access token (the bearer token).
+
+### Programming example
+```java
+import com.ibm.cloud.sdk.core.security.MCSPV2Authenticator;
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+Map<String, String> callerExtClaim = Map.of("productID", "prod-123");
+
+// Create the authenticator.
+MCSPV2Authenticator authenticator = new MCSPV2Authenticator.Builder()
+    .apikey("myapikey")
+    .url("https://example.mcspv2.token-exchange.com")
+    .scopeCollectionType("accounts")
+    .scopeId("global_account")
+    .includeBuiltinActions(true)
+    .callerExtClaim(callerExtClaim)
+    .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=mcspv2
+export EXAMPLE_SERVICE_APIKEY=myapikey
+export EXAMPLE_SERVICE_AUTH_URL=https://example.mcspv2.token-exchange.com
+export EXAMPLE_SCOPE_COLLECTION_TYPE=accounts
+export EXAMPLE_SCOPE_ID=global_account
+export EXAMPLE_INCLUDE_BUILTIN_ACTIONS=true
+export EXAMPLE_CALLER_EXT_CLAIM={"productID":"prod-123"}
+```
+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

debug-logging.properties

@@ -1,12 +1,12 @@
 #
-# Copyright 2024 IBM Corporation.
+# Copyright 2024, 2025 IBM Corporation.
 # SPDX-License-Identifier: Apache2.0
 #
 
 # This file contains a java.util.logging configuration that enables debug
 # logging (level = FINE) in the Java SDK core library.
 #
-# To use this file, you can add the "-Djava.util.logging.config.file=logging.properties"
+# To use this file, you can add the "-Djava.util.logging.config.file=debug-logging.properties"
 # option to your java command line.
 # For more information on java.util.logging, please see:
 # https://docs.oracle.com/en/java/javase/11/core/java-logging-overview.html

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

@@ -34,6 +34,7 @@ public interface Authenticator {
   String AUTHTYPE_CONTAINER = "container";
   String AUTHTYPE_VPC = "vpc";
   String AUTHTYPE_MCSP = "mcsp";
+  String AUTHTYPE_MCSPV2 = "mcspv2";
 
   /**
    * Constants which define the names of external config propreties (credential file, environment variable, etc.).
@@ -59,6 +60,13 @@ public interface Authenticator {
   String PROPNAME_IAM_PROFILE_ID = "IAM_PROFILE_ID";
   String PROPNAME_IAM_PROFILE_NAME = "IAM_PROFILE_NAME";
   String PROPNAME_IAM_ACCOUNT_ID = "IAM_ACCOUNT_ID";
+  String PROPNAME_SCOPE_COLLECTION_TYPE = "SCOPE_COLLECTION_TYPE";
+  String PROPNAME_SCOPE_ID = "SCOPE_ID";
+  String PROPNAME_INCLUDE_BUILTIN_ACTIONS = "INCLUDE_BUILTIN_ACTIONS";
+  String PROPNAME_INCLUDE_CUSTOM_ACTIONS = "INCLUDE_CUSTOM_ACTIONS";
+  String PROPNAME_INCLUDE_ROLES = "INCLUDE_ROLES";
+  String PROPNAME_PREFIX_ROLES = "PREFIX_ROLES";
+  String PROPNAME_CALLER_EXT_CLAIM = "CALLER_EXT_CLAIM";
 
   /**
    * Validates the current set of configuration information in the Authenticator.

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

@@ -35,6 +35,8 @@ public class AuthenticatorBase {
       "The %s property must be a valid integer but was %s.";
   public static final String ERRORMSG_ACCOUNTID_PROP_ERROR    =
       "iamAccountId must be specified if and only if iamProfileName is specified";
+  public static final String ERRORMSG_PROP_INVALID_BOOL =
+          "The %s property must be a valid boolean but was '%s'. Valid values are 'true' and 'false'.";
 
   /**
    * Returns a "Basic" Authorization header value for the specified username and password.

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

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

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2023, 2024.
+ * (C) Copyright IBM Corp. 2023, 2025.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -34,7 +34,7 @@
  */
 public class MCSPAuthenticator extends TokenRequestBasedAuthenticator<MCSPToken, MCSPTokenResponse>
         implements Authenticator {
-    private static final Logger LOG = Logger.getLogger(ContainerAuthenticator.class.getName());
+    private static final Logger LOG = Logger.getLogger(MCSPAuthenticator.class.getName());
     private static final String OPERATION_PATH = "/siusermgr/api/1.0/apikeys/token";
 
     // Properties specific to an MCSP authenticator.

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

@@ -76,6 +76,33 @@ public MCSPToken(MCSPTokenResponse response) {
     }
   }
 
+  /**
+   * This ctor will extract the access token from the specified MCSPV2TokenResponse instance,
+   * and compute the refresh time as "80% of the timeToLive added to the issued-at time".
+   * This means that we'll trigger the acquisition of a new token shortly before it is set to expire.
+   * @param response the MCSPTokenResponse instance
+   */
+  public MCSPToken(MCSPV2TokenResponse response) {
+    super();
+    this.accessToken = response.getToken();
+
+    // To compute the expiration time, we'll need to crack open the accessToken value
+    // which is a JWT (Json Web Token) instance.
+    JsonWebToken jwt = new JsonWebToken(this.accessToken);
+
+    Long iat = jwt.getPayload().getIssuedAt();
+    Long exp = jwt.getPayload().getExpiresAt();
+
+    if (iat != null && exp != null) {
+      long ttl = exp - iat;
+
+      this.expirationTime = exp;
+      this.refreshTime = iat + (long) (0.8 * ttl);
+    } else {
+      throw new RuntimeException("Properties 'iat' and 'exp' MUST be present within the encoded access token");
+    }
+  }
+
   /**
    * Returns true iff this object does not hold a valid access token or has one which has crossed our refresh
    * time. This method also updates the refresh time if it determines the token needs to be refreshed to