feat(IamAssumeAuthenticator): introduce new authenticator type

This commit introduces the new IamAssumeAuthenticator which
will fetch an IAM access token using the IAM getToken operation's
"assume" grant type.  The resulting access token allows the
application to assume the identity of a trusted profile,
similar to the "sudo" feature of Linux.

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

Author: padamstx

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2024-09-03T23:09:01Z",
+  "generated_at": "2024-10-01T20:10:03Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -70,23 +70,55 @@
         "hashed_secret": "91dfd9ddb4198affc5c194cd8ce6d338fde470e2",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 72,
+        "line_number": 73,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "4f51cde3ac0a5504afa4bc06859b098366592c19",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 222,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "e87559ed7decb62d0733ae251ae58d42a55291d8",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 224,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "12f4a68ed3d0863e56497c9cdb1e2e4e91d5cb68",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 288,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "c837b75d7cd93ef9c2243ca28d6e5156259fd253",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 292,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "98635b2eaa2379f28cd6d72a38299f286b81b459",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 407,
+        "line_number": 526,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "47fcf185ee7e15fe05cae31fbe9e4ebe4a06a40d",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 510,
+        "line_number": 629,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -104,23 +136,23 @@
         "hashed_secret": "d4c3d66fd0c38547a3c7a4c6bdc29c36911bc030",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 46,
+        "line_number": 47,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "8318df9ecda039deac9868adf1944a29a95c7114",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 49,
+        "line_number": 50,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "9a66213cc16d178fdbf9f4da6b7bd92497fda404",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 55,
+        "line_number": 56,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -183,6 +215,16 @@
         "verified_result": null
       }
     ],
+    "src/test/java/com/ibm/cloud/sdk/core/test/security/IamAssumeAuthenticatorTest.java": [
+      {
+        "hashed_secret": "333f0f8814d63e7268f80e1e65e7549137d2350c",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 57,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "src/test/java/com/ibm/cloud/sdk/core/test/security/JsonWebTokenTest.java": [
       {
         "hashed_secret": "c6ba9cef42f298486a61546fefd03a4177e60a99",
@@ -294,7 +336,7 @@
         "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 115,
+        "line_number": 127,
         "type": "Secret Keyword",
         "verified_result": null
       }

Authentication.md

@@ -2,7 +2,8 @@
 The java-sdk-core project supports the following types of authentication:
 - Basic Authentication
 - Bearer Token Authentication
-- Identity and Access Management (IAM) Authentication
+- Identity and Access Management (IAM) Authentication (grant type: apikey)
+- Identity and Access Management (IAM) Authentication (grant type: assume)
 - Container Authentication
 - VPC Instance Authentication
 - Cloud Pak for Data Authentication
@@ -12,11 +13,11 @@ The java-sdk-core project supports the following types of authentication:
 The SDK user configures the appropriate type of authentication for use with service instances.  
 The authentication types that are appropriate for a particular service may vary from service to service,
 so it is important for the SDK user to consult with the appropriate service documentation to understand
-which authenticators are supported for that service.
+which authentication types are supported for that service.
 
 The java-sdk-core allows an authenticator to be specified in one of two ways:
 1. programmatically - the SDK user constructs an instance of the desired authenticator using the appropriate Builder class or constructor,
-and then passes the authenticator instance when constructing an instance of the service.
+and then passes the authenticator instance when constructing an instance of the service client.
 2. configuration - the SDK user provides external configuration information (in the form of environment variables
 or a credentials file) to indicate the type of authenticator, along with the configuration of the necessary properties
 for that authenticator.
@@ -138,10 +139,10 @@ authenticator type is intended for situations in which the application will be m
 token itself in terms of initial acquisition and refreshing as needed.
 
 
-## Identity and Access Management (IAM) Authentication
-The `IamAuthenticator` will accept a user-supplied api key and will perform
+## Identity and Access Management (IAM) Authentication (grant type: apikey)
+The `IamAuthenticator` will accept a user-supplied apikey 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 
+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:
@@ -151,7 +152,7 @@ form:
 
 ### Properties
 
-- apikey: (required) the IAM api key
+- apikey: (required) the IAM apikey to be used to obtain an IAM access token.
 
 - url: (optional) The base endpoint URL of the IAM token service.
 The default value of this property is the "prod" IAM token service endpoint
@@ -174,7 +175,7 @@ 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 
+- 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
@@ -214,6 +215,124 @@ ExampleService service = ExampleService.newInstance("example_service");
 ```
 
 
+## Identity and Access Management (IAM) Authentication (grant type: assume)
+The `IamAssumeAuthenticator` performs a two-step token fetch sequence to obtain
+a bearer token that allows the application to assume the identity of a trusted profile:
+1. First, the authenticator obtains an initial bearer token using grant type
+`urn:ibm:params:oauth:grant-type:apikey`.
+This initial token will reflect the identity associated with the input apikey.
+2. Second, the authenticator uses the grant type `urn:ibm:params:oauth:grant-type:assume` to obtain a bearer token
+that reflects the identity of the trusted profile, passing in the initial bearer token
+from the first step, along with the trusted profile-related inputs.
+
+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 IAM apikey to be used to obtain the initial IAM access token.
+
+- iamProfileCrn: (optional) the Cloud Resource Name (CRN) associated with the trusted profile
+for which an access token should be fetched.
+Exactly one of iamProfileCrn, iamProfileId or iamProfileName must be specified.
+
+- iamProfileId: (optional) the ID associated with the trusted profile
+for which an access token should be fetched.
+Exactly one of iamProfileCrn, iamProfileId or iamProfileName must be specified.
+
+- iamProfileName: (optional) the name associated with the trusted profile
+for which an access token should be fetched.  When specifying this property, you must also
+specify the iamAccountId property as well.
+Exactly one of iamProfileCrn, iamProfileId or iamProfileName must be specified.
+
+- iamAccountId: (optional) the ID associated with the IAM account that contains the trusted profile
+referenced by the iamProfileName property.  The imaAccountId property must be specified if and only if
+the iamProfileName property is 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`).
+Make sure that you use an IAM token service endpoint that is appropriate for the
+location of the service being used by your application.
+For example, if you are using an instance of a service in the "production" environment
+(e.g. `https://resource-controller.cloud.ibm.com`),
+then the default "prod" IAM token service endpoint should suffice.
+However, if your application is using an instance of a service in the "staging" environment
+(e.g. `https://resource-controller.test.cloud.ibm.com`),
+then you would also need to configure the authenticator to use the IAM token service "staging"
+endpoint as well (`https://iam.test.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 server when fetching the
+initial IAM access token. These fields are optional, but must be specified together.
+
+- scope: (optional) the scope to be used when obtaining the initial IAM access token.
+If not specified, then no scope will be associated with the access token.
+
+- 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 IAM token service.
+
+### Usage Notes
+- The IamAssumeAuthenticator is used to obtain an access token (a bearer token) from the IAM token service
+that allows an application to "assume" the identity of a trusted profile.
+
+- The authenticator first uses the apikey, url, clientId/clientSecret, scope, disableSSLVerification, and headers
+properties to obtain an initial access token by invoking the IAM `getToken`
+(grant_type=`urn:ibm:params:oauth:grant-type:apikey`) operation.
+
+- The authenticator then uses the initial access token along with the url, iamProfileCrn, iamProfileId,
+iamProfileName, iamAccountId, disableSSLVerification, and headers properties to obtain an access token by invoking
+the IAM `getToken` (grant_type=`urn:ibm:params:oauth:grant-type:assume`) operation.
+The access token resulting from this second step will reflect the identity of the specified trusted profile.
+
+- When providing the trusted profile information, you must specify exactly one of: iamProfileCrn, iamProfileId
+or iamProfileName.  If you specify iamProfileCrn or iamProfileId, then the trusted profile must exist in the same account that is
+associated with the input apikey.  If you specify iamProfileName, then you must also specify the iamAccountId property
+to indicate the IAM account in which the named trusted profile can be found.
+
+### Programming example
+```java
+import com.ibm.cloud.sdk.core.security.IamAssumeAuthenticator;
+import <sdk_base_package>.ExampleService.v1.ExampleService;
+...
+// Create the authenticator.
+IamAssumeAuthenticator authenticator = new IamAssumeAuthenticator.Builder()
+    .iamProfileId("myprofile-1")
+    .apikey("myapikey")
+    .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=iamAssume
+export EXAMPLE_SERVICE_APIKEY=myapikey
+export EXAMPLE_SERVICE_IAM_PROFILE_ID=myprofile-1
+```
+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.
+```
+
+
 ## Container Authentication
 The `ContainerAuthenticator` is intended to be used by application code
 running inside a compute resource managed by the IBM Kubernetes Service (IKS)
@@ -222,7 +341,7 @@ 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 storing credentials in application code, configuration files or a password vault
 - avoid managing or rotating credentials
 
 The `ContainerAuthenticator` will retrieve the CR token from
@@ -272,7 +391,7 @@ 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 
+- 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
@@ -320,7 +439,7 @@ The compute resource identity feature allows you to assign a trusted IAM profile
 This, in turn, allows applications running within the compute resource to take on this identity when interacting with
 IAM-secured IBM Cloud services.
 This results in a simplified security model that allows the application developer to:
-- avoid storing credentials in application code, configuraton files or a password vault
+- avoid storing credentials in application code, configuration files or a password vault
 - avoid managing or rotating credentials
 
 The `VpcInstanceAuthenticator` will invoke the appropriate operations on the compute resource's locally-available
@@ -408,7 +527,7 @@ form:
 
 - 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 
+- 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
@@ -474,7 +593,7 @@ form:
 - 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 
+- 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

README.md

@@ -39,10 +39,12 @@ You can find the Javadoc for this project here: https://ibm.github.io/java-sdk-c
 The java-sdk-core project supports the following types of authentication:
 - Basic Authentication
 - Bearer Token Authentication
-- Identity and Access Management (IAM) Authentication
+- Identity and Access Management (IAM) Authentication (grant type: apikey)
+- Identity and Access Management (IAM) Authentication (grant type: assume)
 - Container Authentication
 - VPC Instance Authentication
 - Cloud Pak for Data Authentication
+- Multi-Cloud Saas Platform (MCSP) Authentication
 - No Authentication (for testing)
 
 For more information about the various authentication types and how to use them with your services, click [here](Authentication.md).

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2024.
  *
  * 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
@@ -26,6 +26,7 @@ public interface Authenticator {
   String AUTHTYPE_BASIC = "basic";
   String AUTHTYPE_NOAUTH = "noAuth";
   String AUTHTYPE_IAM = "iam";
+  String AUTHTYPE_IAM_ASSUME = "iamAssume";
   String AUTHTYPE_CP4D = "cp4d";
   String AUTHTYPE_CP4D_SERVICE = "cp4dService";
   String AUTHTYPE_CP4D_SERVICE_INSTANCE = "cp4dServiceInstance";
@@ -57,6 +58,7 @@ public interface Authenticator {
   String PROPNAME_IAM_PROFILE_CRN = "IAM_PROFILE_CRN";
   String PROPNAME_IAM_PROFILE_ID = "IAM_PROFILE_ID";
   String PROPNAME_IAM_PROFILE_NAME = "IAM_PROFILE_NAME";
+  String PROPNAME_IAM_ACCOUNT_ID = "IAM_ACCOUNT_ID";
 
   /**
    * Validates the current set of configuration information in the Authenticator.