@types/passport

property assignProperty

assignProperty?: string | undefined;

• Assign the object provided by the verify callback to given property.

property authInfo

authInfo?: boolean | undefined;

property failureFlash

failureFlash?: string | boolean | undefined;

• True to flash failure messages or a string to use as a flash message for failures (overrides any from the strategy itself).

property failureMessage

failureMessage?: boolean | string | undefined;

• True to store failure message in req.session.messages, or a string to use as override message for failure.

property failureRedirect

failureRedirect?: string | undefined;

• After failed login, redirect to given URL.

property failWithError

failWithError?: boolean | undefined;

property keepSessionInfo

keepSessionInfo?: boolean | undefined;

property passReqToCallback

passReqToCallback?: boolean | undefined;

property pauseStream

pauseStream?: boolean | undefined;

• Pause the request stream before deserializing the user object from the session. Defaults to false. Should be set to true in cases where middleware consuming the request body is configured after passport and the deserializeUser method is asynchronous.

property prompt

prompt?: string | undefined;

• **Note:** The availability of this property depends on the passport strategy you are using. If not explicitly supported by the strategy or implemented by yourself, this property will be ignored.

property scope

scope?: string | string[] | undefined;

property session

session?: boolean | undefined;

• Save login state in session, defaults to true.

property state

state?: string | undefined;

property successFlash

successFlash?: string | boolean | undefined;

• True to flash success messages or a string to use as a flash message for success (overrides any from the strategy itself).

property successMessage

successMessage?: boolean | string | undefined;

• True to store success message in req.session.messages, or a string to use as override message for success.

property successRedirect

successRedirect?: string | undefined;

• After successful login, redirect to given URL.

property successReturnToOrRedirect

successReturnToOrRedirect?: string | undefined;

property userProperty

userProperty?: string | undefined;

• Determines what property on req will be set to the authenticated user object. Default 'user'.

method authenticate

authenticate: {
    (
        strategy: string | string[] | Strategy,
        callback?: AuthenticateCallback | ((...args: any[]) => any)
    ): AuthenticateRet;
    (
        strategy: string | string[] | Strategy,
        options: AuthenticateOptions,
        callback?: AuthenticateCallback | ((...args: any[]) => any)
    ): AuthenticateRet;
};

• Authenticates requests.

  Applies the nameed strategy (or strategies) to the incoming request, in order to authenticate the request. If authentication is successful, the user will be logged in and populated at req.user and a session will be established by default. If authentication fails, an unauthorized response will be sent.

  Options: - session Save login state in session, defaults to true. - successRedirect After successful login, redirect to given URL. - successMessage True to store success message in req.session.messages, or a string to use as override message for success. - successFlash True to flash success messages or a string to use as a flash message for success (overrides any from the strategy itself). - failureRedirect After failed login, redirect to given URL. - failureMessage True to store failure message in req.session.messages, or a string to use as override message for failure. - failureFlash True to flash failure messages or a string to use as a flash message for failures (overrides any from the strategy itself). - assignProperty Assign the object provided by the verify callback to given property.

  An optional callback can be supplied to allow the application to override the default manner in which authentication attempts are handled. The callback has the following signature, where user will be set to the authenticated user on a successful authentication attempt, or false otherwise. An optional info argument will be passed, containing additional details provided by the strategy's verify callback - this could be information about a successful authentication or a challenge message for a failed authentication. An optional status argument will be passed when authentication fails - this could be a HTTP response code for a remote authentication failure or similar.

  app.get('/protected', function(req, res, next) { passport.authenticate('local', function(err, user, info, status) { if (err) { return next(err) } if (!user) { return res.redirect('/signin') } res.redirect('/account'); })(req, res, next); });

  Note that if a callback is supplied, it becomes the application's responsibility to log-in the user, establish a session, and otherwise perform the desired operations.

  Examples:

  passport.authenticate('local', { successRedirect: '/', failureRedirect: '/login' });

  passport.authenticate('basic', { session: false });

  passport.authenticate('twitter');

method authorize

authorize: {
    (
        strategy: string | string[],
        callback?: AuthenticateCallback | ((...args: any[]) => any)
    ): AuthorizeRet;
    (
        strategy: string | string[],
        options: AuthorizeOptions,
        callback?: AuthenticateCallback | ((...args: any[]) => any)
    ): AuthorizeRet;
};

• Create third-party service authorization middleware.

  Returns middleware that will authorize a connection to a third-party service.

  This middleware is identical to using middleware with the assignProperty option set to 'account'. This is useful when a user is already authenticated (for example, using a username and password) and they want to connect their account with a third-party service.

  In this scenario, the user's third-party account will be set at req.account, and the existing req.user and login session data will be be left unmodified. A route handler can then link the third-party account to the existing local account.

  All arguments to this function behave identically to those accepted by .

  Example 1

  app.get('/oauth/callback/twitter', passport.authorize('twitter'));

method deserializeUser

deserializeUser: {
    <TID>(
        fn: (
            id: TID,
            done: (err: any, user?: Express.User | false | null) => void
        ) => void
    ): void;
    <TID, TR extends IncomingMessage = express.Request>(
        fn: (
            req: TR,
            id: TID,
            done: (err: any, user?: false | Express.User) => void
        ) => void
    ): void;
    <
        User extends Express.User = Express.User,
        Request extends IncomingMessage = express.Request
    >(
        serializedUser: unknown,
        req: Request,
        done: (err: any, user?: false | User) => any
    ): void;
    <User extends Express.User = Express.User>(
        serializedUser: unknown,
        done: (err: any, user?: false | User) => any
    ): void;
};

• Registers a function used to deserialize user objects out of the session.

  Examples:

  passport.deserializeUser(function(id, done) { User.findById(id, function (err, user) { done(err, user); }); });

• Private implementation that traverses the chain of deserializers, attempting to deserialize a user.

• Private implementation that traverses the chain of deserializers, attempting to deserialize a user.

  For backwards compatibility.

method framework

framework: <X, Y, Z>(fw: Framework<X, Y, Z>) => Authenticator<X, Y, Z>;

• Adapt this Authenticator to work with a specific framework.

  By default, Passport works as -style middleware, which makes it compatible with . For any app built using Express, there is no need to call this function.

method initialize

initialize: (options?: InitializeOptions) => InitializeRet;

• Passport initialization.

  Intializes Passport for incoming requests, allowing authentication strategies to be applied.

  As of v0.6.x, it is typically no longer necessary to use this middleware. It exists for compatiblity with apps built using previous versions of Passport, in which this middleware was necessary.

  The primary exception to the above guidance is when using strategies that depend directly on passport@0.4.x or earlier. These earlier versions of Passport monkeypatch Node.js http.IncomingMessage in a way that expects certain Passport-specific properties to be available. This middleware provides a compatibility layer for this situation.

  Options: - userProperty Determines what property on req will be set to the authenticated user object. Default 'user'.

  - compat When true, enables a compatibility layer for packages that depend on passport@0.4.x or earlier. Default true.

  Examples:

  app.use(passport.initialize());

  If sessions are being utilized, applications must set up Passport with functions to serialize a user into and out of a session. For example, a common pattern is to serialize just the user ID into the session (due to the fact that it is desirable to store the minimum amount of data in a session). When a subsequent request arrives for the session, the full User object can be loaded from the database by ID.

  Note that additional middleware is required to persist login state, so we must use the connect.session() middleware _before_ passport.initialize().

  If sessions are being used, this middleware must be in use by the Connect/Express application for Passport to operate. If the application is entirely stateless (not using sessions), this middleware is not necessary, but its use will not have any adverse impact.

  Examples:

  app.use(connect.cookieParser()); app.use(connect.session({ secret: 'keyboard cat' })); app.use(passport.initialize()); app.use(passport.session());

  passport.serializeUser(function(user, done) { done(null, user.id); });

  passport.deserializeUser(function(id, done) { User.findById(id, function (err, user) { done(err, user); }); });

method serializeUser

serializeUser: {
    <TID>(
        fn: (user: Express.User, done: (err: any, id?: TID) => void) => void
    ): void;
    <TID, TR extends IncomingMessage = express.Request>(
        fn: (
            req: TR,
            user: Express.User,
            done: (err: any, id?: TID) => void
        ) => void
    ): void;
    <
        User extends Express.User = Express.User,
        Request extends IncomingMessage = express.Request
    >(
        user: User,
        req: Request,
        done: (err: any, serializedUser?: unknown) => any
    ): void;
    <User extends Express.User = Express.User>(
        user: User,
        done: (err: any, serializedUser?: unknown) => any
    ): void;
};

• Registers a function used to serialize user objects into the session.

  Examples:

  passport.serializeUser(function(user, done) { done(null, user.id); });

• Private implementation that traverses the chain of serializers, attempting to serialize a user.

• Private implementation that traverses the chain of serializers, attempting to serialize a user.

  For backwards compatibility.

method session

session: (options?: SessionOptions) => AuthenticateRet;

• Middleware that will restore login state from a session.

  Web applications typically use sessions to maintain login state between requests. For example, a user will authenticate by entering credentials into a form which is submitted to the server. If the credentials are valid, a login session is established by setting a cookie containing a session identifier in the user's web browser. The web browser will send this cookie in subsequent requests to the server, allowing a session to be maintained.

  If sessions are being utilized, and a login session has been established, this middleware will populate req.user with the current user.

  Note that sessions are not strictly required for Passport to operate. However, as a general rule, most web applications will make use of sessions. An exception to this rule would be an API server, which expects each HTTP request to provide credentials in an Authorization header.

  Examples:

  app.use(connect.cookieParser()); app.use(connect.session({ secret: 'keyboard cat' })); app.use(passport.initialize()); app.use(passport.session());

  Options: - pauseStream Pause the request stream before deserializing the user object from the session. Defaults to false. Should be set to true in cases where middleware consuming the request body is configured after passport and the deserializeUser method is asynchronous.

method transformAuthInfo

transformAuthInfo: {
    (fn: (info: any, done: (err: any, info: any) => void) => void): void;
    <InitialInfo = unknown, Request extends IncomingMessage = express.Request>(
        info: unknown,
        req: Request,
        done: (err: any, transformedAuthInfo?: unknown) => any
    ): void;
    <InitialInfo = unknown>(
        info: unknown,
        done: (err: any, transformedAuthInfo?: unknown) => any
    ): void;
};

• Registers a function used to transform auth info.

  In some circumstances authorization details are contained in authentication credentials or loaded as part of verification.

  For example, when using bearer tokens for API authentication, the tokens may encode (either directly or indirectly in a database), details such as scope of access or the client to which the token was issued.

  Such authorization details should be enforced separately from authentication. Because Passport deals only with the latter, this is the responsiblity of middleware or routes further along the chain. However, it is not optimal to decode the same data or execute the same database query later. To avoid this, Passport accepts optional info along with the authenticated user in a strategy's success() action. This info is set at req.authInfo, where said later middlware or routes can access it.

  Optionally, applications can register transforms to proccess this info, which take effect prior to req.authInfo being set. This is useful, for example, when the info contains a client ID. The transform can load the client from the database and include the instance in the transformed info, allowing the full set of client properties to be convieniently accessed.

  If no transforms are registered, info supplied by the strategy will be left unmodified.

  Examples:

  passport.transformAuthInfo(function(info, done) { Client.findById(info.clientID, function (err, client) { info.client = client; done(err, info); }); });

• Private implementation that traverses the chain of transformers, attempting to transform auth info.

  If no transformers are registered (or they all pass), the default behavior is to use the un-transformed info as-is.

• Private implementation that traverses the chain of transformers, attempting to transform auth info.

  If no transformers are registered (or they all pass), the default behavior is to use the un-transformed info as-is.

  For backwards compatibility.

method unuse

unuse: (name: string) => this;

• Deregister a strategy that was previously registered with the given name.

  In a typical application, the necessary authentication strategies are registered when initializing the app and, once registered, are always available. As such, it is typically not necessary to call this function.

  Example 1

  passport.unuse('acme');

method use

use: { (strategy: Strategy): this; (name: string, strategy: Strategy): this };

• Register a strategy for later use when authenticating requests. The name with which the strategy is registered is passed to .

  Example 1

  Register strategy. passport.use(new GoogleStrategy(...));

  Example 2

  Register strategy and override name. passport.use('password', new LocalStrategy(function(username, password, cb) { // ... }));

method authenticate

authenticate: (
    passport: Authenticator<InitializeRet, AuthenticateRet, AuthorizeRet>,
    name: string,
    options?: any,
    callback?: (...args: any[]) => any
) => (...args: any[]) => AuthenticateRet;

• Authenticates requests.

  Applies the nameed strategy (or strategies) to the incoming request, in order to authenticate the request. If authentication is successful, the user will be logged in and populated at req.user and a session will be established by default. If authentication fails, an unauthorized response will be sent.

  Options: - session Save login state in session, defaults to true. - successRedirect After successful login, redirect to given URL. - successMessage True to store success message in req.session.messages, or a string to use as override message for success. - successFlash True to flash success messages or a string to use as a flash message for success (overrides any from the strategy itself). - failureRedirect After failed login, redirect to given URL. - failureMessage True to store failure message in req.session.messages, or a string to use as override message for failure. - failureFlash True to flash failure messages or a string to use as a flash message for failures (overrides any from the strategy itself). - assignProperty Assign the object provided by the verify callback to given property.

  An optional callback can be supplied to allow the application to override the default manner in which authentication attempts are handled. The callback has the following signature, where user will be set to the authenticated user on a successful authentication attempt, or false otherwise. An optional info argument will be passed, containing additional details provided by the strategy's verify callback - this could be information about a successful authentication or a challenge message for a failed authentication. An optional status argument will be passed when authentication fails - this could be a HTTP response code for a remote authentication failure or similar.

  app.get('/protected', function(req, res, next) { passport.authenticate('local', function(err, user, info, status) { if (err) { return next(err) } if (!user) { return res.redirect('/signin') } res.redirect('/account'); })(req, res, next); });

  Note that if a callback is supplied, it becomes the application's responsibility to log-in the user, establish a session, and otherwise perform the desired operations.

  Examples:

  passport.authenticate('local', { successRedirect: '/', failureRedirect: '/login' });

  passport.authenticate('basic', { session: false });

  passport.authenticate('twitter');

method authorize

authorize: (
    passport: Authenticator<InitializeRet, AuthenticateRet, AuthorizeRet>,
    name: string,
    options?: any,
    callback?: (...args: any[]) => any
) => (...args: any[]) => AuthorizeRet;

• Create third-party service authorization middleware.

  Returns middleware that will authorize a connection to a third-party service.

  This middleware is identical to using middleware with the assignProperty option set to 'account'. This is useful when a user is already authenticated (for example, using a username and password) and they want to connect their account with a third-party service.

  In this scenario, the user's third-party account will be set at req.account, and the existing req.user and login session data will be be left unmodified. A route handler can then link the third-party account to the existing local account.

  All arguments to this function behave identically to those accepted by .

  Example 1

  app.get('/oauth/callback/twitter', passport.authorize('twitter'));

method initialize

initialize: (
    passport: Authenticator<InitializeRet, AuthenticateRet, AuthorizeRet>,
    options?: any
) => (...args: any[]) => InitializeRet;

• Passport initialization.

  Intializes Passport for incoming requests, allowing authentication strategies to be applied.

  If sessions are being utilized, applications must set up Passport with functions to serialize a user into and out of a session. For example, a common pattern is to serialize just the user ID into the session (due to the fact that it is desirable to store the minimum amount of data in a session). When a subsequent request arrives for the session, the full User object can be loaded from the database by ID.

  Note that additional middleware is required to persist login state, so we must use the connect.session() middleware _before_ passport.initialize().

  If sessions are being used, this middleware must be in use by the Connect/Express application for Passport to operate. If the application is entirely stateless (not using sessions), this middleware is not necessary, but its use will not have any adverse impact.

  Examples:

  app.use(connect.cookieParser()); app.use(connect.session({ secret: 'keyboard cat' })); app.use(passport.initialize()); app.use(passport.session());

  passport.serializeUser(function(user, done) { done(null, user.id); });

  passport.deserializeUser(function(id, done) { User.findById(id, function (err, user) { done(err, user); }); });

property compat

compat?: boolean;

• When true, enables a compatibility layer for packages that depend on passport@0.4.x or earlier. Default true.

property userProperty

userProperty?: string;

• Determines what property on req will be set to the authenticated user object. Default 'user'.

property session

session: boolean;

• Save login state in session, defaults to true.

property keepSessionInfo

keepSessionInfo?: boolean;

property Authenticator

Authenticator: { new (): Authenticator };

• Create a new Authenticator object.

property Passport

Passport: PassportStatic['Authenticator'];

• Create a new Authenticator object.

property strategies

strategies: {
    /**
     *  Create a new `SessionStrategy` object.
     *
     * An instance of this strategy is automatically used when creating an
     * {@link Authenticator `Authenticator`}.  As such, it is typically unnecessary to create an
     * instance using this constructor.
     *
     * This `Strategy` authenticates HTTP requests based on the contents
     * of session data.
     *
     * The login session must have been previously initiated, typically upon the
     * user interactively logging in using a HTML form.  During session initiation,
     * the logged-in user's information is persisted to the session so that it can
     * be restored on subsequent requests.
     *
     * Note that this strategy merely restores the authentication state from the
     * session, it does not authenticate the session itself.  Authenticating the
     * underlying session is assumed to have been done by the middleware
     * implementing session support.  This is typically accomplished by setting a
     * signed cookie, and verifying the signature of that cookie on incoming
     * requests.
     *
     * In {@link https://expressjs.com/ Express}-based apps, session support is
     * commonly provided by {@link https://github.com/expressjs/session `express-session`}
     * or {@link https://github.com/expressjs/cookie-session `cookie-session`}.
     *
     * Options:
     *
     *  - `key` Determines what property ("key") on
     *          the session data where login session data is located.  The login
     *          session is stored and read from `req.session[key]`.
     *          Default `'passport'`.
     */
    SessionStrategy: {
        new (deserializeUser: DeserializeUserFunction): SessionStrategy;
        new (
            options: SessionStrategyOptions,
            deserializeUser: DeserializeUserFunction
        ): SessionStrategy;
    };
};

property Strategy

Strategy: { new (): Strategy & StrategyCreatedStatic };

• Creates an instance of Strategy.

property displayName

displayName: string;

property emails

emails?:
    | Array<{
          value: string;
          type?: string | undefined;
      }>
    | undefined;

property id

id: string;

property name

name?:
    | {
          familyName: string;
          givenName: string;
          middleName?: string | undefined;
      }
    | undefined;

property photos

photos?:
    | Array<{
          value: string;
      }>
    | undefined;

property provider

provider: string;

property username

username?: string | undefined;

property pauseStream

pauseStream: boolean;

• Pause the request stream before deserializing the user object from the session. Defaults to false. Should be set to true in cases where middleware consuming the request body is configured after passport and the deserializeUser method is asynchronous.

property name

readonly name: 'session';

• The name of the strategy, set to 'session'.

method authenticate

authenticate: (
    req: IncomingMessage,
    options?: Pick<AuthenticateOptions, 'pauseStream'>
) => void;

• Authenticate request based on current session data.

  When login session data is present in the session, that data will be used to restore login state across across requests by calling the deserialize user function.

  If login session data is not present, the request will be passed to the next middleware, rather than failing authentication - which is the behavior of most other strategies. This deviation allows session authentication to be performed at the application-level, rather than the individual route level, while allowing both authenticated and unauthenticated requests and rendering responses accordingly. Routes that require authentication will need to guard that condition.

  This function is **protected**, and should _not_ be called directly. Instead, use passport.authenticate() middleware and specify the of this strategy and any options.

  Options: - pauseStream When true, data events on the request will be paused, and then resumed after the asynchronous deserializeUser function has completed. This is only necessary in cases where later middleware in the stack are listening for events, and ensures that those events are not missed. Default false.

  Example 1

  passport.authenticate('session');

property key

key: string;

• Determines what property ("key") on the session data where login session data is located. The login session is stored and read from req.session[key]. Default 'passport'.

property name

name?: string | undefined;

method authenticate

authenticate: (
    this: StrategyCreated<this>,
    req: express.Request,
    options?: any
) => any;

• Authenticate request.

  This function must be overridden by subclasses. In abstract form, it always throws an exception.

method error

error: (err: any) => void;

• Internal error while performing authentication.

  Strategies should call this function when an internal error occurs during the process of performing authentication; for example, if the user directory is not available.

method fail

fail: (challenge?: StrategyFailure | string | number, status?: number) => void;

• Fail authentication, with optional challenge and status, defaulting to 401.

  Strategies should call this function to fail an authentication attempt.

method pass

pass: () => void;

• Pass without making a success or fail decision.

  Under most circumstances, Strategies should not need to call this function. It exists primarily to allow previous authentication state to be restored, for example from an HTTP session.

method redirect

redirect: (url: string, status?: number) => void;

• Redirect to url with optional status, defaulting to 302.

  Strategies should call this function to redirect the user (via their user agent) to a third-party website for authentication.

method success

success: (user: Express.User, info?: object) => void;

• Authenticate user, with optional info.

  Strategies should call this function to successfully authenticate a user. user should be an object supplied by the application after it has been given an opportunity to verify credentials. info is an optional argument containing additional user information. This is useful for third-party authentication strategies to pass profile details.

property message

message?: string;

index signature

[key: string]: any;