MicroStrategy ONE

Mobile Authentication API Overview in iOS

The MicroStrategy Mobile SDK exposes a set of authentication APIs that you can use to customize the authentication process on the client side. This includes enhancements to the authentication prompts (login screen UI) not covered in the non-programmatic approach, as well as changes to the actual authentication workflow.

The authentication APIs can be grouped as four components, which work together to perform the authentication process:  

  • MSIMobileManager  
  • MSIMobileLoginPromptView and its subclasses  
  • MSIMobileLoginPromptViewController and its subclasses  

  • MSIMobileLoginModule and its subclasses  

The MSIMobileLoginManager is responsible for managing all the prompts, including their views, view controllers, modules and connection managers. It is a singleton that is created when the application launches and it is disposed of when the application is terminated.  

When the application launches, a singleton instance of MSIMobileLoginManager is created. Once this instance exists, you can register custom views, view controllers and login modules to customize the behavior of the components used during authentication. If you do not register your custom views, view controllers and login modules, when a user needs needs to be authenticated, the manager will instantiate its own default views, view controllers and login modules for the authentication type to be performed.  

When MicroStrategy Mobile needs to authenticate, the application can perform the authentication process in two different ways:

  • By presenting a login screen to the user and processing its input afterwards In this case, subclasses of all the components participate in the authentication process.  

  • By retrieving a set of credentials programmatically and using them to authenticate without presenting a login screen to the user

    In this case, only subclasses of MSIMobileLoginModule participate in the authentication process.  

There are different login screens for different types of authentication. These screens are instances of subclasses of MSIMobileLoginPromptViewController, whose view is an instance of a subclass of MSIMobileLoginPromptView. The component in charge of performing the actual authentication process is a subclass of the MSIMobileLoginModule.

The following diagram depicts how the different components interact to perform the authentication process in MicroStrategy Mobile.

  1. The application instantiates the MSIMobileLoginManager singleton. At this point, you should set up and register the MSIMobileLoginPromptView, MSIMobileLoginPromptViewController and MSIMobileLoginModule for each authentication type you want to have custom components for. When the application receives an authentication challenge (user tries to authenticate and a valid session is not available), the manager uses the custom MSIMobileLoginPromptView, MSIMobileLoginPromptViewController and MSIMobileLoginModule that you declared . If there are no custom objects defined for the authentication challenge type that is received, the framework creates default ones based on the following table:  

    Name Type View Controller Module

    Server and Project authentication

    AuthenticationPromptType

    MSICustomizableAuthenticationPromptView

    MSIAuthenticationPromptViewController

    MSIAuthenticationModule

    Certificate Server authentication

    CertificatePromptType

    MSICustomizableAuthenticationPromptView

    MSICertificateCreationViewController

    MSICertificateCreationModule

    Change password

    ChangePasswordPromptType

    MSICustomizableAuthenticationPromptView

    MSIChangePasswordViewController

    MSIChangePasswordModule

    HTML form authentication

    HTMLFormPromptType

    N/A

    MSIHTMLFormPromptViewController

    N/A

    Express authentication

    QuickViewLoginPromptType

    N/A

    QuickViewLoginViewController

    N/A

    OAuth authentication

    OAuthLoginPromptType

    MSIOAuthLoginPromptView

    MSIOAuthLoginPromptViewController

    MSIOAuthLoginPromptModule

    Configuration retrieval login

    UserDefinedLoginPromptType

    MSIConfigurationRetrievalLoginPromptView

    MSIConfigurationRetrievalLoginPromptViewController

    MSIConfigurationRetrievalLoginModule

  2. When a user taps on a button on the login screen to either sign in or cancel, the MSIMobileLoginPromptView notifies its delegate via the declared methods in MSIMobileLoginPromptViewDelegate. The view controller for MSIMobileLoginPromptView (MSIMobileLoginPromptViewController subclass) is usually the delegate of the MSIMobileLoginPromptView, and it receives the notification.  
  3. Once the MSIMobileLoginPromptViewController is notified about the user’s input, it uses its mobileLoginModule to perform the authentication process using the credentials provided by the user.  

  4. A specific subclass of MSIMobileLoginModule performs the authentication. There are different subclasses of MSIMobileLoginModule which are each responsible for performing a specific type of authentication: project authentication or certificate server authentication.  

  5. During the authentication process, the MSIMobileLoginModule subclass notifies its delegate about the different steps it takes via the declared methods in  MSIMobileLoginModuleDelegate. These steps include pre and post login operations, as well as notification of whether the authentication was successful or not. Usually the MSIMobileLoginPromptViewController subclass is the delegate of the MSIMobileLoginModule.  

  6. You can optionally assign a delegate object for the MSIMobileLoginPromptViewController. If this delegate object has been assigned, once the authentication process is completed, the MSIMobileLoginPromptViewController notifies the delegate object about updates via the methods defined in MSIMobileLoginPromptViewControllerDelegate. These notifications include whether the prompt will be dismissed and whether an error was encountered during the process.

Out-of-the-box project authentication workflow

The diagram below provides a detailed illustration of the workflow in out-of-the-box project authentication.

The steps below provide a detailed explanation of the out-of-the-box project authentication workflow.

  1. When an object (Folder, Report, Document) is accessed in the MicroStrategy Mobile application, the ObjectService tries to get the session state from the MSISessionConnectionManager (an instance variable of MSIMobileLoginManager) by calling the getConnection: method.  

  2. If the session state is invalid because of credentials problems, the MSISessionConnectionManager calls the MSIMobileLoginManager showPrompt:parameters:delegate: method to display the authentication prompt.  

  3. If the view controller for AuthenticationPromptType is not set, the MSIMobileLoginManager creates the default view controller. The MSIMobileLoginManager then sets up and presents the view controller by calling the setupWithMobileLoginPromptView:mobileLoginModule:parameters: method.  

  4. When the MSIAuthenticationPromptViewController is presented, it first checks the server connectivity, via the latency service. It then creates and sets up the view, by calling the setupWithParameters:delegate: method.  

  5. After the user has provided credentials on MSICustomizableAuthenticationPromptView, the view calls its delegate method loginPromptView:didInputAuthenticationParameters: on its delegate, which is the MSIAuthenticationPromptViewController.  

  6. The MSIAuthenticationPromptViewController then calls the MSIAuthenticationModule's startMobileLogin: method to perform the login.  

  7. Once login is successful, the MSIAuthenticationModule calsl its delegate methods mobileLoginModule:willHandlePostMobileLogin: and mobileLoginModule:mobileLoginDidSucceed: on its delegate object, which is the MSIAuthenticationPromptViewController, to save the credentials and close the prompt.  

  8. After the credentials are saved and the prompt is closed, the MSIAuthenticationPromptViewController call its delegate method mobileLoginPromptViewController:withPromptType:didDismissWithUpdateFlag: on the MSIMobileLoginManager.  

  9. After this is completed, the MSIMobileLoginManager calls handleMobileLoginPromptSuccess: on its delegate, which is an instance of MSISessionConnectionManager, and returns MOBILE_LOGIN_PROMPT_STATUS_ANSWERED in its showPrompt:parameters:delegate: method.  

  10. At this point, the mobile login is successful and the session state has been created. The MSISessionConnectionManager can finally return the session state to the ObjectService.