@zowe/imperative/lib/rest/src/session/AuthOrder.d.ts

framework for building configurable CLIs

import { ICommandArguments } from "../../../cmd";
import { ISession } from "./doc/ISession";
import * as SessConstants from "./SessConstants";
import { Config } from "../../../config";
/**
 * This interface represents options for the function putNewAuthsFirstInSess.
 * If true, only the newFirstAuths will be in the result.
 * If false, any existing auth types will remain later in the array.
 */
export interface INewFirstAuthsOpts {
    onlyTheseAuths?: boolean;
}
/**
 * This interface adds options for the function putNewAuthsFirstOnDisk.
 * A client Config object can also be supplied.
 */
export interface INewFirstAuthsOnDiskOpts extends INewFirstAuthsOpts {
    clientConfig?: Config;
}
/**
 * This enum is used to specify if a property is to be used in
 * a session or in a config file.
 */
export declare enum PropUse {
    IN_SESS = 0,
    IN_CFG = 1
}
/**
 * The purpose of this class is to detect an authentication order property
 * supplied by a user in a profile, command line, or environment variable.
 * That authOrder is then used to place the correct set of credentials into
 * a session for authentication.
 *
 * To accomplish this behavior, we call AuthOrder.addCredsToSession
 * early in the processing of a command (when both a session
 * configuration and command arguments are available). For example in:
 *      ConnectionPropsForSessCfg.addPropsOrPrompt or
 *      ProfileInfo.createSession
 *
 * Before we use the session, we call AuthOrder.putTopAuthInSession.
 * For example in:
 *      AbstractRestClient.constructor
 *      AbstractRestClient.request
 * AuthOrder.putTopAuthInSession ensures that the session only contains the
 * credentials for the desired type of authentication.
 */
export declare class AuthOrder {
    private static readonly SESS_CERT_NAME;
    private static readonly SESS_CERT_KEY_NAME;
    private static readonly ARRAY_OF_CREDS;
    /**
     * Add available credentials (and the authentication order in which
     * credentials should be chosen) into a cache within the specified session.
     * Using that cached information put only the top selected credential as
     * the credential to be used by the session.
     *
     * @param sessCfg - Modified.
     *      A session configuration object into which we place cached creds
     *      and the selected creds.
     *
     * @param cmdArgs - Input.
     *      The set of arguments with which the calling function is operating.
     *      For CLI, the cmdArgs come from the command line, profile, or
     *      environment. Other apps can place relevant arguments into this
     *      object to be processed by this function.
     *
     *      If cmdArgs is not supplied, we only cache creds found in the sessCfg.
     */
    static addCredsToSession<SessCfgType extends ISession>(sessCfg: SessCfgType, cmdArgs?: ICommandArguments): void;
    /**
     * Record that the session is being used to make a request for a token
     * (ie logging into APIML).
     *
     * @param sessCfg - Modified.
     *      The session config into which we record that we are requesting a token.
     */
    static makingRequestForToken<SessCfgType extends ISession>(sessCfg: SessCfgType): void;
    /**
     * Put the specified array of auth types first in the authOrder for the
     * specified session. Duplicates are removed from the resulting authOrder
     * array. Any existing auth types remain later in the array,
     * unless newAuthsOpts.onlyTheseAuths is true.
     *
     * Calling apps should NOT use this function to impose a hard-coded
     * authentication order for the session. Users control that decision.
     * Apps should only call this function if the app is implementing a directive
     * from the user which implies that the authOrder should be changed. An example
     * is when a user logs into APIML. The implication is that the user wants to use
     * a token, and that tokens should be at the front of the authentication order.
     *
     * @param sessCfg - Modified.
     *      The session config into which we place the modified array of auth types.
     *
     * @param newFirstAuths - input.
     *      An array of one or more auth types to be placed at the front of the
     *      the existing array of auth types.
     *
     * @param newAuthsOpts - input.
     *      Options that control some replacement choices.
     *
     * @throws {ImperativeError}
     *      If sessCfg is null or undefined.
     */
    static putNewAuthsFirstInSess<SessCfgType extends ISession>(sessCfg: SessCfgType, newFirstAuths: SessConstants.AUTH_TYPE_CHOICES[], newAuthsOpts?: INewFirstAuthsOpts): void;
    /**
     * Put the specified array of auth types first in the authOrder property
     * for the specified profile and save it to the client config file on disk.
     * A new authOrder property will be created if needed.
     * Duplicates from any existing authOrder are removed from the resulting authOrder.
     * Any existing auth types remain later in the property value, unless
     * newAuthsOpts.onlyTheseAuths is true.
     *
     * Calling apps should NOT use this function to impose a hard-coded
     * authentication order for a profile. Users control that decision.
     * Apps should only call this function if the app is implementing a directive
     * from the user which implies that the authOrder should be changed. An example
     * is when a user logs into APIML. The implication is that the user wants to use
     * a token, and that tokens should be at the front of the authentication order.
     *
     * @param profileName - input.
     *      The name of the profile into which the authOrder property will be placed.
     *
     * @param newFirstAuths - input.
     *      An array of one or more auth types to be placed at the front of the
     *      the existing array of auth types.
     *
     * @param newAuthsOpts - input.
     *      Options that control some replacement choices.
     *
     * @throws {ImperativeError}
     *      Any detected error is in the 'message' of the ImperativeError.
     */
    static putNewAuthsFirstOnDisk(profileName: string, newFirstAuths: SessConstants.AUTH_TYPE_CHOICES[], newAuthsOnDiskOpts?: INewFirstAuthsOnDiskOpts): Promise<void>;
    /**
     * Form a new auth type array from an existing array and a second array
     * whose members should come first in the new array.
     * Duplicates are removed from the resulting authOrder array.
     * Any auth types from the existing array remain later in the array,
     * unless newAuthsOpts.onlyTheseAuths is true.
     *
     * @param existingAuths - input.
     *      An existing array of auth types.
     *
     * @param newFirstAuths - input.
     *      An array of one or more auth types to be placed at the front of the
     *      the existing array of auth types.
     *
     * @param newAuthsOpts - input.
     *      Options that control some replacement choices.
     *
     * @returns A new array of AUTH_TYPE_CHOICES.
     */
    private static formNewAuthOrderArray;
    /**
     * Convert an AUTH_TYPE_CHOICES array to a string that is an appropriate
     * value for the "authOrder" configuration property.
     *
     * @param authTypesArray - input.
     *      An array of auth types.
     *
     * @returns A string containing a valid value for the authOrder configuration property.
     */
    private static authArrayToCfgVal;
    /**
     * Convert a string that is an appropriate value for the "authOrder"
     * configuration property into an array of AUTH_TYPE_CHOICES.
     *
     * @param authCfgVal - input.
     *      An authOrder property value.
     *
     * @returns An array of AUTH_TYPE_CHOICES.
     */
    private static authCfgValToArray;
    /**
     * Cache all of the credentials that are available in either the supplied
     * sessCfg object or in the supplied command arguments. Also cache the
     * authOrder that is specified in the supplied command arguments. The
     * cache properties are stored into the sessCfg object itself.
     *
     * Downstream logic uses this cache to determine which auth type should be
     * used in the final session used by a client REST request.
     *
     * @param sessCfg - Modified.
     *      A session configuration object to which we place the cached creds.
     *
     * @param cmdArgs - Input.
     *      The set of arguments with which the calling function is operating.
     *      For CLI, the cmdArgs come from the command line, profile, or
     *      environment. Other apps can place relevant arguments into this
     *      object to be processed by this function.
     *
     *      If cmdArgs is not supplied, we only cache creds found in the sessCfg.
     */
    private static cacheCredsAndAuthOrder;
    /**
     * Cache the authOrder property from the supplied cmdArgs. If no authOrder exists
     * in cmdArgs, a default authOrder is created and cached.
     *
     * @param sessCfg - Modified.
     *      A session configuration object into which we store the auth cache.
     *
     * @param cmdArgs - Input.
     *      The set of arguments that the calling function is using.
     */
    private static cacheAuthOrder;
    /**
     * Cache the named credential into our cache of available credentials.
     *
     * @param sessCredName - Input.
     *      The name of a cred to be cached in a session.
     *
     * @param sessCfg - Modified.
     *      A session configuration object.
     *
     * @param cmdArgs - Input.
     *      The set of arguments with which the calling function is operating.
     */
    private static cacheCred;
    /**
     * Choose a default authentication order and place it into the session sessCfg.
     *
     * Other classes in the Zowe client API (like AbstractRestClient) call
     * cacheDefaultAuthOrder to specify the top default authentication type.
     * If so, we keep any topDefaultAuth that has already been set.
     *
     * If topDefaultAuth has NOT been set, we set basic authentication as the
     * topDefaultAuth.
     *
     * @param sessCfg - Modified.
     *      A session configuration object.
     */
    private static chooseDefaultAuthOrder;
    /**
     * Find the auth cache in the session config. If there is no cache
     * recorded in the session config, create a new auth cache entry.
     *
     * @param sessCfg - Input.
     *      A session configuration object into which we record any newly created cache.
     */
    private static findOrCreateAuthCache;
    /**
     * Keep the specified credential by deleting it from the set of
     * credentials to remove.
     *
     * @param credToKeep - Input.
     *      The credential that we want to keep.
     *
     * @param credsToRemove - Modified.
     *      The set of credentials that will be removed.
     */
    private static keepCred;
    /**
     * Remove all credential properties from the supplied session except for the
     * creds related to the session type specified within the sessCfg argument.
     *
     * @param sessCfg - Modified.
     *      Authentication credentials are removed from this session configuration.
     *
     * @throws {ImperativeError}
     *      If an invalid combination of session type and authTypeToRequestToken is encountered.
     */
    private static removeExtraCredsFromSess;
}
//# sourceMappingURL=AuthOrder.d.ts.map