Interface StitchAuth
-
- All Superinterfaces:
AutoCloseable
,Closeable
- All Known Implementing Classes:
StitchAuthImpl
public interface StitchAuth extends Closeable
StitchAuth manages authentication for any Stitch based client.You can access the StitchAuth instance of the
StitchAppClient
withStitchAppClient.getAuth()
.This class handles login with various authentication providers using
StitchCredential
s withloginWithCredential(com.mongodb.stitch.core.auth.StitchCredential)
.Once logged in, you can retrieve the active
StitchUser
withgetUser()
, switch the active user withswitchToUserWithId(java.lang.String)
,logout()
, and remove users withremoveUserWithId(java.lang.String)
.Working with Multiple User Accounts
The Stitch Client SDKs allow multiple users to log in at the same time. When multiple users are logged in to an app, one of them is the active user for Stitch requests. You can switch the active user to be any other logged in user at any time. This allows users to quickly switch between logged in accounts on a device.
When a user is logged out, they remain on the device and are returned in the
listUsers()
list. To log in again, anotherloginWithCredential(com.mongodb.stitch.core.auth.StitchCredential)
call needs to be made. To remove a user from the device, useremoveUserWithId(java.lang.String)
.The following diagram explains the state of user accounts in your app when different events occur:
- See Also:
StitchAppClient
,StitchUser
,StitchCredential
-
-
Method Summary
Modifier and Type Method Description void
addAuthListener(StitchAuthListener listener)
Adds a listener for any important auth event.<ClientT> ClientT
getProviderClient(AuthProviderClientFactory<ClientT> factory)
Gets a client for the given authentication provider.<T> T
getProviderClient(NamedAuthProviderClientFactory<T> factory, String providerName)
Gets a client for the given named authentication provider.StitchUser
getUser()
Returns the active user or null if no user is active.boolean
isLoggedIn()
Returns whether there's an active user.List<StitchUser>
listUsers()
Returns a list of all logged in users.Task<StitchUser>
loginWithCredential(StitchCredential credential)
Logs in as a user with the given credentials associated with an authentication provider.Task<Void>
logout()
Logs out the active user.Task<Void>
logoutUserWithId(String userId)
Logs out the user with the provided id.Task<Void>
refreshCustomData()
You can store arbitrary data about your application users in a MongoDB collection and configure Stitch to automatically expose each user’s data in a field of their user object.void
removeAuthListener(StitchAuthListener listener)
Removes a listener.Task<Void>
removeUser()
Logs out and removes the active user.Task<Void>
removeUserWithId(String userId)
Logs out and removes the user with the provided id.StitchUser
switchToUserWithId(String userId)
Switches the active user to the user with the provided id.
-
-
-
Method Detail
-
getProviderClient
<ClientT> ClientT getProviderClient(AuthProviderClientFactory<ClientT> factory)
Gets a client for the given authentication provider. Most authentication providers will allow creation of a client without a name of the provider.- Type Parameters:
ClientT
- The type of client to be returned by the factory.- Parameters:
factory
- The factory that will create a client for the authentication provider.- Returns:
- A client to interact with the authentication provider.
-
getProviderClient
<T> T getProviderClient(NamedAuthProviderClientFactory<T> factory, String providerName)
Gets a client for the given named authentication provider.- Type Parameters:
T
- the type of client to be returned by the factory.- Parameters:
factory
- the factory that will create a client for the authentication provider.providerName
- the name of the authentication provider.- Returns:
- a client to interact with the authentication provider.
-
loginWithCredential
Task<StitchUser> loginWithCredential(StitchCredential credential)
Logs in as a user with the given credentials associated with an authentication provider.The user who logs in becomes the active user. Other Stitch functionality acts on behalf of the active user. If there was already an active user, that user becomes inactive but still logged in.
- Example:
public void loginAnonymously() { StitchAppClient client = Stitch.getDefaultAppClient(); StitchAuth auth = client.getAuth(); // The Stitch app is configured for Anonymous login in the Stitch UI auth.loginWithCredential(new AnonymousCredential()).addOnCompleteListener(new OnCompleteListener<StitchUser>() { @Override public void onComplete(@NonNull Task<StitchUser> task) { if (task.isSuccessful()) { Log.i(TAG, "Anonymous login successful!"); } else { Log.e(TAG, "Anonymous login failed!", task.getException()); } } }); }
- Parameters:
credential
- the credentials of the user to log in.- Returns:
- a
Task
containing user associated with the credentials if log in is successful. - See Also:
logout()
,logoutUserWithId(java.lang.String)
,switchToUserWithId(java.lang.String)
,removeUserWithId(java.lang.String)
-
logout
Task<Void> logout()
Logs out the active user.To log out an inactive user, use
logoutUserWithId(java.lang.String)
.Except for anonymous users, logged out users remain on the device and will be listed in the result of
listUsers()
. To log in again,loginWithCredential(com.mongodb.stitch.core.auth.StitchCredential)
must be used. To log out and remove the active user, useremoveUser()
.Anonymous users are deleted immediately after logging out.
- Example:
StitchAppClient client = Stitch.getDefaultAppClient(); StitchAuth auth = client.getAuth(); auth.logout().addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { if (task.isSuccessful()) { Log.i(TAG, "Successfully logged out!"); } else { Log.e(TAG, "Logout failed!", task.getException()); } } });
- Returns:
- a
Task
completing when logged out.
-
logoutUserWithId
Task<Void> logoutUserWithId(String userId)
Logs out the user with the provided id. Throws an exception if the user was not found.Except for anonymous users, logged out users remain on the device and will be listed in the result of
listUsers()
. To log in again,loginWithCredential(com.mongodb.stitch.core.auth.StitchCredential)
must be used. To remove a user from the list, useremoveUserWithId(java.lang.String)
.Anonymous users are deleted immediately after logging out.
- Parameters:
userId
- the id of the user to log out.- Returns:
- a
Task
completing when logged out.
-
removeUser
Task<Void> removeUser()
Logs out and removes the active user.To remove an inactive user, see
removeUserWithId(java.lang.String)
.Removing a user means removing it from this device, i.e. removing it from the list of users returned by
listUsers()
.- Returns:
- a
Task
completing when logged out.
-
removeUserWithId
Task<Void> removeUserWithId(String userId)
Logs out and removes the user with the provided id. Throws an exception if the user was not found.- Parameters:
userId
- the id of the user to remove.- Returns:
- a
Task
completing when logged out.
-
isLoggedIn
boolean isLoggedIn()
Returns whether there's an active user.Note: even if there are other users who are logged in, this will return false if there is no active user. A user becomes the active user upon
loginWithCredential(com.mongodb.stitch.core.auth.StitchCredential)
. SeelistUsers()
.- Returns:
- whether there's a currently active user.
-
getUser
@Nullable StitchUser getUser()
Returns the active user or null if no user is active.Whenever a user logs in, they become the active user. If there was already another user who was active, that user becomes inactive but still logged in. User-based Stitch functionality, such as reading from a database, is performed as the active user.
- Returns:
- the currently logged in, active user or null if no user is active.
-
addAuthListener
void addAuthListener(StitchAuthListener listener)
Adds a listener for any important auth event.- Parameters:
listener
- the listener to add.- See Also:
StitchAuthListener
-
removeAuthListener
void removeAuthListener(StitchAuthListener listener)
Removes a listener.- Parameters:
listener
- the listener to remove.
-
listUsers
List<StitchUser> listUsers()
Returns a list of all logged in users.- Returns:
- the list of currently logged in users
-
switchToUserWithId
StitchUser switchToUserWithId(String userId) throws IllegalArgumentException
Switches the active user to the user with the provided id. Throws an exception if the user was not found.- Parameters:
userId
- the id of the user to switch to- Returns:
- the user that was switched to
- Throws:
IllegalArgumentException
- throws if user id not found
-
refreshCustomData
Task<Void> refreshCustomData()
You can store arbitrary data about your application users in a MongoDB collection and configure Stitch to automatically expose each user’s data in a field of their user object. For example, you might store a user’s preferred language, date of birth, or their local timezone. If this functionality has not been configured, this is a no-op.
-
-