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;

    Swift

    class func __allUsers() -> [String : RLMSyncUser]
    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;

    Swift

    class func __current() -> RLMSyncUser?
    Show on GitHub

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

    Declaration

    Objective-C

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

    Swift

    var identity: String? { get }
    Show on GitHub

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

    Declaration

    Objective-C

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

    Swift

    var authenticationServer: URL? { get }
    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;

    Swift

    var isAdmin: Bool { get }
    Show on GitHub

  • The current state of the user.

    Declaration

    Objective-C

    @property (readonly, nonatomic) RLMSyncUserState state;

    Swift

    var state: RLMSyncUserState { get }
    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;

    Swift

    class func __logIn(with credentials: RLMSyncCredentials, authServerURL: URL, timeout: TimeInterval, callbackQueue: DispatchQueue, onCompletion completion: @escaping RLMUserCompletionBlock)
    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

  • 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;

    Swift

    func 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;

    Swift

    var __errorHandler: RLMUserErrorReportingBlock? { get set }
    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;

    Swift

    func changePassword(_ newPassword: String, completion: @escaping RLMPasswordChangeStatusBlock)

    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;

    Swift

    func changePassword(_ newPassword: String, forUserID userID: String, completion: @escaping RLMPasswordChangeStatusBlock)

    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

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;

    Swift

    func retrieveInfo(forUser providerUserIdentity: String, identityProvider provider: RLMIdentityProvider, completion: @escaping RLMRetrieveUserBlock)

    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;

    Swift

    func __retrievePermissions(callback: @escaping RLMPermissionResultsBlock)
    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;

    Swift

    func apply(_ permission: RLMSyncPermission, callback: @escaping RLMPermissionStatusBlock)
    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;

    Swift

    func revokePermission(_ permission: RLMSyncPermission, callback: @escaping RLMPermissionStatusBlock)
    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;

    Swift

    func __createOfferForRealm(at url: URL, accessLevel: RLMSyncAccessLevel, expiration expirationDate: Date?, callback: @escaping RLMPermissionOfferStatusBlock)

    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;

    Swift

    func acceptOffer(forToken token: String, callback: @escaping RLMPermissionOfferResponseStatusBlock)
    Show on GitHub