iOS/Pods/Realm/include/RLMSyncUser.h

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2016 Realm Inc.
   4 //
   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
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17 ////////////////////////////////////////////////////////////////////////////
  18
  19 #import <Foundation/Foundation.h>
  20
  21 #import "RLMResults.h"
  22 #import "RLMSyncCredentials.h"
  23 #import "RLMSyncPermission.h"
  24
  25 @class RLMSyncUser, RLMSyncUserInfo, RLMSyncCredentials, RLMSyncPermission, RLMSyncSession, RLMRealm;
  26
  27 /**
  28  The state of the user object.
  29  */
  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,
  37 };
  38
  39 /// A block type used for APIs which asynchronously vend an `RLMSyncUser`.
  40 typedef void(^RLMUserCompletionBlock)(RLMSyncUser * _Nullable, NSError * _Nullable);
  41
  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);
  45
  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);
  49
  50 /// A block type used to report the status of a permission offer operation.
  51 typedef void(^RLMPermissionOfferStatusBlock)(NSString * _Nullable, NSError * _Nullable);
  52
  53 /// A block type used to report the status of a permission offer response operation.
  54 typedef void(^RLMPermissionOfferResponseStatusBlock)(NSURL * _Nullable, NSError * _Nullable);
  55
  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);
  59
  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);
  63
  64 /// A block type used to report an error related to a specific user.
  65 typedef void(^RLMUserErrorReportingBlock)(RLMSyncUser * _Nonnull, NSError * _Nonnull);
  66
  67 NS_ASSUME_NONNULL_BEGIN
  68
  69 /**
  70  A `RLMSyncUser` instance represents a single Realm Object Server user account.
  71
  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.
  75
  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.
  78  */
  79 @interface RLMSyncUser : NSObject
  80
  81 /**
  82  A dictionary of all valid, logged-in user identities corresponding to their user objects.
  83  */
  84 + (NSDictionary<NSString *, RLMSyncUser *> *)allUsers NS_REFINED_FOR_SWIFT;
  85
  86 /**
  87  The logged-in user. `nil` if none exists.
  88
  89  @warning Throws an exception if more than one logged-in user exists.
  90  */
  91 + (nullable RLMSyncUser *)currentUser NS_REFINED_FOR_SWIFT;
  92
  93 /**
  94  The unique Realm Object Server user ID string identifying this user.
  95  */
  96 @property (nullable, nonatomic, readonly) NSString *identity;
  97
  98 /**
  99  The URL of the authentication server this user will communicate with.
 100  */
 101 @property (nullable, nonatomic, readonly) NSURL *authenticationServer;
 102
 103 /**
 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.
 106  */
 107 @property (nonatomic, readonly) BOOL isAdmin;
 108
 109 /**
 110  The current state of the user.
 111  */
 112 @property (nonatomic, readonly) RLMSyncUserState state;
 113
 114 #pragma mark - Lifecycle
 115
 116 /**
 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.
 121  */
 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;
 127
 128 /**
 129  Create, log in, and asynchronously return a new user object.
 130
 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.
 135
 136  The completion block always runs on the main queue.
 137
 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.
 142  */
 143 + (void)logInWithCredentials:(RLMSyncCredentials *)credentials
 144                authServerURL:(NSURL *)authServerURL
 145                 onCompletion:(RLMUserCompletionBlock)completion
 146 NS_SWIFT_UNAVAILABLE("Use the full version of this API.");
 147
 148 /**
 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
 152  method does nothing.
 153
 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
 157  taking up space.
 158  */
 159 - (void)logOut;
 160
 161 /**
 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
 164  `RLMSyncAuthError`s.
 165
 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
 169        logged the user out.
 170
 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.
 173  */
 174 @property (nullable, nonatomic) RLMUserErrorReportingBlock errorHandler NS_REFINED_FOR_SWIFT;
 175
 176 #pragma mark - Sessions
 177
 178 /**
 179  Retrieve a valid session object belonging to this user for a given URL, or `nil`
 180  if no such object exists.
 181  */
 182 - (nullable RLMSyncSession *)sessionForURL:(NSURL *)url;
 183
 184 /**
 185  Retrieve all the valid sessions belonging to this user.
 186  */
 187 - (NSArray<RLMSyncSession *> *)allSessions;
 188
 189 #pragma mark - Passwords
 190
 191 /**
 192  Change this user's password asynchronously.
 193
 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
 196           testing.
 197
 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
 201                     by `NSURLSession`.
 202  */
 203 - (void)changePassword:(NSString *)newPassword completion:(RLMPasswordChangeStatusBlock)completion;
 204
 205 /**
 206  Change an arbitrary user's password asynchronously.
 207
 208  @note    The current user must be an admin user for this operation to succeed.
 209
 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
 212           testing.
 213
 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
 218                     by `NSURLSession`.
 219  */
 220 - (void)changePassword:(NSString *)newPassword forUserID:(NSString *)userID completion:(RLMPasswordChangeStatusBlock)completion;
 221
 222 #pragma mark - Administrator
 223
 224 /**
 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.
 227
 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
 233                                 by `NSURLSession`.
 234  */
 235 - (void)retrieveInfoForUser:(NSString *)providerUserIdentity
 236            identityProvider:(RLMIdentityProvider)provider
 237                  completion:(RLMRetrieveUserBlock)completion;
 238
 239 #pragma mark - Permissions
 240
 241 /**
 242  Asynchronously retrieve all permissions associated with the user calling this method.
 243
 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.
 246
 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
 249           main thread.
 250  */
 251 - (void)retrievePermissionsWithCallback:(RLMPermissionResultsBlock)callback NS_REFINED_FOR_SWIFT;
 252
 253 /**
 254  Apply a given permission.
 255
 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.
 259
 260  @see `RLMSyncPermission`
 261  */
 262 - (void)applyPermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
 263
 264 /**
 265  Revoke a given permission.
 266
 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.
 270
 271  @see `RLMSyncPermission`
 272  */
 273 - (void)revokePermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
 274
 275 /**
 276  Create a permission offer for a Realm.
 277
 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).
 281
 282  The operation will take place asynchronously. The token can be accepted by the recepient
 283  using the `-[RLMSyncUser acceptOfferForToken:callback:]` method.
 284
 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.
 293
 294  @see `acceptOfferForToken:callback:`
 295  */
 296 - (void)createOfferForRealmAtURL:(NSURL *)url
 297                      accessLevel:(RLMSyncAccessLevel)accessLevel
 298                       expiration:(nullable NSDate *)expirationDate
 299                         callback:(RLMPermissionOfferStatusBlock)callback NS_REFINED_FOR_SWIFT;
 300
 301 /**
 302  Accept a permission offer.
 303
 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.
 307
 308  The token this method accepts can be created by the offering user through the
 309  `-[RLMSyncUser createOfferForRealmAtURL:accessLevel:expiration:callback:]` method.
 310
 311  @see `createOfferForRealmAtURL:accessLevel:expiration:callback:`
 312  */
 313 - (void)acceptOfferForToken:(NSString *)token
 314                    callback:(RLMPermissionOfferResponseStatusBlock)callback;
 315
 316 /// :nodoc:
 317 - (instancetype)init __attribute__((unavailable("RLMSyncUser cannot be created directly")));
 318 /// :nodoc:
 319 + (instancetype)new __attribute__((unavailable("RLMSyncUser cannot be created directly")));
 320
 321 @end
 322
 323 #pragma mark - User info classes
 324
 325 /**
 326  A data object representing a user account associated with a user.
 327
 328  @see `RLMSyncUserInfo`
 329  */
 330 @interface RLMSyncUserAccountInfo : NSObject
 331
 332 /// The authentication provider which manages this user account.
 333 @property (nonatomic, readonly) RLMIdentityProvider provider;
 334
 335 /// The username or identity of this user account.
 336 @property (nonatomic, readonly) NSString *providerUserIdentity;
 337
 338 /// :nodoc:
 339 - (instancetype)init __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
 340 /// :nodoc:
 341 + (instancetype)new __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
 342
 343 @end
 344
 345 /**
 346  A data object representing information about a user that was retrieved from a user lookup call.
 347  */
 348 @interface RLMSyncUserInfo : NSObject
 349
 350 /**
 351  An array of all the user accounts associated with this user.
 352  */
 353 @property (nonatomic, readonly) NSArray<RLMSyncUserAccountInfo *> *accounts;
 354
 355 /**
 356  The identity issued to this user by the Realm Object Server.
 357  */
 358 @property (nonatomic, readonly) NSString *identity;
 359
 360 /**
 361  Metadata about this user stored on the Realm Object Server.
 362  */
 363 @property (nonatomic, readonly) NSDictionary<NSString *, NSString *> *metadata;
 364
 365 /**
 366  Whether the user is flagged on the Realm Object Server as an administrator.
 367  */
 368 @property (nonatomic, readonly) BOOL isAdmin;
 369
 370 /// :nodoc:
 371 - (instancetype)init __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
 372 /// :nodoc:
 373 + (instancetype)new __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
 374
 375 @end
 376
 377 NS_ASSUME_NONNULL_END