ibm-cloud-sdk-core 4.1.5 → 4.2.0

package/es/auth/authenticators/mcsp-authenticator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * (C) Copyright IBM Corp. 2023.
+ *
+ * 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 { McspTokenManager } from '../token-managers/mcsp-token-manager';
+import { BaseOptions, TokenRequestBasedAuthenticator } from './token-request-based-authenticator';
+/** Configuration options for Multi-Cloud Saas Platform (MCSP) authentication. */
+export interface Options extends BaseOptions {
+    /** The API key used to obtain an MCSP access token. */
+    apikey: string;
+    /** The URL representing the MCSP token service endpoint. */
+    url: string;
+}
+/**
+ * The McspAuthenticator uses an apikey to obtain an access token from the MCSP token server.
+ * When the access token expires, a new access token is obtained from the token server.
+ * The access token will be added to outbound requests via the Authorization header
+ * of the form:    "Authorization: Bearer <access-token>"
+ */
+export declare class McspAuthenticator extends TokenRequestBasedAuthenticator {
+    protected requiredOptions: string[];
+    protected tokenManager: McspTokenManager;
+    private apikey;
+    /**
+     * Create a new McspAuthenticator instance.
+     *
+     * @param options - Configuration options for CloudPakForData authentication.
+     * This should be an object containing these fields:
+     * - url: (required) the endpoint URL for the CloudPakForData token service
+     * - username: (required) the username used to obtain a bearer token
+     * - password: (optional) the password used to obtain a bearer token (required if apikey is not specified)
+     * - apikey: (optional) the API key used to obtain a bearer token (required if password is not specified)
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token requests.
+     */
+    constructor(options: Options);
+    /**
+     * Returns the authenticator's type ('cp4d').
+     *
+     * @returns a string that indicates the authenticator's type
+     */
+    authenticationType(): string;
+}

package/es/auth/authenticators/mcsp-authenticator.js

@@ -0,0 +1,60 @@
+/**
+ * (C) Copyright IBM Corp. 2023.
+ *
+ * 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 { Authenticator } from './authenticator';
+import { McspTokenManager } from '../token-managers/mcsp-token-manager';
+import { TokenRequestBasedAuthenticator } from './token-request-based-authenticator';
+/**
+ * The McspAuthenticator uses an apikey to obtain an access token from the MCSP token server.
+ * When the access token expires, a new access token is obtained from the token server.
+ * The access token will be added to outbound requests via the Authorization header
+ * of the form:    "Authorization: Bearer <access-token>"
+ */
+export class McspAuthenticator extends TokenRequestBasedAuthenticator {
+    /**
+     * Create a new McspAuthenticator instance.
+     *
+     * @param options - Configuration options for CloudPakForData authentication.
+     * This should be an object containing these fields:
+     * - url: (required) the endpoint URL for the CloudPakForData token service
+     * - username: (required) the username used to obtain a bearer token
+     * - password: (optional) the password used to obtain a bearer token (required if apikey is not specified)
+     * - apikey: (optional) the API key used to obtain a bearer token (required if password is not specified)
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token requests.
+     */
+    constructor(options) {
+        super(options);
+        this.requiredOptions = ['apikey', 'url'];
+        this.apikey = options.apikey;
+        this.url = options.url;
+        // the param names are shared between the authenticator and the token
+        // manager so we can just pass along the options object.
+        // also, the token manager will handle input validation
+        this.tokenManager = new McspTokenManager(options);
+    }
+    /**
+     * Returns the authenticator's type ('cp4d').
+     *
+     * @returns a string that indicates the authenticator's type
+     */
+    // eslint-disable-next-line class-methods-use-this
+    authenticationType() {
+        return Authenticator.AUTHTYPE_MCSP;
+    }
+}

package/es/auth/token-managers/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2023.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,15 +21,17 @@
  * Cloud Pak for Data
  * Container (IKS, etc)
  * VPC Instance
+ * Multi-Cloud Saas Platform (MCSP)
  *
  * The token managers sit inside of an authenticator and do the work to retrieve
- * tokens where as the authenticators add these tokens to the actual request.
+ * tokens, whereas the authenticators add these tokens to the actual request.
  *
  * classes:
  *   IamTokenManager: Token Manager of IAM via apikey.
  *   Cp4dTokenManager: Token Manager of CloudPak for data.
  *   ContainerTokenManager: Token manager of IAM via compute resource token.
  *   VpcInstanceTokenManager: Token manager of VPC Instance Metadata Service API tokens.
+ *   McspTokenManager: Token Manager of MCSP via apikey.
  *   JwtTokenManager: A class for shared functionality for parsing, storing, and requesting JWT tokens.
  */
 export { IamTokenManager } from './iam-token-manager';
@@ -39,3 +41,4 @@ export { IamRequestBasedTokenManager, IamRequestOptions } from './iam-request-ba
 export { JwtTokenManager, JwtTokenManagerOptions } from './jwt-token-manager';
 export { TokenManager, TokenManagerOptions } from './token-manager';
 export { VpcInstanceTokenManager } from './vpc-instance-token-manager';
+export { McspTokenManager } from './mcsp-token-manager';

package/es/auth/token-managers/index.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2023.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,15 +21,17 @@
  * Cloud Pak for Data
  * Container (IKS, etc)
  * VPC Instance
+ * Multi-Cloud Saas Platform (MCSP)
  *
  * The token managers sit inside of an authenticator and do the work to retrieve
- * tokens where as the authenticators add these tokens to the actual request.
+ * tokens, whereas the authenticators add these tokens to the actual request.
  *
  * classes:
  *   IamTokenManager: Token Manager of IAM via apikey.
  *   Cp4dTokenManager: Token Manager of CloudPak for data.
  *   ContainerTokenManager: Token manager of IAM via compute resource token.
  *   VpcInstanceTokenManager: Token manager of VPC Instance Metadata Service API tokens.
+ *   McspTokenManager: Token Manager of MCSP via apikey.
  *   JwtTokenManager: A class for shared functionality for parsing, storing, and requesting JWT tokens.
  */
 export { IamTokenManager } from './iam-token-manager';
@@ -39,3 +41,4 @@ export { IamRequestBasedTokenManager } from './iam-request-based-token-manager';
 export { JwtTokenManager } from './jwt-token-manager';
 export { TokenManager } from './token-manager';
 export { VpcInstanceTokenManager } from './vpc-instance-token-manager';
+export { McspTokenManager } from './mcsp-token-manager';

package/es/auth/token-managers/mcsp-token-manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * (C) Copyright IBM Corp. 2023.
+ *
+ * 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 { JwtTokenManager, JwtTokenManagerOptions } from './jwt-token-manager';
+/**
+ * Configuration options for MCSP token retrieval.
+ */
+interface Options extends JwtTokenManagerOptions {
+    /** The API key used to obtain an access token. */
+    apikey: string;
+    /** The base endpoint URL for MCSP token requests. */
+    url: string;
+}
+/**
+ * This interface models the response object received from the MCSP token service.
+ */
+export interface McspTokenData {
+    token: string;
+    token_type: string;
+    expires_in: number;
+}
+/**
+ * Token Manager for Multi-Cloud Saas Platform (MCSP) authenticator.
+ *
+ * The Token Manager will invoke the MCSP token service's 'POST /siusermgr/api/1.0/apikeys/token'
+ * operation to obtain an MCSP access token for a user-supplied apikey.
+ */
+export declare class McspTokenManager extends JwtTokenManager {
+    protected requiredOptions: string[];
+    private apikey;
+    /**
+     * Create a new McspTokenManager instance.
+     *
+     * @param options - Configuration options
+     * This should be an object containing these fields:
+     * - url: (required) the base endpoint URL for the MCSP token service
+     * - apikey: (required) the API key used to obtain the MCSP access token.
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the configuration options were invalid.
+     */
+    constructor(options: Options);
+    protected requestToken(): Promise<any>;
+}
+export {};

package/es/auth/token-managers/mcsp-token-manager.js

@@ -0,0 +1,69 @@
+/**
+ * (C) Copyright IBM Corp. 2023.
+ *
+ * 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 extend from 'extend';
+import { validateInput } from '../utils/helpers';
+import { JwtTokenManager } from './jwt-token-manager';
+/**
+ * This is the path associated with the operation used to obtain
+ * an access token from the MCSP token service.
+ */
+const OPERATION_PATH = '/siusermgr/api/1.0/apikeys/token';
+/**
+ * Token Manager for Multi-Cloud Saas Platform (MCSP) authenticator.
+ *
+ * The Token Manager will invoke the MCSP token service's 'POST /siusermgr/api/1.0/apikeys/token'
+ * operation to obtain an MCSP access token for a user-supplied apikey.
+ */
+export class McspTokenManager extends JwtTokenManager {
+    /**
+     * Create a new McspTokenManager instance.
+     *
+     * @param options - Configuration options
+     * This should be an object containing these fields:
+     * - url: (required) the base endpoint URL for the MCSP token service
+     * - apikey: (required) the API key used to obtain the MCSP access token.
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the configuration options were invalid.
+     */
+    constructor(options) {
+        super(options);
+        this.requiredOptions = ['apikey', 'url'];
+        this.tokenName = 'token';
+        validateInput(options, this.requiredOptions);
+        this.apikey = options.apikey;
+    }
+    requestToken() {
+        const requiredHeaders = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        };
+        const parameters = {
+            options: {
+                url: this.url + OPERATION_PATH,
+                body: {
+                    apikey: this.apikey,
+                },
+                method: 'POST',
+                headers: extend(true, {}, this.headers, requiredHeaders),
+                rejectUnauthorized: !this.disableSslVerification,
+            },
+        };
+        return this.requestWrapperInstance.sendRequest(parameters);
+    }
+}

package/es/auth/utils/get-authenticator-from-environment.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Authenticator, BasicAuthenticator, BearerTokenAuthenticator, CloudPakForDataAuthenticator, IamAuthenticator, ContainerAuthenticator, NoAuthAuthenticator, VpcInstanceAuthenticator, } from '../authenticators';
+import { Authenticator, BasicAuthenticator, BearerTokenAuthenticator, CloudPakForDataAuthenticator, IamAuthenticator, ContainerAuthenticator, NoAuthAuthenticator, VpcInstanceAuthenticator, McspAuthenticator, } from '../authenticators';
 import { readExternalSources } from './read-external-sources';
 /**
  * Look for external configuration of authenticator.
@@ -84,6 +84,9 @@ export function getAuthenticatorFromEnvironment(serviceName) {
     else if (authType === Authenticator.AUTHTYPE_VPC.toLowerCase()) {
         authenticator = new VpcInstanceAuthenticator(credentials);
     }
+    else if (authType === Authenticator.AUTHTYPE_MCSP.toLowerCase()) {
+        authenticator = new McspAuthenticator(credentials);
+    }
     else {
         throw new Error(`Invalid value for AUTH_TYPE: ${authType}`);
     }

package/etc/ibm-cloud-sdk-core.api.md

@@ -34,6 +34,8 @@ export class Authenticator implements AuthenticatorInterface {
     // (undocumented)
     static AUTHTYPE_IAM: string;
     // (undocumented)
+    static AUTHTYPE_MCSP: string;
+    // (undocumented)
     static AUTHTYPE_NOAUTH: string;
     // (undocumented)
     static AUTHTYPE_UNKNOWN: string;
@@ -329,6 +331,27 @@ export class JwtTokenManager extends TokenManager {
 // @public
 export type JwtTokenManagerOptions = TokenManagerOptions;
 
+// @public
+export class McspAuthenticator extends TokenRequestBasedAuthenticator {
+    // Warning: (ae-forgotten-export) The symbol "Options_12" needs to be exported by the entry point index.d.ts
+    constructor(options: Options_12);
+    authenticationType(): string;
+    // (undocumented)
+    protected requiredOptions: string[];
+    // (undocumented)
+    protected tokenManager: McspTokenManager;
+}
+
+// @public
+export class McspTokenManager extends JwtTokenManager {
+    // Warning: (ae-forgotten-export) The symbol "Options_11" needs to be exported by the entry point index.d.ts
+    constructor(options: Options_11);
+    // (undocumented)
+    protected requestToken(): Promise<any>;
+    // (undocumented)
+    protected requiredOptions: string[];
+}
+
 // @public
 export class NoAuthAuthenticator extends Authenticator {
     // (undocumented)

package/ibm-cloud-sdk-core.d.ts

@@ -53,6 +53,7 @@ export declare class Authenticator implements AuthenticatorInterface {
     static AUTHTYPE_CP4D: string;
     static AUTHTYPE_NOAUTH: string;
     static AUTHTYPE_VPC: string;
+    static AUTHTYPE_MCSP: string;
     static AUTHTYPE_UNKNOWN: string;
     /**
      * Create a new Authenticator instance.
@@ -1039,6 +1040,66 @@ export declare class JwtTokenManager extends TokenManager {
 /** Configuration options for JWT token retrieval. */
 export declare type JwtTokenManagerOptions = TokenManagerOptions;
 
+/**
+ * The McspAuthenticator uses an apikey to obtain an access token from the MCSP token server.
+ * When the access token expires, a new access token is obtained from the token server.
+ * The access token will be added to outbound requests via the Authorization header
+ * of the form:    "Authorization: Bearer <access-token>"
+ */
+export declare class McspAuthenticator extends TokenRequestBasedAuthenticator {
+    protected requiredOptions: string[];
+    protected tokenManager: McspTokenManager;
+    private apikey;
+    /**
+     * Create a new McspAuthenticator instance.
+     *
+     * @param options - Configuration options for CloudPakForData authentication.
+     * This should be an object containing these fields:
+     * - url: (required) the endpoint URL for the CloudPakForData token service
+     * - username: (required) the username used to obtain a bearer token
+     * - password: (optional) the password used to obtain a bearer token (required if apikey is not specified)
+     * - apikey: (optional) the API key used to obtain a bearer token (required if password is not specified)
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token requests.
+     */
+    constructor(options: Options_12);
+    /**
+     * Returns the authenticator's type ('cp4d').
+     *
+     * @returns a string that indicates the authenticator's type
+     */
+    authenticationType(): string;
+}
+
+/**
+ * Token Manager for Multi-Cloud Saas Platform (MCSP) authenticator.
+ *
+ * The Token Manager will invoke the MCSP token service's 'POST /siusermgr/api/1.0/apikeys/token'
+ * operation to obtain an MCSP access token for a user-supplied apikey.
+ */
+export declare class McspTokenManager extends JwtTokenManager {
+    protected requiredOptions: string[];
+    private apikey;
+    /**
+     * Create a new McspTokenManager instance.
+     *
+     * @param options - Configuration options
+     * This should be an object containing these fields:
+     * - url: (required) the base endpoint URL for the MCSP token service
+     * - apikey: (required) the API key used to obtain the MCSP access token.
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     *
+     * @throws Error: the configuration options were invalid.
+     */
+    constructor(options: Options_11);
+    protected requestToken(): Promise<any>;
+}
+
 /**
  * NoAuthAuthenticator is a placeholder authenticator implementation which
  * performs no authentication of outgoing REST API requests. It might be
@@ -1082,6 +1143,24 @@ declare interface Options_10 extends BaseOptions {
     iamProfileId?: string;
 }
 
+/**
+ * Configuration options for MCSP token retrieval.
+ */
+declare interface Options_11 extends JwtTokenManagerOptions {
+    /** The API key used to obtain an access token. */
+    apikey: string;
+    /** The base endpoint URL for MCSP token requests. */
+    url: string;
+}
+
+/** Configuration options for Multi-Cloud Saas Platform (MCSP) authentication. */
+declare interface Options_12 extends BaseOptions {
+    /** The API key used to obtain an MCSP access token. */
+    apikey: string;
+    /** The URL representing the MCSP token service endpoint. */
+    url: string;
+}
+
 /** Configuration options for bearer authentication. */
 declare type Options_2 = {
     /** The bearer token to be added to requests. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ibm-cloud-sdk-core",
-  "version": "4.1.5",
+  "version": "4.2.0",
   "description": "Core functionality to support SDKs generated with IBM's OpenAPI SDK Generator.",
   "main": "index.js",
   "typings": "./es/index.d.ts",