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

This commit introduces the new MCSPAuthenticator that can be used
to exchange an apikey for an MCSP access token using the Multi-Cloud Saas Platform
authentication token server's 'POST /siusermgr/api/1.0/apikeys/token' operation.

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": "2023-03-23T17:37:09Z",
+  "generated_at": "2023-11-10T17:28:14Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -70,23 +70,23 @@
         "hashed_secret": "91dfd9ddb4198affc5c194cd8ce6d338fde470e2",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 64,
+        "line_number": 65,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "98635b2eaa2379f28cd6d72a38299f286b81b459",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 385,
+        "line_number": 387,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "47fcf185ee7e15fe05cae31fbe9e4ebe4a06a40d",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 416,
+        "line_number": 482,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -161,6 +161,16 @@
         "verified_result": null
       }
     ],
+    "resources/ibm-credentials-mcsp.env": [
+      {
+        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 2,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "resources/ibm-credentials-retry.env": [
       {
         "hashed_secret": "ce49dd46e23153d6593eccd68534b9f1465d5bbd",
@@ -341,28 +351,80 @@
         "verified_result": null
       }
     ],
+    "test/test_mcsp_authenticator.py": [
+      {
+        "hashed_secret": "da2f27d2c57a0e1ed2dc3a34b4ef02faf2f7a4c2",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 91,
+        "type": "Hex High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 147,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "test/test_mcsp_token_manager.py": [
+      {
+        "hashed_secret": "da2f27d2c57a0e1ed2dc3a34b4ef02faf2f7a4c2",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 30,
+        "type": "Hex High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 43,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "ace1a5bf229c3af3f699369c6f2fa1a628692ab8",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 60,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "test/test_utils.py": [
       {
         "hashed_secret": "34a0a47a51d5bf739df0214450385e29ee7e9847",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 423,
+        "line_number": 435,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "f2e7745f43b0ef0e2c2faf61d6c6a28be2965750",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 446,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "2863fa4b5510c46afc2bd2998dfbc0cf3d6df032",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 503,
+        "line_number": 528,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "b9cad336062c0dc3bb30145b1a6697fccfe755a6",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 564,
+        "line_number": 589,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -378,7 +440,7 @@
       }
     ]
   },
-  "version": "0.13.1+ibm.57.dss",
+  "version": "0.13.1+ibm.61.dss",
   "word_list": {
     "file": null,
     "hash": null

Authentication.md

@@ -6,6 +6,7 @@ The python-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.
@@ -427,6 +428,71 @@ service = ExampleServiceV1.new_instance(service_name='example_service')
 # 'service' can now be used to invoke operations.
 ```
 
+
+## 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.
+
+- disable_ssl_verification: (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
+```python
+from ibm_cloud_sdk_core.authenticators import MCSPAuthenticator
+from <sdk-package-name>.example_service_v1 import *
+
+# Create the authenticator.
+authenticator = MCSPAuthenticator(apikey='myapikey', url='https://example.mcsp.token-exchange.com')
+
+# Construct the service instance.
+service = ExampleServiceV1(authenticator=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:
+```python
+from <sdk-package-name>.example_service_v1 import *
+
+# Construct the service instance.
+service = ExampleServiceV1.new_instance(service_name='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

Makefile

@@ -2,29 +2,33 @@
 # to be ready for development work in the local sandbox.
 # example: "make setup"
 
+PYTHON=python3
+LINT_DIRS=ibm_cloud_sdk_core test test_integration
+
 setup: deps dev_deps install_project
 
 all: upgrade_pip setup test-unit lint
 
 ci: setup test-unit lint
 
 upgrade_pip:
-	python -m pip install --upgrade pip
+	${PYTHON} -m pip install --upgrade pip
 
 deps:
-	python -m pip install -r requirements.txt
+	${PYTHON} -m pip install -r requirements.txt
 
 dev_deps:
-	python -m pip install -r requirements-dev.txt
+	${PYTHON} -m pip install -r requirements-dev.txt
 
 install_project:
-	python -m pip install -e .
+	${PYTHON} -m pip install -e .
 
 test-unit:
-	python -m pytest --cov=ibm_cloud_sdk_core test
+	${PYTHON} -m pytest --cov=ibm_cloud_sdk_core test
 
 lint:
-	./pylint.sh && black --check .
+	${PYTHON} -m pylint ${LINT_DIRS}
+	black --check ${LINT_DIRS}
 
 lint-fix:
-	black .
+	black ${LINT_DIRS}

ibm_cloud_sdk_core/__init__.py

@@ -43,6 +43,7 @@
 from .token_managers.cp4d_token_manager import CP4DTokenManager
 from .token_managers.container_token_manager import ContainerTokenManager
 from .token_managers.vpc_instance_token_manager import VPCInstanceTokenManager
+from .token_managers.mcsp_token_manager import MCSPTokenManager
 from .api_exception import ApiException
 from .utils import datetime_to_string, string_to_datetime, read_external_sources
 from .utils import datetime_to_string_list, string_to_datetime_list

ibm_cloud_sdk_core/authenticators/__init__.py

@@ -41,3 +41,4 @@
 from .iam_authenticator import IAMAuthenticator
 from .vpc_instance_authenticator import VPCInstanceAuthenticator
 from .no_auth_authenticator import NoAuthAuthenticator
+from .mcsp_authenticator import MCSPAuthenticator

ibm_cloud_sdk_core/authenticators/authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2023 IBM All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,6 +28,7 @@ class Authenticator(ABC):
     AUTHTYPE_CP4D = 'cp4d'
     AUTHTYPE_VPC = 'vpc'
     AUTHTYPE_NOAUTH = 'noAuth'
+    AUTHTYPE_MCSP = 'mcsp'
     AUTHTYPE_UNKNOWN = 'unknown'
 
     @abstractmethod

ibm_cloud_sdk_core/authenticators/basic_authenticator.py

@@ -76,7 +76,7 @@ def authenticate(self, req: Request) -> None:
             Authorization: Basic <encoded username and password>
 
         Args:
-            req: The request to add basic auth information too. Must contain a key to a dictionary
+            req: The request to add basic auth information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')

ibm_cloud_sdk_core/authenticators/bearer_token_authenticator.py

@@ -61,7 +61,7 @@ def authenticate(self, req: Request) -> None:
             Authorization: Bearer <bearer-token>
 
         Args:
-            req: The request to add bearer authentication information too. Must contain a key to a dictionary
+            req: The request to add bearer authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')

ibm_cloud_sdk_core/authenticators/cp4d_authenticator.py

@@ -127,7 +127,7 @@ def authenticate(self, req: Request) -> None:
             Authorization: Bearer <bearer-token>
 
         Args:
-            req:  The request to add CP4D authentication information too. Must contain a key to a dictionary
+            req:  The request to add CP4D authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')

ibm_cloud_sdk_core/authenticators/iam_request_based_authenticator.py

@@ -54,7 +54,7 @@ def authenticate(self, req: Request) -> None:
             Authorization: Bearer <bearer-token>
 
         Args:
-            req: The request to add IAM authentication information too. Must contain a key to a dictionary
+            req: The request to add IAM authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')