1 ////////////////////////////////////////////////////////////////////////////
3 // Copyright 2016 Realm Inc.
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
17 ////////////////////////////////////////////////////////////////////////////
19 #import <Foundation/Foundation.h>
21 #import "RLMResults.h"
22 #import "RLMSyncCredentials.h"
23 #import "RLMSyncPermission.h"
25 @class RLMSyncUser, RLMSyncUserInfo, RLMSyncCredentials, RLMSyncPermission, RLMSyncSession, RLMRealm;
28 The state of the user object.
30 typedef NS_ENUM(NSUInteger, RLMSyncUserState) {
31 /// The user is logged out. Call `logInWithCredentials:...` with valid credentials to log the user back in.
32 RLMSyncUserStateLoggedOut,
33 /// The user is logged in, and any Realms associated with it are syncing with the Realm Object Server.
34 RLMSyncUserStateActive,
35 /// The user has encountered a fatal error state, and cannot be used.
36 RLMSyncUserStateError,
39 /// A block type used for APIs which asynchronously vend an `RLMSyncUser`.
40 typedef void(^RLMUserCompletionBlock)(RLMSyncUser * _Nullable, NSError * _Nullable);
42 /// A block type used to report the status of a password change operation.
43 /// If the `NSError` argument is nil, the operation succeeded.
44 typedef void(^RLMPasswordChangeStatusBlock)(NSError * _Nullable);
46 /// A block type used to report the status of a permission apply or revoke operation.
47 /// If the `NSError` argument is nil, the operation succeeded.
48 typedef void(^RLMPermissionStatusBlock)(NSError * _Nullable);
50 /// A block type used to report the status of a permission offer operation.
51 typedef void(^RLMPermissionOfferStatusBlock)(NSString * _Nullable, NSError * _Nullable);
53 /// A block type used to report the status of a permission offer response operation.
54 typedef void(^RLMPermissionOfferResponseStatusBlock)(NSURL * _Nullable, NSError * _Nullable);
56 /// A block type used to asynchronously report results of a permissions get operation.
57 /// Exactly one of the two arguments will be populated.
58 typedef void(^RLMPermissionResultsBlock)(RLMResults<RLMSyncPermission *> * _Nullable, NSError * _Nullable);
60 /// A block type used to asynchronously report results of a user info retrieval.
61 /// Exactly one of the two arguments will be populated.
62 typedef void(^RLMRetrieveUserBlock)(RLMSyncUserInfo * _Nullable, NSError * _Nullable);
64 /// A block type used to report an error related to a specific user.
65 typedef void(^RLMUserErrorReportingBlock)(RLMSyncUser * _Nonnull, NSError * _Nonnull);
67 NS_ASSUME_NONNULL_BEGIN
70 A `RLMSyncUser` instance represents a single Realm Object Server user account.
72 A user may have one or more credentials associated with it. These credentials
73 uniquely identify the user to the authentication provider, and are used to sign
74 into a Realm Object Server user account.
76 Note that user objects are only vended out via SDK APIs, and cannot be directly
77 initialized. User objects can be accessed from any thread.
79 @interface RLMSyncUser : NSObject
82 A dictionary of all valid, logged-in user identities corresponding to their user objects.
84 + (NSDictionary<NSString *, RLMSyncUser *> *)allUsers NS_REFINED_FOR_SWIFT;
87 The logged-in user. `nil` if none exists.
89 @warning Throws an exception if more than one logged-in user exists.
91 + (nullable RLMSyncUser *)currentUser NS_REFINED_FOR_SWIFT;
94 The unique Realm Object Server user ID string identifying this user.
96 @property (nullable, nonatomic, readonly) NSString *identity;
99 The URL of the authentication server this user will communicate with.
101 @property (nullable, nonatomic, readonly) NSURL *authenticationServer;
104 Whether the user is a Realm Object Server administrator. Value reflects the
105 state at the time of the last successful login of this user.
107 @property (nonatomic, readonly) BOOL isAdmin;
110 The current state of the user.
112 @property (nonatomic, readonly) RLMSyncUserState state;
114 #pragma mark - Lifecycle
117 Create, log in, and asynchronously return a new user object, specifying a custom
118 timeout for the network request and a custom queue to run the callback upon.
119 Credentials identifying the user must be passed in. The user becomes available in
120 the completion block, at which point it is ready for use.
122 + (void)logInWithCredentials:(RLMSyncCredentials *)credentials
123 authServerURL:(NSURL *)authServerURL
124 timeout:(NSTimeInterval)timeout
125 callbackQueue:(dispatch_queue_t)callbackQueue
126 onCompletion:(RLMUserCompletionBlock)completion NS_REFINED_FOR_SWIFT;
129 Create, log in, and asynchronously return a new user object.
131 If the login completes successfully, the completion block will invoked with
132 a `RLMSyncUser` object representing the logged-in user. This object can be
133 used to open synchronized Realms. If the login fails, the completion block
134 will be invoked with an error.
136 The completion block always runs on the main queue.
138 @param credentials A credentials value identifying the user to be logged in.
139 @param authServerURL The URL of the authentication server (e.g. "http://realm.example.org:9080").
140 @param completion A callback block that returns a user object or an error,
141 indicating the completion of the login operation.
143 + (void)logInWithCredentials:(RLMSyncCredentials *)credentials
144 authServerURL:(NSURL *)authServerURL
145 onCompletion:(RLMUserCompletionBlock)completion
146 NS_SWIFT_UNAVAILABLE("Use the full version of this API.");
149 Log a user out, destroying their server state, unregistering them from the SDK,
150 and removing any synced Realms associated with them from on-disk storage on
151 next app launch. If the user is already logged out or in an error state, this
154 This method should be called whenever the application is committed to not using
155 a user again unless they are recreated.
156 Failing to call this method may result in unused files and metadata needlessly
162 An optional error handler which can be set to notify the host application when
163 the user encounters an error. Errors reported by this error handler are always
166 @note Check for `RLMSyncAuthErrorInvalidAccessToken` to see if the user has
167 been remotely logged out because its refresh token expired, or because the
168 third party authentication service providing the user's identity has
171 @warning Regardless of whether an error handler is installed, certain user errors
172 will automatically cause the user to enter the logged out state.
174 @property (nullable, nonatomic) RLMUserErrorReportingBlock errorHandler NS_REFINED_FOR_SWIFT;
176 #pragma mark - Sessions
179 Retrieve a valid session object belonging to this user for a given URL, or `nil`
180 if no such object exists.
182 - (nullable RLMSyncSession *)sessionForURL:(NSURL *)url;
185 Retrieve all the valid sessions belonging to this user.
187 - (NSArray<RLMSyncSession *> *)allSessions;
189 #pragma mark - Passwords
192 Change this user's password asynchronously.
194 @warning Changing a user's password using an authentication server that doesn't
195 use HTTPS is a major security flaw, and should only be done while
198 @param newPassword The user's new password.
199 @param completion Completion block invoked when login has completed or failed.
200 The callback will be invoked on a background queue provided
203 - (void)changePassword:(NSString *)newPassword completion:(RLMPasswordChangeStatusBlock)completion;
206 Change an arbitrary user's password asynchronously.
208 @note The current user must be an admin user for this operation to succeed.
210 @warning Changing a user's password using an authentication server that doesn't
211 use HTTPS is a major security flaw, and should only be done while
214 @param newPassword The user's new password.
215 @param userID The identity of the user whose password should be changed.
216 @param completion Completion block invoked when login has completed or failed.
217 The callback will be invoked on a background queue provided
220 - (void)changePassword:(NSString *)newPassword forUserID:(NSString *)userID completion:(RLMPasswordChangeStatusBlock)completion;
222 #pragma mark - Administrator
225 Given a Realm Object Server authentication provider and a provider identifier for a user
226 (for example, a username), look up and return user information for that user.
228 @param providerUserIdentity The username or identity of the user as issued by the authentication provider.
229 In most cases this is different from the Realm Object Server-issued identity.
230 @param provider The authentication provider that manages the user whose information is desired.
231 @param completion Completion block invoked when request has completed or failed.
232 The callback will be invoked on a background queue provided
235 - (void)retrieveInfoForUser:(NSString *)providerUserIdentity
236 identityProvider:(RLMIdentityProvider)provider
237 completion:(RLMRetrieveUserBlock)completion;
239 #pragma mark - Permissions
242 Asynchronously retrieve all permissions associated with the user calling this method.
244 The results will be returned through the callback block, or an error if the operation failed.
245 The callback block will be run on the same thread the method was called on.
247 @warning This method must be called from a thread with a currently active run loop. Unless
248 you have manually configured a run loop on a side thread, this will usually be the
251 - (void)retrievePermissionsWithCallback:(RLMPermissionResultsBlock)callback NS_REFINED_FOR_SWIFT;
254 Apply a given permission.
256 The operation will take place asynchronously, and the callback will be used to report whether
257 the permission change succeeded or failed. The user calling this method must have the right
258 to grant the given permission, or else the operation will fail.
260 @see `RLMSyncPermission`
262 - (void)applyPermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
265 Revoke a given permission.
267 The operation will take place asynchronously, and the callback will be used to report whether
268 the permission change succeeded or failed. The user calling this method must have the right
269 to grant the given permission, or else the operation will fail.
271 @see `RLMSyncPermission`
273 - (void)revokePermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
276 Create a permission offer for a Realm.
278 A permission offer is used to grant access to a Realm this user manages to another
279 user. Creating a permission offer produces a string token which can be passed to the
280 recepient in any suitable way (for example, via e-mail).
282 The operation will take place asynchronously. The token can be accepted by the recepient
283 using the `-[RLMSyncUser acceptOfferForToken:callback:]` method.
285 @param url The URL of the Realm for which the permission offer should pertain. This
286 may be the URL of any Realm which this user is allowed to manage. If the URL
287 has a `~` wildcard it will be replaced with this user's user identity.
288 @param accessLevel What access level to grant to whoever accepts the token.
289 @param expirationDate Optionally, a date which indicates when the offer expires. If the
290 recepient attempts to accept the offer after the date it will be rejected.
291 @param callback A callback indicating whether the operation succeeded or failed. If it
292 succeeded the token will be passed in as a string.
294 @see `acceptOfferForToken:callback:`
296 - (void)createOfferForRealmAtURL:(NSURL *)url
297 accessLevel:(RLMSyncAccessLevel)accessLevel
298 expiration:(nullable NSDate *)expirationDate
299 callback:(RLMPermissionOfferStatusBlock)callback NS_REFINED_FOR_SWIFT;
302 Accept a permission offer.
304 Pass in a token representing a permission offer. The operation will take place asynchronously.
305 If the operation succeeds, the callback will be passed the URL of the Realm for which the
306 offer applied, so the Realm can be opened.
308 The token this method accepts can be created by the offering user through the
309 `-[RLMSyncUser createOfferForRealmAtURL:accessLevel:expiration:callback:]` method.
311 @see `createOfferForRealmAtURL:accessLevel:expiration:callback:`
313 - (void)acceptOfferForToken:(NSString *)token
314 callback:(RLMPermissionOfferResponseStatusBlock)callback;
317 - (instancetype)init __attribute__((unavailable("RLMSyncUser cannot be created directly")));
319 + (instancetype)new __attribute__((unavailable("RLMSyncUser cannot be created directly")));
323 #pragma mark - User info classes
326 A data object representing a user account associated with a user.
328 @see `RLMSyncUserInfo`
330 @interface RLMSyncUserAccountInfo : NSObject
332 /// The authentication provider which manages this user account.
333 @property (nonatomic, readonly) RLMIdentityProvider provider;
335 /// The username or identity of this user account.
336 @property (nonatomic, readonly) NSString *providerUserIdentity;
339 - (instancetype)init __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
341 + (instancetype)new __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
346 A data object representing information about a user that was retrieved from a user lookup call.
348 @interface RLMSyncUserInfo : NSObject
351 An array of all the user accounts associated with this user.
353 @property (nonatomic, readonly) NSArray<RLMSyncUserAccountInfo *> *accounts;
356 The identity issued to this user by the Realm Object Server.
358 @property (nonatomic, readonly) NSString *identity;
361 Metadata about this user stored on the Realm Object Server.
363 @property (nonatomic, readonly) NSDictionary<NSString *, NSString *> *metadata;
366 Whether the user is flagged on the Realm Object Server as an administrator.
368 @property (nonatomic, readonly) BOOL isAdmin;
371 - (instancetype)init __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
373 + (instancetype)new __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
377 NS_ASSUME_NONNULL_END