VaultMobileSDK  18R3
iOS framework for Vault API
Instance Methods | Class Methods | Properties | List of all members
VEVVaultAuth Class Reference

A singleton class that manages Vault authentication. More...

Inherits NSObject.

Instance Methods

(void) - authenticateWithHandler:
 Forces the appearance of the login view in order to perform either initial authentication or re-authentication to refresh the session. More...
 
(void) - logout
 Logs the user out and invokes the logout handler if set. The user is no longer locally authenticated after calling this method.
 
(void) - setLogoutHandler:
 Sets the callback handler that will be invoked when the user is logged out. Logout will occur when logout is called or may occur from within VaultMobileSDK itself. For example, when the user resets the pincode the user is logged out and prompted to log back in again. More...
 
(BOOL) - showLockScreen
 Forces the lock screen to display immediately. More...
 
(BOOL) - isShowingLockScreen
 Returns whether the lock screen is currently presented or not. More...
 
(void) - refreshUserWithHandler:
 Synchronizes the state associated with the current user with Vault. Currently this only includes the user's list of available vaults. More...
 
(void) - enableBiometricAuthentication:
 Enables or disables Biometric Authentication for both VEVVaultSDK's login view and passcode view. This must be set after calling application:didFinishLaunchingWithOptions: (VEVSDKApplicationDelegate) and before calling any method that may display the login view or passcode view. More...
 
(BOOL) - isBiometricAuthenticationEnabled
 Reports whether Biometric Authentication enabled for VEVVaultMobileSDK's login view and passcode view. More...
 

Class Methods

(instancetype) + sharedInstance
 Return the singleton instance.
 

Properties

VEVUsercurrentUser
 The user object that represents the locally authenticated user.
 
id< VEVPasscodeManagerDelegate > passcodeDelegate
 The object that acts as the delegate for VEVVaultAuth's lock screen view.
 

Detailed Description

A singleton class that manages Vault authentication.

Many of the features of VaultMobileSDK require authentication with Vault. Authentication can be performed in one of two ways: either implicitly or explicitly. An implicit login occurs whenever a VaultMobileSDK method is called that requires authentication—that is, a valid session ID, and either the user has not logged in previously or the current session ID has expired. When an implicit login occurs, the method that triggered it is interrupted and VaultMobileSDK displays a full-screen login UI (see login UI below). Once logged in the triggering method resumes. Any errors that occur are reported back to the application by means of callbacks. Implementations for these callbacks are the only code that the application developer needs to write in order to support authentication.

In addition to implicit login, the application developer can force authentication (or re-authentication) at any time by calling authenticateWithHandler: (VEVVaultAuth). This is termed explicit login.

Login UI

When the login view is displayed, regardless of whether in response to an implicit login or an explicit login, it performs a refresh session operation or it performs an initial login. When performing a refresh session, the username is pre-filled and rendered read-only. In addition, a Cancel button is displayed that allows the user to dismiss the login UI and return to the host app without performing any authentication (see "Local Authentication and Offline Access" below). In contrast, when performing an initial login the username is blank and the login UI cannot be dismissed until authentication completes successfully.

Local Authentication and Offline Access

Once authentication is complete, VaultMobileSDK regards the user as locally authenticated. This simply means that by virtue of having once logged in to Vault and obtained a session ID, the user is considered authenticated with respect to client-side operations until the user explicitly logs out. An expired session ID has no bearing on this status. In practice, this means that the user can dismiss the login view without re-authenticating with Vault. This ensures that the user can still access protected features of the application that don't require direct interaction with Vault even if network access is unavailable.

Pin Code View

VaultMobileSDK provides a client-side pin code protected lock screen that displays automatically after the application launches or is brought into the foreground from the background. New users set their pin codes immediately after authenticating for the first time.

Biometric Authentication

Biometric Authentication may be used when re-authenticating after a Vault session ID has expired and when unlocking the lock screen. Users have the option to enable Biometric Authentication by checking the Biometric Authentication on the login view.

OAuth

VaultMobileSDK supports authentication via OAuth for Vaults that have been configured for OAuth support. Authentication via OAuth behaves identically to basic authentication with the following exceptions:

  1. Once the user enters his or her username in the login view, VaultMobileSDK detects that the user is configured for OAuth and an SFSafariViewController is displayed with the IDP's login page loaded. Authentication via OAuth is conducted as normal and once complete, the application is notified via callback in the same manner as in basic authentication.
  2. Re-authentication is performed automatically and invisibly via refresh token or, if the refresh token expires, the VaultMobileSDK refresh session login view is bypassed entirely and the user re-authenticates with the IDP directly from within SFSafariViewController.
  3. Biometric Authentication is not supported for OAuth users.

The following steps are required in order to configure VaultMobileSDK for OAuth support. Once configured, VaultMobileSDK manages all of the particulars of OAuth on behalf of the host application.

  1. Add com.veeva.oauth.client_id to the Info.plist file with the corresponding OAuth client ID configured on the authentication server.
  2. Add com.veeva.oauth.redirect_uri to the Info.plist file with the corresponding redirect URI configured on the authentication server.
  3. In the application's UIApplicationDelegate:application:openURL:options: method, invoke VEVSDKApplicationDelegate:application:openURL:options:.

Method Documentation

◆ authenticateWithHandler:()

- (void) authenticateWithHandler: (nullable VEVVaultAuthLoginResultHandler handler

Forces the appearance of the login view in order to perform either initial authentication or re-authentication to refresh the session.

Parameters
handlerThe callback invoked after authentication completes.
Remarks
When handler is invoked after a successful login, it passes back the user object for the current user. If authentication fails, details regarding the failure are contained in the error parameter. If an error occurs during initial login user will be nil . If an error occurs while re-authenticating, then user corresponds to the user returned when authentication last succeeded.

◆ setLogoutHandler:()

- (void) setLogoutHandler: (nullable VEVVaultAuthLogoutHandler handler

Sets the callback handler that will be invoked when the user is logged out. Logout will occur when logout is called or may occur from within VaultMobileSDK itself. For example, when the user resets the pincode the user is logged out and prompted to log back in again.

Parameters
handlerThe callback invoked after logout completes.

◆ showLockScreen()

- (BOOL) showLockScreen

Forces the lock screen to display immediately.

Returns
YES if the user is locally authenticated and the passcode displayed, otherwise NO.

◆ isShowingLockScreen()

- (BOOL) isShowingLockScreen

Returns whether the lock screen is currently presented or not.

Returns
YES if the lock screen is currently present otherwise NO.

◆ refreshUserWithHandler:()

- (void) refreshUserWithHandler: (nullable VEVVaultAuthRefreshUserResultHandler handler

Synchronizes the state associated with the current user with Vault. Currently this only includes the user's list of available vaults.

Parameters
handlerThe callback invoked upon completion.
See also
- authenticateWithHandler:

◆ enableBiometricAuthentication:()

- (void) enableBiometricAuthentication: (BOOL)  enable

Enables or disables Biometric Authentication for both VEVVaultSDK's login view and passcode view. This must be set after calling application:didFinishLaunchingWithOptions: (VEVSDKApplicationDelegate) and before calling any method that may display the login view or passcode view.

Parameters
enableYES to enable Biometric Authentication, NO to disable. By default this value is set to YES.
Remarks
This is an opt-out method for overriding the Biometric Authentication configuration that may be set via EMM. If this value is NOT explicitly set via this method then VaultMobileSDK will use an EMM value located in the com.apple.configuration.managed EMM dictionary with key VeevaVaultBiometricAuthenticationVisible. If no EMM value is present it will default to YES.

◆ isBiometricAuthenticationEnabled()

- (BOOL) isBiometricAuthenticationEnabled

Reports whether Biometric Authentication enabled for VEVVaultMobileSDK's login view and passcode view.

See also
- enableBiometricAuthentication:
Returns
YES if Biometric Authentication is enabled, otherwise NO.

The documentation for this class was generated from the following file: