@entrustcorp/idaas-auth-js/dist/index.d.ts

IDaaS Authentication SDK for SPA applications

/**
 * The configurable options when requesting an authentication challenge.
 */
export declare interface AuthenticationRequestParams extends BaseLoginOptions {
    /**
     * The user ID of the user to request the challenge for.
     */
    userId?: string;
    /**
     * The preferred method of authentication.
     */
    preferredAuthenticationMethod?: IdaasAuthenticationMethod;
    /**
     * Determines if the preferred authentication method must be used.
     */
    strict?: boolean;
    /**
     * Options available during TOKENPUSH authentication
     */
    tokenPushOptions?: TokenPushOptions;
    /**
     * Options available during FACE authentication
     */
    faceBiometricOptions?: FaceBiometricOptions;
    /**
     * The transaction details of the request.
     */
    transactionDetails?: TransactionDetail[];
}

export declare interface AuthenticationResponse {
    token?: string;
    /**
     * A flag indicating if authentication has been completed.
     */
    authenticationCompleted?: boolean;
    /**
     * The second factor authenticator that will be used.
     */
    secondFactorMethod?: IdaasAuthenticationMethod;
    /**
     * The method of authentication that will be used.
     */
    method?: IdaasAuthenticationMethod;
    /**
     * A flag indicating if `pollAuth` should be called.
     */
    pollForCompletion?: boolean;
    /**
     * The user ID of the authenticated user.
     */
    userId?: string;
    /**
     * Parameters required for completing the `GRID` authentication method.
     */
    gridChallenge?: GridChallenge;
    /**
     * Parameters required for completing the `KBA` authentication method.
     */
    kbaChallenge?: KbaChallenge;
    /**
     * Parameters required for completing the `FACE` authentication method.
     *
     * TODO: onfido SDK integration, not necessary when complete. Required for WEB bio auth
     */
    faceChallenge?: FaceChallenge;
    /**
     * Parameters defining the behaviour of the `TEMP_ACCESS_CODE` authentication method.
     */
    tempAccessCodeChallenge?: TempAccessCodeChallenge;
    /**
     * Push authentication mutual challenge for token or Face Biometric.
     */
    pushMutualChallenge?: string;
    /**
     * The PublicKeyCredentialRequestOptions to be passed in the publicKey field to the navigator.credential.get() call.
     */
    publicKeyCredentialRequestOptions?: PublicKeyCredentialRequestOptions;
}

/**
 * The configurable options when submitting a response to an authentication challenge.
 */
export declare interface AuthenticationSubmissionParams {
    /**
     * The user's response to the authentication challenge.
     */
    response?: string;
    /**
     * The user's answers to the KBA challenge questions.
     * Answers must be in the order of the questions returned when requesting the challenge.
     */
    kbaChallengeAnswers?: string[];
    /**
     * The credential returned from navigator.credentials.get(credentialRequestOptions).
     */
    credential?: Credential;
}

/**
 * The configurable options for the `login` and `requestChallenge` methods.
 */
declare interface BaseLoginOptions {
    /**
     * The audience to be used for requesting API access. This defaults to the `globalAudience` set in your `IdaasClientOptions` if not set.
     */
    audience?: string;
    /**
     * The scope to be used on this authentication request.
     *
     * This defaults to the `globalScope` in your `IdaasClientOptions` if not set. If you are setting extra scopes and require `profile` and `email` to be included then you must include them in the provided scope.
     *
     * Note: The `openid` scope is always applied regardless of this setting.
     */
    scope?: string;
    /**
     * Determines whether the token obtained from this login request can use refresh tokens.  This defaults to the `globalUseRefreshToken` set in your `IdaasClientOptions` if not set.
     *
     * Note: Use of refresh tokens must be enabled on your IDaaS client application.
     */
    useRefreshToken?: boolean;
    /**
     * Specifies the maximum age of a token, this value does not change on token refresh.
     */
    maxAge?: number;
}

/**
 * The configurable options when requesting a FACE authentication challenge.
 */
declare interface FaceBiometricOptions extends MutualChallenge {
}

/**
 * Parameters returned to initialize a Face Biometric authenticator.
 */
export declare type FaceChallenge = {
    /**
     * Which device to use for registration and authentication.
     */
    device?: 'WEB' | 'MOBILE';
    /**
     * The ID of the Face Biometric to get.
     */
    id?: string;
    /**
     * QR Code to use to launch the mobile flow.
     */
    qrCode?: string;
    /**
     * The SDK token generated for the user.
     */
    sdkToken?: string;
    /**
     * Workflow run ID to use for the user.
     */
    workflowRunId?: string;
};

/**
 * The configurable options for a fallback login.
 */
declare interface FallbackAuthorizationOptions {
    /**
     * The URI to be redirected to after a successful login. The default value is the current page.
     * This URI must be included in the `Login Redirect URI(s)` field in your IDaaS client application settings.
     */
    redirectUri?: string;
    /**
     * Determines whether the token obtained from this login request can use refresh tokens.  This defaults to the `globalUseRefreshToken` set in your `IdaasClientOptions` if not set.
     *
     * Note: Use of refresh tokens must be enabled on your IDaaS client application.
     */
    useRefreshToken?: boolean;
    /**
     * Determines the method of login that will be used to authenticate the user.
     * The default setting is `false`.
     */
    popup?: boolean;
    /**
     * Determines the strength/quality of the method used to authenticate the user.
     */
    acrValues?: string[];
}

/**
 * If the authentication challenge is of type FIDO, the FIDOChallenge will contain the FIDO challenge parameters that must be passed to the FIDO token to complete authentication.
 */
export declare type FIDOChallenge = {
    /**
     * The list of IDs of the FIDO tokens registered for the user. Each value is base-64 encoded.
     */
    allowCredentials?: Array<(string)>;
    /**
     * A random challenge. It is a base-64 encoded value.
     */
    challenge: string;
    /**
     * The number of seconds that the client will wait for the FIDO token to respond.
     */
    timeout: number;
};

/**
 * The configurable options when requesting an AccessToken.
 */
export declare interface GetAccessTokenOptions {
    /**
     * The audience the token must have. This defaults to the `globalAudience` in your `IdaasClientOptions` if not set.
     */
    audience?: string;
    /**
     * The scope(s) the token must have. This defaults to the `globalScope` in your `IdaasClientOptions` if not set.
     */
    scope?: string;
    /**
     * The acr value(s) that are acceptable for this token to have, the returned token's acr claim will be one of these values.
     */
    acrValues?: string[];
    /**
     * The values that will be used to attempt a login if the requested token is not found.
     */
    fallbackAuthorizationOptions?: FallbackAuthorizationOptions;
}

/**
 * If the authentication challenge is of type grid, the GridChallenge object will contain the grid challenge that the end user must answer.
 */
export declare type GridChallenge = {
    /**
     * The grid challenge specifies a list of grid cells that the user must answer in their challenge.
     */
    challenge: Array<GridChallengeCell>;
    /**
     * The grid details.
     */
    gridInfo: Array<GridInfo>;
    /**
     * The numCharsPerCell value specifies the number of characters expected in the response for each cell as defined by current settings.
     */
    numCharsPerCell: number;
    /**
     * The serial numbers of the grids that can be used to answer this challenge.
     * @deprecated
     */
    serialNumbers: Array<(string)>;
};

/**
 * A GridChallengeCell specifies one cell in a grid by its row and column coordinates.  Normally a grid challenge cell is displayed using letters for the column and numbers for the row.  For example, a cell with the value 0,0 will be displayed as A1.
 */
declare type GridChallengeCell = {
    /**
     * The column within the grid starting at 0.
     */
    column: number;
    /**
     * The row within the grid starting at 0.
     */
    row: number;
};

/**
 * Details about the grid.
 */
declare type GridInfo = {
    /**
     * The expiry date of the grid. Null value indicates the grid will never expire.
     */
    expiryDate?: string;
    /**
     * The serial number of the grid that can be used to answer this challenge.
     */
    serialNumber: string;
};

export declare type IdaasAuthenticationMethod = "PASSWORD" | "KBA" | "TEMP_ACCESS_CODE" | "OTP" | "GRID" | "TOKEN" | "TOKENPUSH" | "FIDO" | "SMARTCREDENTIALPUSH" | "PASSWORD_AND_SECONDFACTOR" | "PASSKEY" | "FACE";

export declare class IdaasClient {
    private readonly storageManager;
    private readonly issuerUrl;
    private readonly clientId;
    private readonly globalScope;
    private readonly globalAudience;
    private readonly globalUseRefreshToken;
    private authenticationTransaction?;
    private config?;
    constructor({ issuerUrl, clientId, globalAudience, globalScope, globalUseRefreshToken, storageType, }: IdaasClientOptions);
    /**
     * Perform the authorization code flow by authenticating the user to obtain an access token and optionally refresh and
     * ID tokens.
     *
     * If using redirect (i.e. popup=false), your application must also be configured to call handleRedirect at the redirectUri
     * to complete the flow.
     * */
    login({ audience, scope, redirectUri, useRefreshToken, popup, acrValues, maxAge, }?: OidcLoginOptions): Promise<string | null>;
    /**
     * Perform the authorization code flow using a new popup window at the OpenID Provider (OP) to authenticate the user.
     */
    private loginWithPopup;
    /**
     * Perform the authorization code flow by redirecting to the OpenID Provider (OP) to authenticate the user and then redirect
     * with the necessary state and code.
     */
    private loginWithRedirect;
    /**
     * Handle the callback to the login redirectUri post-authorize and pass the received code to the token endpoint to get
     * the access token, ID token, and optionally refresh token (optional). Additionally, validate the ID token claims.
     */
    handleRedirect(): Promise<null>;
    /**
     * Fetch the user information stored in the id_token
     * @returns returns the decodedIdToken containing the user info.
     */
    getIdTokenClaims(): UserClaims | null;
    isAuthenticated(): boolean;
    /**
     * Clear the application session and navigate to the OpenID Provider's (OP) endsession endpoint.
     */
    logout({ redirectUri }?: LogoutOptions): Promise<void>;
    /**
     * Removes tokens from storage that have surpassed their max_age, and tokens that are expired and not refreshable.
     */
    private removeUnusableTokens;
    /**
     * Returns an access token with the required scopes and audience that is unexpired or refreshable.
     * The `fallbackAuthorizationOptions` parameter determines the result if there are no access tokens with the required scopes and audience that are unexpired or refreshable.
     */
    getAccessToken({ audience, scope, acrValues, fallbackAuthorizationOptions, }?: GetAccessTokenOptions): Promise<string | null>;
    private parseAndSaveTokenResponse;
    /**
     * Get the user claims from the OpenId Provider using the userinfo endpoint.
     *
     * @param accessToken when provided its scopes will be used to determine the claims returned from the userinfo endpoint.
     * If not provided, the access token with the default scopes and audience will be used if available.
     */
    getUserInfo(accessToken?: string): Promise<UserClaims | null>;
    private parseRedirect;
    private parseLoginRedirect;
    private validateAuthorizeResponse;
    private requestAndValidateTokens;
    private requestTokenUsingRefreshToken;
    /**
     * Generate the authorization url by generating searchParams. codeVerifier will need to be stored for use after redirect.
     */
    private generateAuthorizationUrl;
    /**
     * Generate the endsession url with the required query params to log out the user from the OpenID Provider
     */
    private generateLogoutUrl;
    private getConfig;
    private initializeAuthenticationTransaction;
    requestChallenge(options?: AuthenticationRequestParams): Promise<AuthenticationResponse>;
    authenticatePassword: ({ options, password, }: {
        options: AuthenticationRequestParams;
        password: string;
    }) => Promise<AuthenticationResponse>;
    pollAuth(): Promise<AuthenticationResponse>;
    cancelAuth(): Promise<void>;
    submitChallenge(options?: AuthenticationSubmissionParams): Promise<AuthenticationResponse>;
    private handleAuthenticationTransactionSuccess;
}

/**
 * The configurable options of the IdaasClient.
 */
export declare interface IdaasClientOptions {
    /**
     * The issuer to be used for validation of JWTs and for fetching API endpoints, typically `https://{yourIdaasDomain}.region.trustedauth.com/api/oidc`.
     */
    issuerUrl: string;
    /**
     * The Client ID found on your IDaaS Application settings page.
     */
    clientId: string;
    /**
     * The storage mechanism to use for ID and access tokens.
     *
     * @default "memory"
     */
    storageType?: "memory" | "localstorage";
    /**
     * The global scope to be used.
     *
     * This defaults to `openid profile email` if not set. If you are setting extra scopes and require `profile` and `email` to be included then you must include them in the provided scope.
     *
     * Note: The `openid` scope is always applied regardless of this setting.
     */
    globalScope?: string;
    /**
     * The global audience to be used for requesting API access.
     */
    globalAudience?: string;
    /**
     * If true, refresh tokens are used to fetch new access tokens from the IDaaS server.
     * The default setting is `false`.
     *
     * Note: Use of refresh tokens must be enabled on your IDaaS client application. Tokens using refresh tokens will have the `offline_access` scope applied.
     */
    globalUseRefreshToken?: boolean;
}

/**
 * Knowledge-based authenticator required for authentication to Identity as a Service
 */
export declare type KbaChallenge = {
    id?: string;
    userQuestions: Array<UserQuestion>;
};

/**
 * The configurable options for the Logout method.
 */
export declare interface LogoutOptions {
    /**
     * The URI to be redirected to after a successful logout. This URI must be included in the `Logout Redirect URI(s)` field in your IDaaS client application settings.
     */
    redirectUri?: string;
}

declare interface MutualChallenge {
    /**
     * Determines if the user must answer a mutual challenge for the TOKENPUSH and FACE authenticators.
     */
    mutualChallengeEnabled?: boolean;
}

/**
 * The configurable options specific to the OIDC `login` method.
 */
export declare interface OidcLoginOptions extends BaseLoginOptions {
    /**
     * The URI to be redirected to after a successful login. The default value is the current page.
     * This URI must be included in the `Login Redirect URI(s)` field in your IDaaS client application settings.
     */
    redirectUri?: string;
    /**
     * Determines the method of login that will be used to authenticate the user.
     * The default setting is `false`.
     */
    popup?: boolean;
    /**
     * Determines the strength/quality of the method used to authenticate the user.
     */
    acrValues?: string[];
}

/**
 * Information about the temporary access code settings.
 */
export declare type TempAccessCodeChallenge = {
    /**
     * An optional admin contact value (like an admin email address or phone number) to be displayed in the admin contact message.
     */
    adminContact?: string;
    /**
     * Indicates if the admin contact message should be displayed for this challenge.
     */
    enableAdminContact?: boolean;
};

/**
 * The configurable options when requesting a TOKENPUSH authentication challenge.
 */
declare interface TokenPushOptions extends MutualChallenge {
}

/**
 * Transaction detail item and its value used with push authenticators and with offline transaction verification.
 */
declare type TransactionDetail = {
    /**
     * The transaction detail name.
     */
    detail?: string;
    usage?: Array<('RBA' | 'TVS')>;
    /**
     * The transaction detail value.
     */
    value?: string;
};

/**
 * The standard user claims of OIDC.
 */
export declare interface UserClaims {
    sub?: string;
    name?: string;
    given_name?: string;
    family_name?: string;
    middle_name?: string;
    nickname?: string;
    preferred_username?: string;
    profile?: string;
    picture?: string;
    website?: string;
    email?: string;
    email_verified?: boolean;
    gender?: string;
    birthdate?: string;
    zoneinfo?: string;
    locale?: string;
    phone_number?: string;
    phone_number_verified?: boolean;
    address?: string;
    updated_at?: number;
    [propName: string]: unknown;
}

/**
 * A KBA question/answer stored for a user.
 */
declare type UserQuestion = {
    /**
     * The question's answer.
     */
    answer?: string;
    /**
     * The UUID of the KBA question/answer.
     */
    id?: string;
    /**
     * The question.
     */
    question?: string;
};

export { }