RLMSyncUser

@interface RLMSyncUser : NSObject

A RLMSyncUser instance represents a single Realm Object Server user account.

A user may have one or more credentials associated with it. These credentials uniquely identify the user to the authentication provider, and are used to sign into a Realm Object Server user account.

Note that user objects are only vended out via SDK APIs, and cannot be directly initialized. User objects can be accessed from any thread.

  • A dictionary of all valid, logged-in user identities corresponding to their user objects.

    Declaration

    Objective-C

    + (nonnull NSDictionary<NSString *, RLMSyncUser *> *)allUsers;
    Show on GitHub

  • The logged-in user. nil if none exists.

    Warning

    Throws an exception if more than one logged-in user exists.

    Declaration

    Objective-C

    + (nullable RLMSyncUser *)currentUser;
    Show on GitHub

  • The unique Realm Object Server user ID string identifying this user.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSString *identity;
    Show on GitHub

  • The user’s refresh token used to access the Realm Object Server.

    This is required to make HTTP requests to Realm Object Server’s REST API for functionality not exposed natively. It should be treated as sensitive data.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSString *refreshToken;
    Show on GitHub

  • The URL of the authentication server this user will communicate with.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSURL *authenticationServer;
    Show on GitHub

  • Whether the user is a Realm Object Server administrator. Value reflects the state at the time of the last successful login of this user.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL isAdmin;
    Show on GitHub

  • The current state of the user.

    Declaration

    Objective-C

    @property (readonly, nonatomic) RLMSyncUserState state;
    Show on GitHub

Lifecycle

  • Create, log in, and asynchronously return a new user object, specifying a custom timeout for the network request and a custom queue to run the callback upon. Credentials identifying the user must be passed in. The user becomes available in the completion block, at which point it is ready for use.

    Declaration

    Objective-C

    + (void)logInWithCredentials:(nonnull RLMSyncCredentials *)credentials
               authServerURL:(nonnull NSURL *)authServerURL
                     timeout:(NSTimeInterval)timeout
               callbackQueue:(nonnull dispatch_queue_t)callbackQueue
                onCompletion:(nonnull RLMUserCompletionBlock)completion;
    Show on GitHub

  • Create, log in, and asynchronously return a new user object.

    If the login completes successfully, the completion block will invoked with a RLMSyncUser object representing the logged-in user. This object can be used to open synchronized Realms. If the login fails, the completion block will be invoked with an error.

    The completion block always runs on the main queue.

    Declaration

    Objective-C

    + (void)logInWithCredentials:(nonnull RLMSyncCredentials *)credentials
               authServerURL:(nonnull NSURL *)authServerURL
                onCompletion:(nonnull RLMUserCompletionBlock)completion;

    Parameters

    credentials

    A credentials value identifying the user to be logged in.
    authServerURL

    The URL of the authentication server (e.g. http://realm.example.org:9080).
    completion

    A callback block that returns a user object or an error, indicating the completion of the login operation.
    Show on GitHub

  • Returns the default configuration for the user. The default configuration points to the default query-based Realm on the server the user authenticated against.

    Declaration

    Objective-C

    - (nonnull RLMRealmConfiguration *)configuration;
    Show on GitHub

  • Create a query-based configuration instance for the given url.

    Declaration

    Objective-C

    - (nonnull RLMRealmConfiguration *)configurationWithURL:(nullable NSURL *)url;

    Parameters

    url

    The unresolved absolute URL to the Realm on the Realm Object Server, e.g. realm://example.org/~/path/to/realm. Unresolved means the path should contain the wildcard marker ~, which will automatically be filled in with the user identity by the Realm Object Server.

    Return Value

    A default configuration object with the sync configuration set to use the given URL.

    Show on GitHub

  • Create a configuration instance for the given url.

    Declaration

    Objective-C

    - (nonnull RLMRealmConfiguration *)configurationWithURL:(nullable NSURL *)url
                                    fullSynchronization:
                                        (_Bool)fullSynchronization;

    Parameters

    url

    The unresolved absolute URL to the Realm on the Realm Object Server, e.g. realm://example.org/~/path/to/realm. Unresolved means the path should contain the wildcard marker ~, which will automatically be filled in with the user identity by the Realm Object Server.
    fullSynchronization

    If YES, all objects in the server Realm are automatically synchronized, and the query subscription methods cannot be used.

    Return Value

    A default configuration object with the sync configuration set to use the given URL and options.

    Show on GitHub

  • Create a configuration instance for the given url.

    Declaration

    Objective-C

    - (nonnull RLMRealmConfiguration *)
    configurationWithURL:(nullable NSURL *)url
     fullSynchronization:(_Bool)fullSynchronization
     enableSSLValidation:(_Bool)enableSSLValidation
               urlPrefix:(nullable NSString *)urlPrefix;

    Parameters

    url

    The unresolved absolute URL to the Realm on the Realm Object Server, e.g. realm://example.org/~/path/to/realm. Unresolved means the path should contain the wildcard marker ~, which will automatically be filled in with the user identity by the Realm Object Server.
    fullSynchronization

    If YES, all objects in the server Realm are automatically synchronized, and the query subscription methods cannot be used.
    enableSSLValidation

    If NO, invalid SSL certificates for the server will not be rejected. THIS SHOULD NEVER BE USED IN PRODUCTION AND EXISTS ONLY FOR TESTING PURPOSES.
    urlPrefix

    A prefix which is prepending to URLs constructed for the server. This should normally be nil, and customized only to match corresponding settings on the server.

    Return Value

    A default configuration object with the sync configuration set to use the given URL and options.

    Show on GitHub

  • Log a user out, destroying their server state, unregistering them from the SDK, and removing any synced Realms associated with them from on-disk storage on next app launch. If the user is already logged out or in an error state, this method does nothing.

    This method should be called whenever the application is committed to not using a user again unless they are recreated. Failing to call this method may result in unused files and metadata needlessly taking up space.

    Declaration

    Objective-C

    - (void)logOut;
    Show on GitHub

  • An optional error handler which can be set to notify the host application when the user encounters an error. Errors reported by this error handler are always RLMSyncAuthErrors.

    Note

    Check for RLMSyncAuthErrorInvalidAccessToken to see if the user has been remotely logged out because its refresh token expired, or because the third party authentication service providing the user’s identity has logged the user out.

    Warning

    Regardless of whether an error handler is installed, certain user errors will automatically cause the user to enter the logged out state.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable)
    RLMUserErrorReportingBlock errorHandler;
    Show on GitHub

Sessions

Passwords

  • Change this user’s password asynchronously.

    Warning

    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.

    Declaration

    Objective-C

    - (void)changePassword:(nonnull NSString *)newPassword
            completion:(nonnull RLMPasswordChangeStatusBlock)completion;

    Parameters

    newPassword

    The user’s new password.
    completion

    Completion block invoked when login has completed or failed. The callback will be invoked on a background queue provided by NSURLSession.
    Show on GitHub

  • Change an arbitrary user’s password asynchronously.

    Note

    The current user must be an admin user for this operation to succeed.

    Warning

    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.

    Declaration

    Objective-C

    - (void)changePassword:(nonnull NSString *)newPassword
             forUserID:(nonnull NSString *)userID
            completion:(nonnull RLMPasswordChangeStatusBlock)completion;

    Parameters

    newPassword

    The user’s new password.
    userID

    The identity of the user whose password should be changed.
    completion

    Completion block invoked when login has completed or failed. The callback will be invoked on a background queue provided by NSURLSession.
    Show on GitHub

  • Ask the server to send a password reset email to the given email address.

    If email is an email address which is associated with a user account that was registered using the password authentication service, the server will send an email to that address with a password reset token. No error is reported if the email address is invalid or not associated with an account.

    Declaration

    Objective-C

    + (void)requestPasswordResetForAuthServer:(nonnull NSURL *)serverURL
                                userEmail:(nonnull NSString *)email
                               completion:(nonnull RLMPasswordChangeStatusBlock)
                                              completion;

    Parameters

    serverURL

    The authentication server URL for the user.
    email

    The email address to send the email to.
    completion

    A block which will be called when the request completes or fails. The callback will be invoked on a background queue provided by NSURLSession, and not on the calling queue.
    Show on GitHub

  • Change a user’s password using a one-time password reset token.

    By default, the password reset email sent by ROS will link to a web site where the user can select a new password, and the app will not need to call this method. If you wish to instead handle this within your native app, you must change the baseURL in the server configuration for PasswordAuthProvider to a scheme registered for your app, extract the token from the URL, and call this method after prompting the user for a new password.

    Warning

    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.

    Declaration

    Objective-C

    + (void)completePasswordResetForAuthServer:(nonnull NSURL *)serverURL
                                     token:(nonnull NSString *)token
                                  password:(nonnull NSString *)newPassword
                                completion:
                                    (nonnull RLMPasswordChangeStatusBlock)
                                        completion;

    Parameters

    serverURL

    The authentication server URL for the user.
    token

    The one-time use token from the URL.
    newPassword

    The user’s new password.
    completion

    A block which will be called when the request completes or fails. The callback will be invoked on a background queue provided by NSURLSession, and not on the calling queue.
    Show on GitHub

  • Ask the server to send a confirmation email to the given email address.

    If email is an email address which is associated with a user account that was registered using the password authentication service, the server will send an email to that address with a confirmation token. No error is reported if the email address is invalid or not associated with an account.

    Declaration

    Objective-C

    + (void)requestEmailConfirmationForAuthServer:(nonnull NSURL *)serverURL
                                    userEmail:(nonnull NSString *)email
                                   completion:
                                       (nonnull RLMPasswordChangeStatusBlock)
                                           completion;

    Parameters

    serverURL

    The authentication server URL for the user.
    email

    The email address to send the email to.
    completion

    A block which will be called when the request completes or fails. The callback will be invoked on a background queue provided by NSURLSession, and not on the calling queue.
    Show on GitHub

  • Confirm a user’s email using a one-time confirmation token.

    By default, the confirmation email sent by ROS will link to a web site with a generic thank you for confirming your email message, and the app will not need to call this method. If you wish to instead handle this within your native app, you must change the baseURL in the server configuration for PasswordAuthProvider to a scheme registered for your app, extract the token from the URL, and call this method.

    Declaration

    Objective-C

    + (void)confirmEmailForAuthServer:(nonnull NSURL *)serverURL
                            token:(nonnull NSString *)token
                       completion:
                           (nonnull RLMPasswordChangeStatusBlock)completion;

    Parameters

    serverURL

    The authentication server URL for the user.
    token

    The one-time use token from the URL.
    completion

    A block which will be called when the request completes or fails. The callback will be invoked on a background queue provided by NSURLSession, and not on the calling queue.
    Show on GitHub

Administrator

  • Given a Realm Object Server authentication provider and a provider identifier for a user (for example, a username), look up and return user information for that user.

    Declaration

    Objective-C

    - (void)retrieveInfoForUser:(nonnull NSString *)providerUserIdentity
           identityProvider:(nonnull RLMIdentityProvider)provider
                 completion:(nonnull RLMRetrieveUserBlock)completion;

    Parameters

    providerUserIdentity

    The username or identity of the user as issued by the authentication provider. In most cases this is different from the Realm Object Server-issued identity.
    provider

    The authentication provider that manages the user whose information is desired.
    completion

    Completion block invoked when request has completed or failed. The callback will be invoked on a background queue provided by NSURLSession.
    Show on GitHub

Permissions

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

    The results will be returned through the callback block, or an error if the operation failed. The callback block will be run on the same thread the method was called on.

    Warning

    This method must be called from a thread with a currently active run loop. Unless you have manually configured a run loop on a side thread, this will usually be the main thread.

    Declaration

    Objective-C

    - (void)retrievePermissionsWithCallback:
    (nonnull RLMPermissionResultsBlock)callback;
    Show on GitHub

  • Apply a given permission.

    The operation will take place asynchronously, and the callback will be used to report whether the permission change succeeded or failed. The user calling this method must have the right to grant the given permission, or else the operation will fail.

    See

    RLMSyncPermission

    Declaration

    Objective-C

    - (void)applyPermission:(nonnull RLMSyncPermission *)permission
               callback:(nonnull RLMPermissionStatusBlock)callback;
    Show on GitHub

  • Revoke a given permission.

    The operation will take place asynchronously, and the callback will be used to report whether the permission change succeeded or failed. The user calling this method must have the right to grant the given permission, or else the operation will fail.

    See

    RLMSyncPermission

    Declaration

    Objective-C

    - (void)revokePermission:(nonnull RLMSyncPermission *)permission
                callback:(nonnull RLMPermissionStatusBlock)callback;
    Show on GitHub

  • Create a permission offer for a Realm.

    A permission offer is used to grant access to a Realm this user manages to another user. Creating a permission offer produces a string token which can be passed to the recepient in any suitable way (for example, via e-mail).

    The operation will take place asynchronously. The token can be accepted by the recepient using the -[RLMSyncUser acceptOfferForToken:callback:] method.

    See

    acceptOfferForToken:callback:

    Declaration

    Objective-C

    - (void)createOfferForRealmAtURL:(nonnull NSURL *)url
                     accessLevel:(RLMSyncAccessLevel)accessLevel
                      expiration:(nullable NSDate *)expirationDate
                        callback:
                            (nonnull RLMPermissionOfferStatusBlock)callback;

    Parameters

    url

    The URL of the Realm for which the permission offer should pertain. This may be the URL of any Realm which this user is allowed to manage. If the URL has a ~ wildcard it will be replaced with this user’s user identity.
    accessLevel

    What access level to grant to whoever accepts the token.
    expirationDate

    Optionally, a date which indicates when the offer expires. If the recepient attempts to accept the offer after the date it will be rejected.
    callback

    A callback indicating whether the operation succeeded or failed. If it succeeded the token will be passed in as a string.
    Show on GitHub

  • Accept a permission offer.

    Pass in a token representing a permission offer. The operation will take place asynchronously. If the operation succeeds, the callback will be passed the URL of the Realm for which the offer applied, so the Realm can be opened.

    The token this method accepts can be created by the offering user through the -[RLMSyncUser createOfferForRealmAtURL:accessLevel:expiration:callback:] method.

    See

    createOfferForRealmAtURL:accessLevel:expiration:callback:

    Declaration

    Objective-C

    - (void)acceptOfferForToken:(nonnull NSString *)token
                   callback:
                       (nonnull RLMPermissionOfferResponseStatusBlock)callback;
    Show on GitHub