@@ -7,7 +7,8 @@ The python-sdk-core project supports the following types of authentication:
77- Container Authentication
88- VPC Instance Authentication
99- Cloud Pak for Data Authentication
10- - Multi-Cloud Saas Platform (MCSP) Authentication
10+ - Multi-Cloud Saas Platform (MCSP) V1 Authentication
11+ - Multi-Cloud Saas Platform (MCSP) V2 Authentication
1112- No Authentication (for testing)
1213
1314The SDK user configures the appropriate type of authentication for use with service instances.
@@ -546,11 +547,11 @@ service = ExampleServiceV1.new_instance(service_name='example_service')
546547```
547548
548549
549- ## Multi-Cloud Saas Platform (MCSP) Authentication
550+ ## Multi-Cloud Saas Platform (MCSP) V1 Authentication
550551The ` MCSPAuthenticator ` can be used in scenarios where an application needs to
551552interact with an IBM Cloud service that has been deployed to a non-IBM Cloud environment (e.g. AWS).
552- It accepts a user-supplied apikey and performs the necessary interactions with the
553- Multi-Cloud Saas Platform token service to obtain a suitable MCSP access token (a bearer token)
553+ It accepts a user-supplied apikey and invokes the Multi-Cloud Saas Platform token service's
554+ ` POST /siusermgr/api/1.0/apikeys/ token` operation to obtain a suitable MCSP access token (a bearer token)
554555for the specified apikey.
555556The authenticator will also obtain a new bearer token when the current token expires.
556557The bearer token is then added to each outbound request in the ` Authorization ` header in the
@@ -610,6 +611,104 @@ service = ExampleServiceV1.new_instance(service_name='example_service')
610611```
611612
612613
614+ ## Multi-Cloud Saas Platform (MCSP) V2 Authentication
615+ The ` MCSPV2Authenticator ` can be used in scenarios where an application needs to
616+ interact with an IBM Cloud service that has been deployed to a non-IBM Cloud environment (e.g. AWS).
617+ It accepts a user-supplied apikey and invokes the Multi-Cloud Saas Platform token service's
618+ ` POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` operation to obtain a suitable MCSP access token (a bearer token)
619+ for the specified apikey.
620+ The authenticator will also obtain a new bearer token when the current token expires.
621+ The bearer token is then added to each outbound request in the ` Authorization ` header in the
622+ form:
623+ ```
624+ Authorization: Bearer <bearer-token>
625+ ```
626+
627+ ### Properties
628+
629+ - apikey: (required) The apikey to be used to obtain an MCSP access token.
630+
631+ - url: (required) The URL representing the MCSP token service endpoint's base URL string. Do not include the
632+ operation path (e.g. ` /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` ) as part of this property's value.
633+
634+ - scope_collection_type: (required) The scope collection type of item(s).
635+ The valid values are: ` accounts ` , ` subscriptions ` , ` services ` .
636+
637+ - scope_id: (required) The scope identifier of item(s).
638+
639+ - include_builtin_actions: (optional) A flag to include builtin actions in the ` actions ` claim in the MCSP token (default: false).
640+
641+ - include_custom_actions: (optional) A flag to include custom actions in the ` actions ` claim in the MCSP token (default: false).
642+
643+ - include_roles: (optional) A flag to include the ` roles ` claim in the MCSP token (default: true).
644+
645+ - prefix_roles: (optional) A flag to add a prefix with the scope level where
646+ the role is defined in the ` roles ` claim (default: false).
647+
648+ - caller_ext_claim: (optional) A map containing keys and values to be injected into the returned access token
649+ as the ` callerExt ` claim. The keys used in this map must be enabled in the apikey by setting the
650+ ` callerExtClaimNames ` property when the apikey is created.
651+ This property is typically only used in scenarios involving an apikey with identityType ` SERVICEID ` .
652+
653+ - disable_ssl_verification: (optional) A flag that indicates whether verification of the server's SSL
654+ certificate should be disabled or not. The default value is ` false ` .
655+
656+ - headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
657+ made to the MCSP token service.
658+
659+ ### Usage Notes
660+ - When constructing an MCSPV2Authenticator instance, the apikey, url, scope_collection_type, and scope_id properties are required.
661+
662+ - If you specify the caller_ext_claim map, the keys used in the map must have been previously enabled in the apikey
663+ by setting the ` callerExtClaimNames ` property when you created the apikey.
664+ The entries contained in this map will appear in the ` callerExt ` field (claim) of the returned access token.
665+
666+ - The authenticator will invoke the token server's ` POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` operation to
667+ exchange the apikey for an MCSP access token (the bearer token).
668+
669+ ### Programming example
670+ ``` python
671+ from ibm_cloud_sdk_core.authenticators import MCSPV2Authenticator
672+ from < sdk- package- name> .example_service_v1 import *
673+
674+ # Create the authenticator.
675+ authenticator = MCSPV2Authenticator(
676+ apikey = ' myapikey'
677+ url = ' https://example.mcspv2.token-exchange.com'
678+ scope_collection_type = ' accounts'
679+ scope_id = ' 20250519-2128-3755-60b3-103e01c509e8'
680+ include_builtin_actions = True ,
681+ caller_ext_claim = {" productID" " prod-123"
682+ )
683+
684+ # Construct the service instance.
685+ service = ExampleServiceV1(authenticator = authenticator)
686+
687+ # 'service' can now be used to invoke operations.
688+ ```
689+
690+ ### Configuration example
691+ External configuration:
692+ ```
693+ export EXAMPLE_SERVICE_AUTH_TYPE=mcspv2
694+ export EXAMPLE_SERVICE_APIKEY=myapikey
695+ export EXAMPLE_SERVICE_AUTH_URL=https://example.mcspv2.token-exchange.com
696+ export EXAMPLE_SERVICE_SCOPE_COLLECTION_TYPE=accounts
697+ export EXAMPLE_SERVICE_SCOPE_ID=20250519-2128-3755-60b3-103e01c509e8
698+ export EXAMPLE_SERVICE_INCLUDE_BUILTIN_ACTIONS=true
699+ export EXAMPLE_SERVICE_CALLER_EXT_CLAIM={"productID":"prod-123"}
700+ ```
701+ Application code:
702+ ``` python
703+ from < sdk- package- name> .example_service_v1 import *
704+
705+ # Construct the service instance.
706+ service = ExampleServiceV1.new_instance(service_name = ' example_service'
707+
708+ # 'service' can now be used to invoke operations.
709+ ```
710+
711+
613712## No Auth Authentication
614713The ` NoAuthAuthenticator ` is a placeholder authenticator which performs no actual authentication function.
615714It can be used in situations where authentication needs to be bypassed, perhaps while developing
0 commit comments