@magda/authentication-plugin-sdk/dist/index.d.ts

MAGDA Authentication Plugin SDK

import AuthApiClient from '@magda/auth-api-client';
import { CookieOptions as CookieOptions_3 } from 'express';
import express from 'express';
import passport from 'passport';
import { QueryDataMap } from 'urijs';
import { Request as Request_2 } from 'express';
import { Response as Response_2 } from 'express';
import { Router } from 'express';
import { User } from '@magda/auth-api-client';
import { UserToken } from '@magda/auth-api-client';

/**
 * Different type of AuthenticationMethod:
 * - IDP-URI-REDIRECTION: the plugin will redirect user agent to idp (identity provider) for authentication. e.g. Google & fackebook oauth etc.
 *   - This is the default method.
 * - PASSWORD: the plugin expect frontend do a form post that contains username & password to the plugin for authentication
 * - QR-CODE: the plugin offers a url that is used by the frontend to request auth challenge data. The data will be encoded into a QR-code image and expect the user scan the QR code with a mobile app to complete the authentication request.
 *   - Once the QR-code image is generated, the frontend is expected to start polling a pre-defined plugin url to check whether the authentication is complete or not.
 */
export declare type AuthenticationMethod = "IDP-URI-REDIRECTION" | "PASSWORD" | "QR-CODE";

/**
 * Basic Auth Plugin are the config info that supplied to Gateway
 * via [authPlugins](https://github.com/magda-io/magda/tree/master/deploy/helm/internal-charts/gateway) helm chart config
 */
export declare type AuthPluginBasicConfig = {
    key: string;
    baseUrl: string;
};

export declare interface AuthPluginConfig extends Omit<AuthPluginBasicConfig, "baseUrl"> {
    name: string;
    iconUrl: string;
    authenticationMethod: AuthenticationMethod;
    loginFormExtraInfoHeading?: string;
    loginFormExtraInfoContent?: string;
    loginFormUsernameFieldLabel?: string;
    loginFormPasswordFieldLabel?: string;
    qrCodeImgDataRequestUrl?: string;
    qrCodeAuthResultPollUrl?: string;
    qrCodeExtraInfoHeading?: string;
    qrCodeExtraInfoContent?: string;
}

export declare type CookieOptions = CookieOptions_2;

declare type CookieOptions_2 = CookieOptions_3;

/**
 * Create an express router that can be used to enable session on an express application.
 *
 * @export
 * @param {MagdaSessionRouterOptions} options
 * @returns {Router}
 */
export declare function createMagdaSessionRouter(options: MagdaSessionRouterOptions): Router;

/**
 * Verify the user using the user profile received during the authentication.
 * If a user can be located, return UserToken type data.
 * Otherwise, create a new user and return UserToken type data .
 *
 * @export
 * @param {AuthApiClient} authApi
 * @param {passport.Profile} profile
 * @param {string} source
 * @param {(
     *         authApiClient: AuthApiClient,
     *         userData: User,
     *         profile: passport.Profile
     *     ) => Promise<User>} [beforeUserCreated] an optional handler that will be called just before a user is created.
 * The user data returned by this handler will be used to create the user record. The following parameters will be provided to the handler:
 * - authApiClient: Auth API Client. You can use it to add a role to the user.
 * - userData: the user data that is converted from the user profile received using the default conversion logic.
 * - profile: the user profile received
 *
 * @param {(
     *         authApiClient: AuthApiClient,
     *         user: User,
     *         profile: passport.Profile
     *     ) => Promise<void>} [afterUserCreated] an optional call that will be called when a user has just been created.
 * The following parameters will be provided to the handler:
 * - authApiClient: Auth API Client. You can use it to add a role to the user.
 * - user: the user data of the magda user that is just created.
 * - profile: the user profile received
 *
 * @returns {Promise<UserToken>}
 */
export declare function createOrGetUserToken(authApi: AuthApiClient, profile: passport.Profile, source: string, beforeUserCreated?: (authApiClient: AuthApiClient, userData: User, profile: passport.Profile) => Promise<User>, afterUserCreated?: (authApiClient: AuthApiClient, user: User, profile: passport.Profile) => Promise<void>): Promise<UserToken>;

export declare const DEFAULT_SESSION_COOKIE_NAME: string;

export declare const DEFAULT_SESSION_COOKIE_OPTIONS: CookieOptions_3;

export declare const deleteCookie: typeof deleteCookie_2;

declare function deleteCookie_2(cookieName: string, cookieOptions: CookieOptions_2, res: express.Response): void;

/**
 * Complete destroy Magda session and remove session cookie from the user agent
 *
 * @export
 * @param {Request} req
 * @param {Response} res
 * @param {SessionCookieOptions} cookieOptions
 * @return {*}  {Promise<void>}
 */
export declare function destroyMagdaSession(req: Request_2, res: Response_2, cookieOptions: SessionCookieOptions): Promise<void>;

export declare const destroySession: typeof destroySession_2;

/**
 * destroy the session.
 *  - will delete the session data from session store only.
 *  - will not delete session cookie (Call deleteCookie method for deleting cookie)
 * @export
 * @param {express.Request} req
 * @return {*}  {Promise<void>}
 */
declare function destroySession_2(req: express.Request): Promise<void>;

/**
 * Join `url` with `baseUrl` if `url` is not an absolute (full) url string
 *
 * @export
 * @param {string} url A full url string or a url path string (/a/b/c).
 * @param {string} baseUrl A baseUrl used to generate a full url when a url path string is supplied via the `url` parameter.
 * @param {QueryDataMap} [optionalQueries]
 * @param {string[]} [allowedUrlHosts] Optional; when specify, the host of `url` parameter will only be used if it is included by this list.
 * @returns
 */
export declare function getAbsoluteUrl(url: string, baseUrl: string, optionalQueries?: QueryDataMap, allowedUrlHosts?: string[]): string;

export declare function getSessionId(req: express.Request, secret?: string): string;

export declare type MagdaSessionRouterOptions = {
    cookieOptions: SessionCookieOptions;
    sessionSecret: string;
    sessionDBHost: string;
    sessionDBPort: number;
    sessionDBUser?: string;
    sessionDBPassword?: string;
    sessionDBName?: string;
};

export declare function redirectOnError(err: any, toURL: string, req: Request_2, res: Response_2): void;

export declare function redirectOnSuccess(toURL: string, req: Request_2, res: Response_2): void;

export declare type SessionCookieOptions = CookieOptions_2;

export { }