Class User

This class represents a user on the Realm Object Server. The credentials are provided by various 3rd party providers (Facebook, Google, etc.). A user can log in to the Realm Object Server, and if access is granted, it is possible to synchronize the local and the remote Realm. Moreover, synchronization is halted when the user is logged out. It is possible to persist a user. By retrieving a user, there is no need to log in to the 3rd party provider again. Persisting a user between sessions, the user's credentials are stored locally on the device, and should be treated as sensitive data.

Inheritance

Object

User

Namespace: Realms.Sync

Assembly: Realm.Sync.dll

Syntax

public class User : IEquatable<User>

Properties

AllLoggedIn

Gets all currently logged in users.

Declaration

public static User[] AllLoggedIn { get; }

Property Value

Type	Description
User[]	An array of valid logged in users.

Current

Gets the currently logged-in user. If none exists, null is returned. If more than one user is currently logged in, an exception is thrown.

Declaration

public static User Current { get; }

Property Value

Type	Description
User	Valid user or null to indicate nobody logged in.

Exceptions

Type	Condition
RealmException	Thrown if there are more than one users logged in.

Identity

Gets the identity of this user on the Realm Object Server. The identity is a guaranteed to be unique among all users on the Realm Object Server.

Declaration

public string Identity { get; }

Property Value

Type	Description
String	A string that uniquely identifies that user in Realm Object Server.

IsAdmin

Gets a value indicating whether this User is a Realm Object Server administrator user.

Declaration

public bool IsAdmin { get; }

Property Value

Type	Description
Boolean	true if the user is admin; otherwise, false.

RefreshToken

Gets this user's refresh token. This is the user's credential for accessing the Realm Object Server and should be treated as sensitive data.

Declaration

public string RefreshToken { get; }

Property Value

Type	Description
String	A unique string that can be used for refreshing the user's credentials.

ServerUri

Gets the server URI that was used for authentication.

Declaration

public Uri ServerUri { get; }

Property Value

Type	Description
Uri	The used to connect to the authentication service.

State

Gets the current state of the user.

Declaration

public UserState State { get; }

Property Value

Type	Description
UserState	A value indicating whether the user is active, logged out, or an error has occurred.

Methods

AcceptPermissionOfferAsync(String)

Consumes a token generated by OfferPermissionsAsync(String, AccessLevel, Nullable<DateTimeOffset>) to obtain permissions to a shared Realm.

Declaration

public Task<string> AcceptPermissionOfferAsync(string offerToken)

Parameters

Type	Name	Description
String	offerToken	The token, generated by OfferPermissionsAsync(String, AccessLevel, Nullable<DateTimeOffset>).

Returns

Type	Description
Task<String>	The relative url of the Realm that the token has granted permissions to.

ApplyPermissionsAsync(PermissionCondition, String, AccessLevel)

Changes the permissions of a Realm.

Declaration

public Task ApplyPermissionsAsync(PermissionCondition condition, string realmUrl, AccessLevel accessLevel)

Parameters

Type	Name	Description
PermissionCondition	condition	A PermissionCondition that will be used to match existing users against.
String	realmUrl	The Realm URL whose permissions settings should be changed. Use * to change the permissions of all Realms managed by this User.
AccessLevel	accessLevel	The access level to grant matching users. Note that the access level setting is absolute, i.e. it may revoke permissions for users that previously had a higher access level. To revoke all permissions, use None

Returns

Type	Description
Task	An awaitable task, that, upon completion, indicates that the permissions have been successfully applied by the server.

ChangePasswordAsync(String)

Changes the user's password.

Declaration

public Task ChangePasswordAsync(string newPassword)

Parameters

Type	Name	Description
String	newPassword	The user's new password.

Returns

Type	Description
Task	An awaitable task that, when successful, indicates that the password has changed.

Remarks

Changing a user's password using an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

ChangePasswordAsync(String, String)

Changes another user's password.

Declaration

public Task ChangePasswordAsync(string userId, string newPassword)

Parameters

Type	Name	Description
String	userId	The Identity of the user we want to change the password for.
String	newPassword	The user's new password.

Returns

Type	Description
Task	An awaitable task that, when successful, indicates that the password has changed.

Remarks

This user needs admin privilege in order to change someone else's password.
Changing a user's password using an authentication server that doesn't use HTTPS is a major security flaw, and should only be done while testing.

CompletePasswordResetAsync(Uri, String, String)

Complete the password reset flow by using the reset token sent to the user's email as a one-time authorization token to change the password.

Declaration

public static Task CompletePasswordResetAsync(Uri serverUri, string token, string newPassword)

Parameters

Type	Name	Description
Uri	serverUri	The URI of the server that the user is authenticated against.
String	token	The token that was sent to the user's email address.
String	newPassword	The user's new password.

Returns

Type	Description
Task	An awaitable task that, when successful, indicates that the password has changed.

Remarks

By default, the link that will be sent to the user's email will redirect to a webpage where they can enter their new password. If you wish to provide a native UX, you may wish to modify the url to use deep linking to open the app, extract the token, and navigate to a view that allows them to change their password within the app.

ConfigurePersistence(UserPersistenceMode, Byte[], Boolean)

Configures user persistence. If you need to call this, be sure to do so before accessing any other Realm API.

Declaration

public static void ConfigurePersistence(UserPersistenceMode mode, byte[] encryptionKey = null, bool resetOnError = false)

Parameters

Type	Name	Description
UserPersistenceMode	mode	The persistence mode.
Byte[]	encryptionKey	The key to encrypt the persistent user store with.
Boolean	resetOnError	If set to true reset the persistent user store on error.

Remarks

Users are persisted in a realm file within the application's sandbox.

By default User objects are persisted and are additionally protected with an encryption key stored in the iOS Keychain when running on an iOS device (but not on a Simulator). On Android users are persisted in plaintext, because the AndroidKeyStore API is only supported on API level 18 and up. You might want to provide your own encryption key on Android or disable persistence for security reasons.

ConfirmEmailAsync(Uri, String)

Complete the password reset flow by using the confirmation token sent to the user's email as a one-time authorization token to confirm their email.

Declaration

public static Task ConfirmEmailAsync(Uri serverUri, string token)

Parameters

Type	Name	Description
Uri	serverUri	The URI of the server that the user is authenticated against.
String	token	The token that was sent to the user's email address.

Returns

Type	Description
Task	An awaitable task that, when successful, indicates that the email has been confirmed.

Remarks

By default, the link that will be sent to the user's email will redirect to a webpage where they'll see a generic "Thank you for confirming" text. If you wish to provide a native UX, you may wish to modify the url to use deep linking to open the app, extract the token, and inform them that their email has been confirmed.

Equals(User)

Declaration

public bool Equals(User other)

Parameters

Type	Name	Description
User	other

Returns

Type	Description
Boolean

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

GetGrantedPermissionsAsync(Recipient, Int32)

Asynchronously retrieve all permissions associated with the user calling this method.

Declaration

public Task<IQueryable<PathPermission>> GetGrantedPermissionsAsync(Recipient recipient = Recipient.Any, int millisecondTimeout = 2000)

Parameters

Type	Name	Description
Recipient	recipient	The optional recipient of the permission.
Int32	millisecondTimeout	The timeout in milliseconds for downloading server changes. If the download times out, no error will be thrown and instead the latest local state will be returned. If set to 0, the latest state will be returned immediately.

Returns

Type	Description
Task<IQueryable<PathPermission>>	A queryable collection of PathPermission objects that provide detailed information regarding the granted access.

Remarks

The collection is a live query, similar to what you would get by calling All(String), so the same features and limitations apply - you can query and subscribe for notifications, but you cannot pass it between threads.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

GetLoggedInUser(String, Uri)

Gets a logged in user with a specified identity.

Declaration

public static User GetLoggedInUser(string identity, Uri serverUri)

Parameters

Type	Name	Description
String	identity	The identity of the user.
Uri	serverUri	The URI of the server that the user is authenticated against.

Returns

Type	Description
User	A user instance if a logged in user with that id exists, null otherwise.

GetPermissionChanges(ManagementObjectStatus[])

Gets the permission changes that this user has created by invoking ApplyPermissionsAsync(PermissionCondition, String, AccessLevel).

Declaration

public IQueryable<PermissionChange> GetPermissionChanges(params ManagementObjectStatus[] statuses)

Parameters

Type	Name	Description
ManagementObjectStatus[]	statuses	Optional statuses to filter by. If empty, will return objects with any status.

Returns

Type	Description
IQueryable<PermissionChange>	A queryable collection of PermissionChange objects.

GetPermissionOfferResponses(ManagementObjectStatus[])

Gets the permission offer responses that this user has created by invoking AcceptPermissionOfferAsync(String).

Declaration

public IQueryable<PermissionOfferResponse> GetPermissionOfferResponses(params ManagementObjectStatus[] statuses)

Parameters

Type	Name	Description
ManagementObjectStatus[]	statuses	Optional statuses to filter by. If empty, will return objects with any status.

Returns

Type	Description
IQueryable<PermissionOfferResponse>	A queryable collection of PermissionOfferResponse objects.

GetPermissionOffers(ManagementObjectStatus[])

Gets the permission offers that this user has created by invoking OfferPermissionsAsync(String, AccessLevel, Nullable<DateTimeOffset>).

Declaration

public IQueryable<PermissionOffer> GetPermissionOffers(params ManagementObjectStatus[] statuses)

Parameters

Type	Name	Description
ManagementObjectStatus[]	statuses	Optional statuses to filter by. If empty, will return objects with any status.

Returns

Type	Description
IQueryable<PermissionOffer>	A queryable collection of PermissionOffer objects.

InvalidateOfferAsync(PermissionOffer)

Invalidates a permission offer.

Declaration

public Task InvalidateOfferAsync(PermissionOffer offer)

Parameters

Type	Name	Description
PermissionOffer	offer	The offer that should be invalidated.

Returns

Type	Description
Task	An awaitable task, that, upon completion, indicates that the offer has been successfully invalidated by the server.

Remarks

Invalidating an offer prevents new users from consuming its token. It doesn't revoke any permissions that have already been granted.

LoginAsync(Credentials, Uri)

Logs the user in to the Realm Object Server.

Declaration

public static Task<User> LoginAsync(Credentials credentials, Uri serverUri)

Parameters

Type	Name	Description
Credentials	credentials	The credentials to use for authentication.
Uri	serverUri	The URI of the server that the user is authenticated against.

Returns

Type	Description
Task<User>	An awaitable Task, that, upon completion, contains the logged in user.

LogOut()

Logs out the user from the Realm Object Server. Once the Object Server has confirmed the logout the user credentials will be deleted from this device.

Declaration

public void LogOut()

LogOutAsync()

Logs out the user from the Realm Object Server. Once the Object Server has confirmed the logout the user credentials will be deleted from this device.

Declaration

public Task LogOutAsync()

Returns

Type	Description
Task	An awaitable Task, that, upon completion indicates that the user has been logged out both locally and on the server.

OfferPermissionsAsync(String, AccessLevel, Nullable<DateTimeOffset>)

Generates a token that can be used for sharing a Realm.

Declaration

public Task<string> OfferPermissionsAsync(string realmUrl, AccessLevel accessLevel, DateTimeOffset? expiresAt = null)

Parameters

Type	Name	Description
String	realmUrl	The Realm URL whose permissions settings should be changed. Use * to change the permissions of all Realms managed by this User.
AccessLevel	accessLevel	The access level to grant matching users. Note that the access level setting is absolute, i.e. it may revoke permissions for users that previously had a higher access level. To revoke all permissions, use None
Nullable<DateTimeOffset>	expiresAt	Optional expiration date of the offer. If set to null, the offer doesn't expire.

Returns

Type	Description
Task<String>	A token that can be shared with another user, e.g. via email or message and then consumed by AcceptPermissionOfferAsync(String) to obtain permissions to a Realm.

RequestEmailConfirmationAsync(Uri, String)

Request an email confirmation email to be sent to a user's email. This method requires internet connection and will not throw an exception, even if the email doesn't belong to a Realm Object Server user.

Declaration

public static Task RequestEmailConfirmationAsync(Uri serverUri, string email)

Parameters

Type	Name	Description
Uri	serverUri	The URI of the server that the user is authenticated against.
String	email	The email that corresponds to the user's username.

Returns

Type	Description
Task	An awaitable task that, upon completion, indicates that the request has been sent.

RequestPasswordResetAsync(Uri, String)

Request a password reset email to be sent to a user's email. This method requires internet connection and will not throw an exception, even if the email doesn't belong to a Realm Object Server user.

Declaration

public static Task RequestPasswordResetAsync(Uri serverUri, string email)

Parameters

Type	Name	Description
Uri	serverUri	The URI of the server that the user is authenticated against.
String	email	The email that corresponds to the user's username.

Returns

Type	Description
Task	An awaitable task that, upon completion, indicates that the request has been sent.

Remarks

This can only be used for users who authenticated with UsernamePassword(String, String, Boolean) and passed a valid email address as a username.

RetrieveInfoForUserAsync(String, String)

Looks up user's information by provider id. This is useful when you know the id of a user in a provider's system, e.g. on Facebook and want to find the associated Realm user's Id.

Declaration

public Task<UserInfo> RetrieveInfoForUserAsync(string provider, string providerUserIdentity)

Parameters

Type	Name	Description
String	provider	The provider that the user has signed up with.
String	providerUserIdentity	The id of the user in the provider's system.

Returns

Type	Description
Task<UserInfo>	A UserInfo, containing information about the User's Identity in Realm's authentication system, or null if a user has not been found.

Remarks

This user needs admin privilege in order to look up other users by provider id.
The exact names of built-in providers can be found in Credentials.Provider.

Extension Methods

UserPermissionsExtensions.GetManagementRealm(User)

UserPermissionsExtensions.GetPermissionRealm(User)