ExternalAuthenticationService | Vendure Docs

ExternalAuthenticationService

This is a helper service which exposes methods related to looking up and creating Users based on an external AuthenticationStrategy.

Signature

class ExternalAuthenticationService {    constructor(connection: TransactionalConnection, roleService: RoleService, historyService: HistoryService, customerService: CustomerService, administratorService: AdministratorService, channelService: ChannelService)    findCustomerUser(ctx: RequestContext, strategy: string, externalIdentifier: string, checkCurrentChannelOnly:  = true) => Promise<User | undefined>;    findAdministratorUser(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>;    createCustomerAndUser(ctx: RequestContext, config: {            strategy: string;            externalIdentifier: string;            emailAddress: string;            firstName: string;            lastName: string;            verified?: boolean;        }) => Promise<User>;    createAdministratorAndUser(ctx: RequestContext, config: {            strategy: string;            externalIdentifier: string;            identifier: string;            emailAddress?: string;            firstName?: string;            lastName?: string;            roles: Role[];            /** An optional provider profile image to use as the Administrator avatar. */            avatar?: Promise<StoredMediaUpload> | StoredMediaUpload;        }) => ;    setAdministratorAvatar(ctx: RequestContext, userId: ID, avatar: Promise<StoredMediaUpload> | StoredMediaUpload | null) => Promise<Administrator>;    findUser(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>;    createUser(ctx: RequestContext, config: {            strategy: string;            externalIdentifier: string;        }) => Promise<User>;}

Was this chapter helpful?

Report Issue

Edited Jul 23, 2026·View source

findCustomerUser

method

(ctx: RequestContext, strategy: string, externalIdentifier: string, checkCurrentChannelOnly:  = true) => Promise<User | undefined>

Looks up a User based on their identifier from an external authentication provider, ensuring this User is associated with a Customer account.

By default, only customers in the currently-active Channel will be checked. By passing false as the checkCurrentChannelOnly argument, all channels will be checked.

findAdministratorUser

method(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>

Looks up a User based on their identifier from an external authentication provider, ensuring this User is associated with an Administrator account.

createCustomerAndUser

method

(ctx: RequestContext, config: {             strategy: string;             externalIdentifier: string;             emailAddress: string;             firstName: string;             lastName: string;             verified?: boolean;         }) => Promise<User>

If a customer has been successfully authenticated by an external authentication provider, yet cannot be found using findCustomerUser, then we need to create a new User and Customer record in Vendure for that user. This method encapsulates that logic as well as additional housekeeping such as adding a record to the Customer's history.

If a User account already exists with the same email address, the external authentication method will only be linked to that existing account when config.verified is true. An AuthenticationStrategy MUST therefore only set verified: true when the external provider has verified that the authenticating user owns the email address. Attempting to link an unverified external identity to an existing account will throw an UnverifiedExternalEmailError.

createAdministratorAndUser

method

(ctx: RequestContext, config: {             strategy: string;             externalIdentifier: string;             identifier: string;             emailAddress?: string;             firstName?: string;             lastName?: string;             roles: Role[];             /** An optional provider profile image to use as the Administrator avatar. */             avatar?: Promise<StoredMediaUpload> | StoredMediaUpload;         }) =>

If an administrator has been successfully authenticated by an external authentication provider, yet cannot be found using findAdministratorUser, then we need to create a new User and Administrator record in Vendure for that user.

setAdministratorAvatar

method

(ctx: RequestContext, userId: ID, avatar: Promise<StoredMediaUpload> | StoredMediaUpload | null) => Promise<Administrator>

Sets or removes the avatar belonging to an externally-authenticated Administrator. This allows an authentication strategy to synchronize a provider profile image without needing to look up the Administrator or manage the underlying system Asset.

Example

import { Readable } from 'stream';const response = await fetch(googleProfile.picture);const image = Buffer.from(await response.arrayBuffer());await externalAuthenticationService.setAdministratorAvatar(ctx, user.id, {    filename: `${googleProfile.sub}.jpg`,    mimetype: response.headers.get('content-type') ?? 'image/jpeg',    createReadStream: () => Readable.from([image]),});

findUser

method(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>

createUser

method

(ctx: RequestContext, config: {             strategy: string;             externalIdentifier: string;         }) => Promise<User>

Looks up a User based on their identifier from an external authentication provider. Creates the user if does not exist. Unlike findCustomerUser and findAdministratorUser, this method does not enforce that the User is associated with a Customer or Administrator account.