@@ -7,7 +7,8 @@ The node-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.
@@ -280,14 +281,14 @@ However, if your application is using an instance of a service in the "staging"
280281then you would also need to configure the authenticator to use the IAM token service "staging"
281282endpoint as well (` https://iam.test.cloud.ibm.com ` ).
282283
283- - clientId/clientSecret: (optional) The ` clientId ` and ` clientSecret ` fields are used to form a
284+ - clientId/clientSecret: (optional) The ` clientId ` and ` clientSecret ` fields are used to form a
284285"basic auth" Authorization header for interactions with the IAM token server when fetching the
285286initial IAM access token. These fields are optional, but must be specified together.
286287
287288- scope: (optional) the scope to be used when obtaining the initial IAM access token.
288289If not specified, then no scope will be associated with the access token.
289290
290- - disableSslVerification: (optional) A flag that indicates whether verification of the server's SSL
291+ - disableSslVerification: (optional) A flag that indicates whether verification of the server's SSL
291292certificate should be disabled or not. The default value is ` false ` .
292293
293294- headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
@@ -612,11 +613,11 @@ const service = ExampleServiceV1.newInstance(options);
612613```
613614
614615
615- ## Multi-Cloud Saas Platform (MCSP) Authentication
616+ ## Multi-Cloud Saas Platform (MCSP) V1 Authentication
616617The ` McspAuthenticator ` can be used in scenarios where an application needs to
617618interact with an IBM Cloud service that has been deployed to a non-IBM Cloud environment (e.g. AWS).
618- It accepts a user-supplied apikey and performs the necessary interactions with the
619- Multi-Cloud Saas Platform token service to obtain a suitable MCSP access token (a bearer token)
619+ It accepts a user-supplied apikey and invokes the Multi-Cloud Saas Platform token service's
620+ ` POST /siusermgr/api/1.0/apikeys/ token` operation to obtain a suitable MCSP access token (a bearer token)
620621for the specified apikey.
621622The authenticator will also obtain a new bearer token when the current token expires.
622623The bearer token is then added to each outbound request in the ` Authorization ` header in the
@@ -684,6 +685,109 @@ const service = ExampleServiceV1.newInstance(options);
684685```
685686
686687
688+ ## Multi-Cloud Saas Platform (MCSP) V2 Authentication
689+ The ` McspV2Authenticator ` can be used in scenarios where an application needs to
690+ interact with an IBM Cloud service that has been deployed to a non-IBM Cloud environment (e.g. AWS).
691+ It accepts a user-supplied apikey and invokes the Multi-Cloud Saas Platform token service's
692+ ` POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` operation to obtain a suitable MCSP access token (a bearer token)
693+ for the specified apikey.
694+ The authenticator will also obtain a new bearer token when the current token expires.
695+ The bearer token is then added to each outbound request in the ` Authorization ` header in the
696+ form:
697+ ```
698+ Authorization: Bearer <bearer-token>
699+ ```
700+
701+ ### Properties
702+
703+ - apikey: (required) The apikey to be used to obtain an MCSP access token.
704+
705+ - url: (required) The URL representing the MCSP token service endpoint's base URL string. Do not include the
706+ operation path (e.g. ` /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` ) as part of this property's value.
707+
708+ - scopeCollectionType: (required) The scope collection type of item(s).
709+ The valid values are: ` accounts ` , ` subscriptions ` , ` services ` .
710+
711+ - scopeId: (required) The scope identifier of item(s).
712+
713+ - includeBuiltinActions: (optional) A flag to include builtin actions in the ` actions ` claim in the MCSP token (default: false).
714+
715+ - includeCustomActions: (optional) A flag to include custom actions in the ` actions ` claim in the MCSP token (default: false).
716+
717+ - includeRoles: (optional) A flag to include the ` roles ` claim in the MCSP token (default: true).
718+
719+ - prefixRoles: (optional) A flag to add a prefix with the scope level where
720+ the role is defined in the ` roles ` claim (default: false).
721+
722+ - callerExtClaim: (optional) A map containing keys and values to be injected into the returned access token
723+ as the ` callerExt ` claim. The keys used in this map must be enabled in the apikey by setting the
724+ ` callerExtClaimNames ` property when the apikey is created.
725+ This property is typically only used in scenarios involving an apikey with identityType ` SERVICEID ` .
726+
727+ - disableSSLVerification: (optional) A flag that indicates whether verification of the server's SSL
728+ certificate should be disabled or not. The default value is ` false ` .
729+
730+ - headers: (optional) A set of key/value pairs that will be sent as HTTP headers in requests
731+ made to the MCSP token service.
732+
733+ ### Usage Notes
734+ - When constructing an McspV2Authenticator instance, the apikey, url, scopeCollectionType, and scopeId properties are required.
735+
736+ - If you specify the callerExtClaim map, the keys used in the map must have been previously enabled in the apikey
737+ by setting the ` callerExtClaimNames ` property when you created the apikey.
738+ The entries contained in this map will appear in the ` callerExt ` field (claim) of the returned access token.
739+
740+ - The authenticator will invoke the token server's ` POST /api/2.0/{scopeCollectionType}/{scopeId}/apikeys/token ` operation to
741+ exchange the apikey for an MCSP access token (the bearer token).
742+
743+ ### Programming example
744+ ``` js
745+ const { McspV2Authenticator } = require (' ibm-cloud-sdk-core'
746+ const ExampleServiceV1 = require (' <sdk-package-name>/example-service/v1'
747+
748+ const authenticator = new McspV2Authenticator ({
749+ apikey: ' myapikey'
750+ url: ' https://example.mcsp.token-exchange.com'
751+ scopeCollectionType: ' accounts'
752+ scopeId: ' 20250519-2128-3755-60b3-103e01c509e8'
753+ includeBuiltinActions: true ,
754+ callerExtClaim: {' productID' : ' prod-123'
755+ });
756+
757+ const options = {
758+ authenticator,
759+ };
760+
761+ const service = new ExampleServiceV1 (options);
762+
763+ // 'service' can now be used to invoke operations.
764+ ```
765+
766+ ### Configuration example
767+ External configuration:
768+ ```
769+ export EXAMPLE_SERVICE_AUTH_TYPE=mcspv2
770+ export EXAMPLE_SERVICE_APIKEY=myapikey
771+ export EXAMPLE_SERVICE_AUTH_URL=https://example.mcspv2.token-exchange.com
772+ export EXAMPLE_SERVICE_SCOPE_COLLECTION_TYPE=accounts
773+ export EXAMPLE_SERVICE_SCOPE_ID=20250519-2128-3755-60b3-103e01c509e8
774+ export EXAMPLE_SERVICE_INCLUDE_BUILTIN_ACTIONS=true
775+ export EXAMPLE_SERVICE_CALLER_EXT_CLAIM={"productID":"prod-123"}
776+ ```
777+ Application code:
778+ ``` js
779+ const ExampleServiceV1 = require (' <sdk-package-name>/example-service/v1'
780+
781+ const options = {
782+ serviceName: ' example_service'
783+ };
784+
785+ const service = ExampleServiceV1 .newInstance (options);
786+
787+ // 'service' can now be used to invoke operations.
788+ ```
789+
790+
687791## No Auth Authentication
688792The ` NoAuthAuthenticator ` is a placeholder authenticator which performs no actual authentication function.
689793It can be used in situations where authentication needs to be bypassed, perhaps while developing
0 commit comments