StitchAuth

StitchAuth represents and controls the login state of a StitchAppClient.

Login is required for most Stitch functionality. Depending on which Authentication Provider you are using, use loginWithCredential or loginWithRedirect to log in.

Once logged in, StitchAuth.user is a StitchUser object that can be examined for user profile and other information.

Login state can persist across browser sessions. Therefore, a StitchAppClient's StitchAuth instance may already contain login information upon initialization.

In the case of OAuth2 authentication providers, StitchAuth may also initialize with the result of a previous session's request to loginWithRedirect. The redirect result can be checked with hasRedirectResult and handled with handleRedirectResult.

To log out, use logout.

Examples

For an example of loginWithRedirect, see Facebook Authentication.

copy

// Previously:
// const stitchAppClient = Stitch.initializeDefaultAppClient('your-stitch-app-id')

// Log in with anonymous credential
stitchAppClient.auth
  .loginWithCredential(new AnonymousCredential())
  .then((user) => {
    console.log(`Logged in as anonymous user with id: ${user.id}`)
  })
  .catch(console.error)

Hierarchy

StitchAuth

Index

Properties

Methods

Properties

isLoggedIn

isLoggedIn: boolean

Whether or not there is a currently logged in active user of this StitchAuth

Optional user

user: StitchUser

A StitchUser object representing the currently logged in, active user, or undefined if there is no logged in active user.

Methods

addAuthListener

addAuthListener(listener: StitchAuthListener): any

Registers a StitchAuthListener with the client.

Example

copy

// In this example, a custom StitchAuthListener is defined and registered:
const stitchClient = Stitch.defaultAppClient

// Define the listener
const myAuthListener = {
  onUserAdded: (auth, addedUser) => {
    console.log('onUserAdded:', addedUser.profile)
  },
  onUserLoggedIn: (auth, loggedInUser) => {
    console.log('onUserLoggedIn:', loggedInUser.profile)
  },
  onActiveUserChanged: (auth, currentActiveUser, previousActiveUser) => {
    console.log('onActiveUserChanged:', currentActiveUser, previousActiveUser)
  },
  onUserLoggedOut: (auth, loggedOutUser) => {
    console.log('onUserLoggedOut:', loggedOutUser.profile)
  },
  onUserRemoved: (auth, removedUser) => {
    console.log('onUserRemoved:', removedUser.profile)
  },
  onUserLinked: (auth, linkedUser) => {
    console.log('onUserLinked:', linkedUser.profile)
  },
  onListenerRegistered: (auth) => {
    console.log('onListenerRegistered')
  },
}

// Register the listener
const {auth} = stitchClient
auth.addAuthListener(myAuthListener)

// Console:
//   onListenerRegistered

const user = await auth.loginWithCredential(new UserPasswordCredential('user', 'password'))

// Console:
//   onUserAdded
//   onUserLoggedIn
//   onActiveUserChanged

await auth.logout()

// Console:
//   onUserLoggedOut
//   onActiveUserChanged

await auth.removeUserWithId(user.id)

// Console:
//   onUserRemoved

Parameters

listener: StitchAuthListener

The listener to be triggered when an authentication event occurs on this auth object.

Returns any

handleRedirectResult

handleRedirectResult(): Promise<StitchUser>

- Defined in browser/core/src/core/auth/StitchAuth.ts:152
If hasRedirectResult is true, completes the OAuth2 login previously started by loginWithRedirect.

Returns Promise<StitchUser>

hasRedirectResult

hasRedirectResult(): boolean

- Defined in browser/core/src/core/auth/StitchAuth.ts:147
Checks whether or not an external login process previously started by loginWithRedirect has redirected the user to this page.

Stitch will have this information available right after initialization.

Call this method before calling handleRedirectResult if you want to avoid errors.

Returns boolean

listUsers

listUsers(): StitchUser[]

- Defined in browser/core/src/core/auth/StitchAuth.ts:79
Returns a list of all users who have logged into this application, except those that have been removed manually and anonymous users who have logged out.

Note

The list of users is a snapshot of the state when listUsers() is called. The [[StitchUsers]] in this list will not be updated if, e.g., a user's login state changes after this is called.

Example
copy
```
const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

// Log in as two different users.
await auth.loginWithCredential(new UserPasswordCredential('user1', 'password'))
await auth.loginWithCredential(new UserPasswordCredential('user2', 'password'))

// List users.
console.log(auth.listUsers())
```
See Also
- removeUser
- removeUserWithId
Returns StitchUser[]

loginWithCredential

loginWithCredential(credential: StitchCredential): Promise<StitchUser>

Logs in as a StitchUser using the provided StitchCredential.

Example

copy

// Previously:
// const stitchAppClient = Stitch.initializeDefaultAppClient('your-stitch-app-id')

// Log in with anonymous credential
stitchAppClient.auth
  .loginWithCredential(new AnonymousCredential())
  .then((user) => {
    console.log(`Logged in as anonymous user with id: ${user.id}`)
  })
  .catch(console.error)

// Log in with user/password credential
stitchAppClient.auth
  .loginWithCredential(new UserPasswordCredential('user', 'password'))
  .then((user) => {
    console.log(`Logged in as user with id: ${user.id}`)
  })
  .catch(console.error)

Parameters

credential: StitchCredential

The StitchCredential to use when logging in.

Returns Promise<StitchUser>

loginWithRedirect

loginWithRedirect(credential: StitchRedirectCredential): void

- Defined in browser/core/src/core/auth/StitchAuth.ts:137
Authenticates the client as a MongoDB Stitch user using the provided StitchRedirectCredential.

This method will redirect the user to an OAuth2 login page where the login is handled externally. That external page will redirect the user back to the page specified in the redirect credential. To complete the login, that page will need to handle the redirect by calling handleRedirectResult.

For usage examples, see Facebook Authentication and Google Authentication.

Parameters
- credential: StitchRedirectCredential
  
  The StitchRedirectCredential to use when logging in.
Returns void

logout

logout(): Promise<void>

Logs out the currently authenticated active user and clears any persisted authentication information for that user.

There will be no active user after this logout takes place, even if there are other logged in users. Another user must be explicitly switched to using switchToUserWithId, loginWithCredential or loginWithRedirect.

Example

copy

const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

const user1 = await auth.loginWithCredential(new UserPasswordCredential('user1', 'password'))
const user2 = await auth.loginWithCredential(new UserPasswordCredential('user2', 'password'))

// Active user is now user2
expect('Active user to be user2', auth.user.id === user2.id)

await auth.logout()

// The active user is now undefined. Stitch does not assume it should
// switch to another active account upon logout
expect('Active user to be undefined', auth.user === undefined)

// Explicitly switch to a desired active user
auth.switchToUserWithId(user1.id)

expect('Active user to be user1', auth.user.id === user1.id)

logoutUserWithId

logoutUserWithId(userId: string): Promise<void>

Logs out the user with the provided id.

The promise rejects with an exception if the user was not found.

Note

Because anonymous users are deleted after logout, this method is equivalent to removeUserWithId for anonymous users.

Example

copy

const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

// Log in with user/password credential. The Email/Password Provider
// was enabled in the Stitch UI Users Panel.
let user = await auth.loginWithCredential(new UserPasswordCredential('user', 'password'))

expect('User is logged in', user.isLoggedIn)

// Log out the user who just logged in.
await auth.logoutUserWithId(user.id)

// Update the user with the latest state
user = auth.listUsers().find(entry => entry.id === user.id)

expect('User is logged out', !user.isLoggedIn)

Parameters

userId: string

the id of the user to log out

Returns Promise<void>

refreshCustomData

refreshCustomData(): Promise<void>

- Defined in browser/core/src/core/auth/StitchAuth.ts:214
Refresh a user's custom data field.

Returns Promise<void>

removeAuthListener

removeAuthListener(listener: StitchAuthListener): any

- Defined in browser/core/src/core/auth/StitchAuth.ts:209
Unregisters a listener.

Parameters
- listener: StitchAuthListener
Returns any

removeUser

removeUser(): Promise<void>

Logs out the active user and removes that user from the list of all users associated with this application as returned by StitchAuth.listUsers.

Example

copy

const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

// Log in
const user = await auth.loginWithCredential(new UserPasswordCredential('user', 'password'))

expect('Users list now contains user',
  undefined !== auth.listUsers().find(entry => entry.id === user.id))

// Now remove active user
await auth.removeUser()

expect('User has been removed from list',
  undefined === auth.listUsers().find(entry => entry.id === user.id))

Returns Promise<void>

removeUserWithId

removeUserWithId(userId: string): Promise<void>

Removes the user with the provided id from the list of all users associated with this application as returned by StitchAuth.listUsers.

If the user was logged in, the user will be logged out before being removed.

The promise rejects with an exception if the user was not found.

Example

copy

const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

// Log in with two users
const user1 = await auth.loginWithCredential(new UserPasswordCredential('user1', 'password'))
const user2 = await auth.loginWithCredential(new UserPasswordCredential('user2', 'password'))

// List all logged in users
console.log(auth.listUsers())

// Now remove user1
await auth.removeUserWithId(user1.id)

// User has been removed from the list
console.log(auth.listUsers())

Parameters

userId: string

the id of the user to remove

Returns Promise<void>

switchToUserWithId

switchToUserWithId(userId: string): StitchUser

Switches the active user to the user with the specified id. The user must exist in the list of all users who have logged into this application, and the user must be currently logged in, otherwise this will throw a StitchClientError.

Example

copy

const stitchAppClient = Stitch.defaultAppClient

const {auth} = stitchAppClient

// Log in as user1
await auth.loginWithCredential(new UserPasswordCredential('user1', 'password'))

// Active user is now user1
const user1 = auth.user

// Log in as user2
await auth.loginWithCredential(new UserPasswordCredential('user2', 'password'))

// Active user is now user2
const user2 = auth.user

// See that auth.user has changed upon loginWithCredential()
expect('user1 is not user2', user1.id !== user2.id)

let activeUser = auth.user

// Verify that active user is user2
expect('active user is user2', activeUser.id === user2.id)

// Switch active user to to user1
activeUser = auth.switchToUserWithId(user1.id)

// Verify that active user is now user1
expect('active user is user1', activeUser.id === user1.id)

Parameters

userId: string

the id of the user to switch to

Throws

an exception if the user is not found, or the found user is not logged in

Returns StitchUser

Generated using TypeDoc

StitchAuth

Examples

See Also

Hierarchy

Index

Properties

Methods

Properties

isLoggedIn

Optional user

Methods

addAuthListener

Example

Parameters

listener: StitchAuthListener

Returns any

handleRedirectResult

Returns Promise<StitchUser>

hasRedirectResult

Returns boolean

listUsers

Note

Example

See Also

Returns StitchUser[]

loginWithCredential

Example

Parameters

credential: StitchCredential

Returns Promise<StitchUser>

loginWithRedirect

Parameters

credential: StitchRedirectCredential

Returns void

logout

Example

See Also

Returns Promise<void>

logoutUserWithId

Note

Example

Parameters

userId: string

Returns Promise<void>

refreshCustomData

Returns Promise<void>

removeAuthListener

Parameters

listener: StitchAuthListener

Returns any

removeUser

Example

Returns Promise<void>

removeUserWithId

Example

Parameters

userId: string

Returns Promise<void>

switchToUserWithId

Example

Parameters

userId: string

Throws

Returns StitchUser