ibm-cloud-sdk-core 3.16.0__py3-none-any.whl → 3.20.6__py3-none-any.whl

ibm_cloud_sdk_core/token_managers/container_token_manager.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2021 IBM All Rights Reserved.
+# Copyright 2021, 2024 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.
@@ -18,6 +18,7 @@ import logging
 from typing import Dict, Optional
 
 from .iam_request_based_token_manager import IAMRequestBasedTokenManager
+from ..private_helpers import _build_user_agent
 
 
 logger = logging.getLogger(__name__)
@@ -79,51 +80,64 @@ class ContainerTokenManager(IAMRequestBasedTokenManager):
         scope: The "scope" to use when fetching the bearer token from the IAM token server.
         This can be used to obtain an access token with a specific scope.
     """
-    DEFAULT_CR_TOKEN_FILENAME = '/var/run/secrets/tokens/vault-token'
-
-    def __init__(self,
-                 cr_token_filename: Optional[str] = None,
-                 iam_profile_name: Optional[str] = None,
-                 iam_profile_id: Optional[str] = None,
-                 url: Optional[str] = None,
-                 client_id: Optional[str] = None,
-                 client_secret: Optional[str] = None,
-                 disable_ssl_verification: bool = False,
-                 scope: Optional[str] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 headers: Optional[Dict[str, str]] = None) -> None:
+
+    DEFAULT_CR_TOKEN_FILENAME1 = '/var/run/secrets/tokens/vault-token'
+    DEFAULT_CR_TOKEN_FILENAME2 = '/var/run/secrets/tokens/sa-token'
+
+    def __init__(
+        self,
+        cr_token_filename: Optional[str] = None,
+        iam_profile_name: Optional[str] = None,
+        iam_profile_id: Optional[str] = None,
+        url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        disable_ssl_verification: bool = False,
+        scope: Optional[str] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
         super().__init__(
-            url=url, client_id=client_id, client_secret=client_secret,
-            disable_ssl_verification=disable_ssl_verification, headers=headers, proxies=proxies, scope=scope)
+            url=url,
+            client_id=client_id,
+            client_secret=client_secret,
+            disable_ssl_verification=disable_ssl_verification,
+            headers=headers,
+            proxies=proxies,
+            scope=scope,
+        )
 
         self.cr_token_filename = cr_token_filename
         self.iam_profile_name = iam_profile_name
         self.iam_profile_id = iam_profile_id
 
         self.request_payload['grant_type'] = 'urn:ibm:params:oauth:grant-type:cr-token'
+        self._set_user_agent(_build_user_agent('container-authenticator'))
 
     def retrieve_cr_token(self) -> str:
         """Retrieves the CR token for the current compute resource by reading it from the local file system.
 
         Raises:
-            Exception: Cannot retrieve the compute resource token from.
+            Exception: Error retrieving the compute resource token.
 
         Returns:
             A string which contains the compute resource token.
         """
-        cr_token_filename = self.cr_token_filename if self.cr_token_filename else self.DEFAULT_CR_TOKEN_FILENAME
-
-        logger.debug('Attempting to read CR token from file: %s',
-                      cr_token_filename)
-
         try:
-            with open(cr_token_filename, 'r', encoding='utf-8') as file:
-                cr_token = file.read()
+            cr_token = None
+            if self.cr_token_filename:
+                # If the user specified a filename, then use that.
+                cr_token = self.read_file(self.cr_token_filename)
+            else:
+                # If the user didn't specify a filename, then try our two defaults.
+                try:
+                    cr_token = self.read_file(self.DEFAULT_CR_TOKEN_FILENAME1)
+                except:
+                    cr_token = self.read_file(self.DEFAULT_CR_TOKEN_FILENAME2)
             return cr_token
-        # pylint: disable=broad-except
         except Exception as ex:
-            raise Exception(
-                'Unable to retrieve the CR token value from file {}: {}'.format(cr_token_filename, ex)) from None
+            # pylint: disable=broad-exception-raised
+            raise Exception('Unable to retrieve the CR token: {}'.format(ex)) from None
 
     def request_token(self) -> dict:
         """Retrieves a CR token value from the current compute resource,
@@ -132,11 +146,9 @@ class ContainerTokenManager(IAMRequestBasedTokenManager):
         Returns:
              A dictionary containing the bearer token to be subsequently used service requests.
         """
-        # Retrieve the CR token for this compute resource.
-        cr_token = self.retrieve_cr_token()
 
         # Set the request payload.
-        self.request_payload['cr_token'] = cr_token
+        self.request_payload['cr_token'] = self.retrieve_cr_token()
 
         if self.iam_profile_id:
             self.request_payload['profile_id'] = self.iam_profile_id
@@ -168,3 +180,22 @@ class ContainerTokenManager(IAMRequestBasedTokenManager):
             iam_profile_id: id of the linked trusted IAM profile to be used when obtaining the IAM access token
         """
         self.iam_profile_id = iam_profile_id
+
+    def read_file(self, filename: str) -> str:
+        """Read in the specified file and return the contents as a string.
+        Args:
+            filename: the name of the file to read
+        Returns:
+            The contents of the file as a string.
+        Raises:
+            Exception: An error occured reading the file.
+        """
+        try:
+            logger.debug('Attempting to read CR token from file: %s', filename)
+            with open(filename, 'r', encoding='utf-8') as file:
+                cr_token = file.read()
+            logger.debug('Successfully read CR token from file: %s', filename)
+            return cr_token
+        except Exception as ex:
+            # pylint: disable=broad-exception-raised
+            raise Exception('Error reading CR token from file {}: {}'.format(filename, ex)) from None

ibm_cloud_sdk_core/token_managers/cp4d_token_manager.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -17,6 +17,7 @@
 import json
 from typing import Dict, Optional
 
+from ..private_helpers import _build_user_agent
 from .jwt_token_manager import JWTTokenManager
 
 
@@ -48,19 +49,22 @@ class CP4DTokenManager(JWTTokenManager):
         proxies.https (str): The proxy endpoint to use for HTTPS requests.
         verify (str): The path to the certificate to use for HTTPS requests.
     """
+
     TOKEN_NAME = 'token'
     VALIDATE_AUTH_PATH = '/v1/authorize'
 
-    def __init__(self,
-                 username: str = None,
-                 password: str = None,
-                 url: str = None,
-                 *,
-                 apikey: str = None,
-                 disable_ssl_verification: bool = False,
-                 headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 verify: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        username: str = None,
+        password: str = None,
+        url: str = None,
+        *,
+        apikey: str = None,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        verify: Optional[str] = None,
+    ) -> None:
         self.username = username
         self.password = password
         self.verify = verify
@@ -72,23 +76,27 @@ class CP4DTokenManager(JWTTokenManager):
             self.headers = {}
         self.headers['Content-Type'] = 'application/json'
         self.proxies = proxies
-        super().__init__(url, disable_ssl_verification=disable_ssl_verification,
-                         token_name=self.TOKEN_NAME)
+        super().__init__(url, disable_ssl_verification=disable_ssl_verification, token_name=self.TOKEN_NAME)
+        self._set_user_agent(_build_user_agent('cp4d-authenticator'))
 
     def request_token(self) -> dict:
-        """Makes a request for a token.
-        """
+        """Makes a request for a token."""
+        required_headers = {
+            'User-Agent': self.user_agent,
+        }
+        request_headers = {}
+        if self.headers is not None and isinstance(self.headers, dict):
+            request_headers.update(self.headers)
+        request_headers.update(required_headers)
+
         response = self._request(
             method='POST',
-            headers=self.headers,
+            headers=request_headers,
             url=self.url,
-            data=json.dumps({
-                "username": self.username,
-                "password": self.password,
-                "api_key": self.apikey
-            }),
+            data=json.dumps({"username": self.username, "password": self.password, "api_key": self.apikey}),
             proxies=self.proxies,
-            verify=self.verify)
+            verify=self.verify,
+        )
         return response
 
     def set_headers(self, headers: Dict[str, str]) -> None:

ibm_cloud_sdk_core/token_managers/iam_request_based_token_manager.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -19,7 +19,7 @@ from typing import Dict, Optional
 from .jwt_token_manager import JWTTokenManager
 
 
-#pylint: disable=too-many-instance-attributes
+# pylint: disable=too-many-instance-attributes
 class IAMRequestBasedTokenManager(JWTTokenManager):
     """The IamRequestBasedTokenManager class contains code relevant to any token manager that
     interacts with the IAM service to manage a token. It stores information relevant to all
@@ -60,21 +60,25 @@ class IAMRequestBasedTokenManager(JWTTokenManager):
         scope: The "scope" to use when fetching the bearer token from the IAM token server.
         This can be used to obtain an access token with a specific scope.
     """
+
     DEFAULT_IAM_URL = 'https://iam.cloud.ibm.com'
     OPERATION_PATH = "/identity/token"
-
-    def __init__(self,
-                 url: Optional[str] = None,
-                 client_id: Optional[str] = None,
-                 client_secret: Optional[str] = None,
-                 disable_ssl_verification: bool = False,
-                 headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 scope: Optional[str] = None) -> None:
+    IAM_EXPIRATION_WINDOW = 10
+
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        scope: Optional[str] = None,
+    ) -> None:
         if not url:
             url = self.DEFAULT_IAM_URL
         if url.endswith(self.OPERATION_PATH):
-            url = url[:-len(self.OPERATION_PATH)]
+            url = url[: -len(self.OPERATION_PATH)]
         self.url = url
         self.client_id = client_id
         self.client_secret = client_secret
@@ -83,8 +87,7 @@ class IAMRequestBasedTokenManager(JWTTokenManager):
         self.proxies = proxies
         self.scope = scope
         self.request_payload = {}
-        super().__init__(
-            self.url, disable_ssl_verification=disable_ssl_verification, token_name='access_token')
+        super().__init__(self.url, disable_ssl_verification=disable_ssl_verification, token_name='access_token')
 
     def request_token(self) -> dict:
         """Request an IAM OAuth token given an API Key.
@@ -95,12 +98,15 @@ class IAMRequestBasedTokenManager(JWTTokenManager):
         Returns:
              A dictionary containing the bearer token to be subsequently used service requests.
         """
-        headers = {
-            'Content-type': 'application/x-www-form-urlencoded',
-            'Accept': 'application/json'
+        required_headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Accept': 'application/json',
+            'User-Agent': self._get_user_agent(),
         }
+        request_headers = {}
         if self.headers is not None and isinstance(self.headers, dict):
-            headers.update(self.headers)
+            request_headers.update(self.headers)
+        request_headers.update(required_headers)
 
         data = dict(self.request_payload)
 
@@ -115,10 +121,11 @@ class IAMRequestBasedTokenManager(JWTTokenManager):
         response = self._request(
             method='POST',
             url=(self.url + self.OPERATION_PATH) if self.url else self.url,
-            headers=headers,
+            headers=request_headers,
             data=data,
             auth_tuple=auth_tuple,
-            proxies=self.proxies)
+            proxies=self.proxies,
+        )
         return response
 
     def set_client_id_and_secret(self, client_id: str, client_secret: str) -> None:
@@ -167,3 +174,19 @@ class IAMRequestBasedTokenManager(JWTTokenManager):
             value: A space seperated string that makes up the scope parameter.
         """
         self.scope = value
+
+    def _is_token_expired(self) -> bool:
+        """
+        Returns true iff the current cached token is expired.
+        We'll consider an access token as expired when we reach its IAM server-reported expiration time
+        minus our expiration window (10 secs).
+        We do this to avoid using an access token that might expire in the middle of a long-running transaction
+        within an IBM Cloud service.
+
+        Returns
+        -------
+        bool
+            True if token is expired; False otherwise
+        """
+        current_time = self._get_current_time()
+        return current_time >= (self.expire_time - self.IAM_EXPIRATION_WINDOW)

ibm_cloud_sdk_core/token_managers/iam_token_manager.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -17,6 +17,7 @@
 from typing import Dict, Optional
 
 from .iam_request_based_token_manager import IAMRequestBasedTokenManager
+from ..private_helpers import _build_user_agent
 
 
 class IAMTokenManager(IAMRequestBasedTokenManager):
@@ -60,19 +61,27 @@ class IAMTokenManager(IAMRequestBasedTokenManager):
         This can be used to obtain an access token with a specific scope.
     """
 
-    def __init__(self,
-                 apikey: str,
-                 *,
-                 url: Optional[str] = None,
-                 client_id: Optional[str] = None,
-                 client_secret: Optional[str] = None,
-                 disable_ssl_verification: bool = False,
-                 headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 scope: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        apikey: str,
+        *,
+        url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        scope: Optional[str] = None,
+    ) -> None:
         super().__init__(
-            url=url, client_id=client_id, client_secret=client_secret,
-            disable_ssl_verification=disable_ssl_verification, headers=headers, proxies=proxies, scope=scope)
+            url=url,
+            client_id=client_id,
+            client_secret=client_secret,
+            disable_ssl_verification=disable_ssl_verification,
+            headers=headers,
+            proxies=proxies,
+            scope=scope,
+        )
 
         self.apikey = apikey
 
@@ -80,3 +89,5 @@ class IAMTokenManager(IAMRequestBasedTokenManager):
         self.request_payload['grant_type'] = 'urn:ibm:params:oauth:grant-type:apikey'
         self.request_payload['apikey'] = self.apikey
         self.request_payload['response_type'] = 'cloud_iam'
+
+        self._set_user_agent(_build_user_agent('iam-authenticator'))

ibm_cloud_sdk_core/token_managers/jwt_token_manager.py

@@ -75,15 +75,7 @@ class JWTTokenManager(TokenManager, ABC):
         buffer = (exp - iat) * 0.2
         self.refresh_time = self.expire_time - buffer
 
-    def _request(self,
-                 method,
-                 url,
-                 *,
-                 headers=None,
-                 params=None,
-                 data=None,
-                 auth_tuple=None,
-                 **kwargs) -> dict:
+    def _request(self, method, url, *, headers=None, params=None, data=None, auth_tuple=None, **kwargs) -> dict:
         kwargs = dict({"timeout": 60}, **kwargs)
         kwargs = dict(kwargs, **self.http_config)
 
@@ -91,13 +83,8 @@ class JWTTokenManager(TokenManager, ABC):
             kwargs['verify'] = False
 
         response = requests.request(
-            method=method,
-            url=url,
-            headers=headers,
-            params=params,
-            data=data,
-            auth=auth_tuple,
-            **kwargs)
+            method=method, url=url, headers=headers, params=params, data=data, auth=auth_tuple, **kwargs
+        )
         if 200 <= response.status_code <= 299:
             return response.json()
 

ibm_cloud_sdk_core/token_managers/mcsp_token_manager.py

@@ -0,0 +1,102 @@
+# coding: utf-8
+
+# Copyright 2023, 2024 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.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+from typing import Dict, Optional
+
+from ..private_helpers import _build_user_agent
+from .jwt_token_manager import JWTTokenManager
+
+
+class MCSPTokenManager(JWTTokenManager):
+    """The MCSPTokenManager accepts a user-supplied apikey and performs the necessary interactions with
+    the Multi-Cloud Saas Platform (MCSP) token service to obtain an MCSP access token (a bearer token).
+    When the access token expires, a new access token is obtained from the token server.
+
+    Keyword Arguments:
+        apikey: The apikey for authentication [required].
+        url: The endpoint for JWT token requests [required].
+        disable_ssl_verification: Disable ssl verification. Defaults to False.
+        headers: Headers to be sent with every service token request. Defaults to None.
+        proxies: Proxies to use for making request. Defaults to None.
+        proxies.http (optional): The proxy endpoint to use for HTTP requests.
+        proxies.https (optional): The proxy endpoint to use for HTTPS requests.
+    """
+
+    TOKEN_NAME = 'token'
+    OPERATION_PATH = '/siusermgr/api/1.0/apikeys/token'
+
+    def __init__(
+        self,
+        apikey: str,
+        url: str,
+        *,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.apikey = apikey
+        self.headers = headers
+        if self.headers is None:
+            self.headers = {}
+        self.headers['Content-Type'] = 'application/json'
+        self.headers['Accept'] = 'application/json'
+        self.proxies = proxies
+        super().__init__(url, disable_ssl_verification=disable_ssl_verification, token_name=self.TOKEN_NAME)
+        self._set_user_agent(_build_user_agent('mcsp-authenticator'))
+
+    def request_token(self) -> dict:
+        """Makes a request for a token."""
+        required_headers = {
+            'User-Agent': self.user_agent,
+        }
+        request_headers = {}
+        if self.headers is not None and isinstance(self.headers, dict):
+            request_headers.update(self.headers)
+        request_headers.update(required_headers)
+
+        response = self._request(
+            method='POST',
+            headers=request_headers,
+            url=self.url + self.OPERATION_PATH,
+            data=json.dumps({"apikey": self.apikey}),
+            proxies=self.proxies,
+        )
+        return response
+
+    def set_headers(self, headers: Dict[str, str]) -> None:
+        """Headers to be sent with every MCSP token request.
+
+        Args:
+            headers: The headers to be sent with every MCSP token request.
+        """
+        if isinstance(headers, dict):
+            self.headers = headers
+        else:
+            raise TypeError('headers must be a dictionary')
+
+    def set_proxies(self, proxies: Dict[str, str]) -> None:
+        """Sets the proxies the token manager will use to communicate with MCSP on behalf of the host.
+
+        Args:
+            proxies: Proxies to use for making request. Defaults to None.
+            proxies.http (optional): The proxy endpoint to use for HTTP requests.
+            proxies.https (optional): The proxy endpoint to use for HTTPS requests.
+        """
+        if isinstance(proxies, dict):
+            self.proxies = proxies
+        else:
+            raise TypeError('proxies must be a dictionary')

ibm_cloud_sdk_core/token_managers/token_manager.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2020 IBM All Rights Reserved.
+# Copyright 2020, 2024 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.
@@ -49,14 +49,10 @@ class TokenManager(ABC):
         lock (Lock): Lock variable to serialize access to refresh/request times
         http_config (dict): A dictionary containing values that control the timeout, proxies, and etc of HTTP requests.
         access_token (str): The latest stored access token
+        user_agent (str): The User-Agent header value to be included in each outbound token request
     """
 
-    def __init__(
-            self,
-            url: str,
-            *,
-            disable_ssl_verification: bool = False
-    ):
+    def __init__(self, url: str, *, disable_ssl_verification: bool = False):
         self.url = url
         self.disable_ssl_verification = disable_ssl_verification
         self.expire_time = 0
@@ -65,6 +61,7 @@ class TokenManager(ABC):
         self.lock = Lock()
         self.http_config = {}
         self.access_token = None
+        self.user_agent = None
 
     def get_token(self) -> str:
         """Get a token to be used for authentication.
@@ -100,6 +97,12 @@ class TokenManager(ABC):
         else:
             raise TypeError('status must be a bool')
 
+    def _set_user_agent(self, user_agent: str = None) -> None:
+        self.user_agent = user_agent
+
+    def _get_user_agent(self) -> str:
+        return self.user_agent
+
     def paced_request_token(self) -> None:
         """
         Paces requests to request_token.
@@ -190,15 +193,7 @@ class TokenManager(ABC):
         """
         pass
 
-    def _request(self,
-                 method,
-                 url,
-                 *,
-                 headers=None,
-                 params=None,
-                 data=None,
-                 auth_tuple=None,
-                 **kwargs):
+    def _request(self, method, url, *, headers=None, params=None, data=None, auth_tuple=None, **kwargs):
         kwargs = dict({"timeout": 60}, **kwargs)
         kwargs = dict(kwargs, **self.http_config)
 
@@ -206,13 +201,8 @@ class TokenManager(ABC):
             kwargs['verify'] = False
 
         response = requests.request(
-            method=method,
-            url=url,
-            headers=headers,
-            params=params,
-            data=data,
-            auth=auth_tuple,
-            **kwargs)
+            method=method, url=url, headers=headers, params=params, data=data, auth=auth_tuple, **kwargs
+        )
         if 200 <= response.status_code <= 299:
             return response