DBOAuthManager

Objective-C

@interface DBOAuthManager : NSObject <DBAccessTokenRefreshing> {
  NSString *_appKey;
  NSURL *_redirectURL;
  NSURL *_cancelURL;
  NSString *_host;
  NSMutableArray<NSURL *> *_urls;
  DBOAuthPKCESession *_authSession;
}

Swift

class DBOAuthManager : NSObject, DBAccessTokenRefreshing

Platform-neutral manager for performing OAuth linking.

Note

OAuth flow webviews localize to environment locale.
  • Sets the locale of the OAuth flow webpages. If nil, then defaults to device locale.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSLocale *_Nonnull locale;

    Swift

    var locale: Locale { get set }

Shared instance accessors and mutators

  • Accessor method for DBOAuthManager shared instance.

    Shared instance is used to authenticate users through OAuth2, save access tokens, and retrieve access tokens.

    Declaration

    Objective-C

    + (nullable DBOAuthManager *)sharedOAuthManager;

    Swift

    class func shared() -> DBOAuthManager?

    Return Value

    The DBOAuthManager shared instance.

  • Mutator method for DBOAuthManager shared instance.

    Shared instance is used to authenticate users through OAuth2, save access tokens, and retrieve access tokens.

    Declaration

    Objective-C

    + (void)setSharedOAuthManager:(nonnull DBOAuthManager *)sharedOAuthManager;

    Swift

    class func setShared(_ sharedOAuthManager: DBOAuthManager)

    Parameters

    sharedOAuthManager

    The updated reference to the DBOAuthManager shared instance.

Constructors

  • DBOAuthManager convenience constructor.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithAppKey:(nonnull NSString *)appKey;

    Swift

    init(appKey: String)

    Parameters

    appKey

    The app key from the developer console that identifies this app.

    Return Value

    An initialized instance.

  • DBOAuthManager convenience constructor.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithAppKey:(nonnull NSString *)appKey
                                      host:(nullable NSString *)host;

    Swift

    init(appKey: String, host: String?)

    Parameters

    appKey

    The app key from the developer console that identifies this app.

    host

    The host of the OAuth web flow. Leave nil to use default host.

    Return Value

    An initialized instance.

  • DBOAuthManager full constructor.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithAppKey:(nonnull NSString *)appKey
                                      host:(nullable NSString *)host
                               redirectURL:(nullable NSString *)redirectURL;

    Swift

    init(appKey: String, host: String?, redirectURL: String?)

    Parameters

    appKey

    The app key from the developer console that identifies this app.

    host

    The host of the OAuth web flow. Leave nil to use default host.

    redirectURL

    The redirect url of the OAuth web flow. Default to “db-://2/token”

    Return Value

    An initialized instance.

Auth flow methods

  • Commences the authorization flow (platform-neutral).

    Interfaces with platform-specific rendering logic via the DBSharedApplication protocol.

    Declaration

    Objective-C

    - (void)authorizeFromSharedApplication:
        (nonnull id<DBSharedApplication>)sharedApplication;

    Parameters

    sharedApplication

    A platform-neutral shared application abstraction for rendering auth flow.

  • Commences the authorization flow (platform-neutral).

    Interfaces with platform-specific rendering logic via the DBSharedApplication protocol.

    Declaration

    Objective-C

    - (void)authorizeFromSharedApplication:
                (nonnull id<DBSharedApplication>)sharedApplication
                                   usePkce:(BOOL)usePkce
                              scopeRequest:(nullable DBScopeRequest *)scopeRequest;

    Parameters

    sharedApplication

    A platform-neutral shared application abstraction for rendering auth flow.

    usePkce

    Whether to use OAuth2 code flow with PKCE.

    scopeRequest

    The ScopeRequest, only used in code flow with PKCE.

  • Handles a redirect back into the application (from whichever auth flow was being used).

    Declaration

    Objective-C

    - (BOOL)handleRedirectURL:(nonnull NSURL *)url
                   completion:(nonnull DBOAuthCompletion)completion;

    Swift

    func handleRedirectURL(_ url: URL, completion: @escaping DBOAuthCompletion) -> Bool

    Parameters

    url

    The redirect URL to attempt to handle.

    completion

    Completion block for oauth result, called with nil if SDK cannot handle the redirect URL, otherwise an instance of DBOAuthResult.

    Return Value

    Whether the URL can be handled.

Keychain methods

  • Saves an access token to the DBKeychain class.

    Declaration

    Objective-C

    - (BOOL)storeAccessToken:(nonnull DBAccessToken *)accessToken;

    Swift

    func store(_ accessToken: DBAccessToken) -> Bool

    Parameters

    accessToken

    The access token to save.

    Return Value

    Whether the save operation succeeded.

  • Utility function to return an arbitrary access token from the DBKeychain class, if any exist.

    Declaration

    Objective-C

    - (nullable DBAccessToken *)retrieveFirstAccessToken;

    Swift

    func retrieveFirstAccessToken() -> DBAccessToken?

    Return Value

    the “first” access token found, if any, otherwise nil.

  • Retrieves the access token for a particular user from the DBKeychain class.

    Declaration

    Objective-C

    - (nullable DBAccessToken *)retrieveAccessToken:(nonnull NSString *)tokenUid;

    Swift

    func retrieveAccessToken(_ tokenUid: String) -> DBAccessToken?

    Parameters

    tokenUid

    The uid of the access token to retrieve.

    Return Value

    An access token if present, otherwise nil.

  • Retrieves all stored access tokens from the DBKeychain class.

    Declaration

    Objective-C

    - (nonnull NSDictionary<NSString *, DBAccessToken *> *)retrieveAllAccessTokens;

    Swift

    func retrieveAllAccessTokens() -> [String : DBAccessToken]

    Return Value

    a dictionary mapping token uids to their access tokens.

  • Checks if there are any stored access tokens in the DBKeychain class.

    Declaration

    Objective-C

    - (BOOL)hasStoredAccessTokens;

    Swift

    func hasStoredAccessTokens() -> Bool

    Return Value

    Whether there are stored access tokens.

  • Deletes a specific access tokens from the DBKeychain class.

    Declaration

    Objective-C

    - (BOOL)clearStoredAccessToken:(nonnull NSString *)tokenUid;

    Swift

    func clearStoredAccessToken(_ tokenUid: String) -> Bool

    Parameters

    tokenUid

    The uid of the access token to delete.

    Return Value

    Whether the delete operation succeeded.

  • Deletes all stored access tokens in the DBKeychain class.

    Declaration

    Objective-C

    - (BOOL)clearStoredAccessTokens;

    Swift

    func clearStoredAccessTokens() -> Bool

    Return Value

    Whether the batch deletion operation succeeded.

  • When YES users will not be able to sign up for a Dropbox account via the authorization page. Instead, the authorization page will show a link to the Dropbox iOS app in the App Store. This is was originally intended for use when necessary for compliance with App Store policies.

    Default value is YES.

    NOTE: Recent App Store policy suggests that sign up is now allowed, so it should be safe to enable signup. However we are keeping the parameter and defaulting to YES to allow SDK users to make the appropriate decision for their apps.

    Declaration

    Objective-C

    @property (nonatomic) BOOL disableSignup;

    Swift

    var disableSignup: Bool { get set }
  • When YES, users who use the web auth flow (NOT dbapp delegated auth) will be forced to sign in from scratch. When NO, there is saved session data from the SafariViewController that can be used across signin attempts. This is intended for use with multi-account applications for App Store compliance, since adding a second account would shortcut the username/password entry page and use the first account’s credentials.

    Default value is NO, which is consistent with historical behavior.

    Declaration

    Objective-C

    @property (nonatomic) BOOL webAuthShouldForceReauthentication;

    Swift

    var webAuthShouldForceReauthentication: Bool { get set }