Configuration files and bean classes

To customize authentication for MicroStrategy Library, you make changes to the Spring bean definitions in the XML configuration files. Depending on the customization, you may sometimes need to sub-class a bean defined in the configuration file.

• Changing bean definitions in XML configuration files
• Sub-classing Java bean classes

Changing bean definitions in XML configuration files

The MicroStrategy Authentication Module is configured by a set of XML files located in the auth folder of the restful-api-1.0-SNAPSHOT-jar-with-dependencies.jar file.

• MainConfig.xml

  MainConfig.xml defines the basic Authentication Module infrastructure and some shared beans that are used for all or several supported authentication modes. It also holds the configuration information for the beans responsible for multi-mode support.

• Authentication mode-specific XML configuration files

  There are separate XML configuration files for each supported authentication mode, with the name of the file reflecting the authentication mode it is used to configure. For example, StdConfig.xml is the configuration file for Standard authentication.

  Maintaining a separate configuration file for each authentication mode makes it possible to load only the configuration files for the authentication modes that are enabled.

In addition to the main configuration files described above, there is a corresponding set of configuration files with the same names located in the auth/custom folder. You use these configuration files to customize authentication. The beans defined in these custom configuration files override the definitions of the beans with the same IDs defined in the main configuration files.

Out-of-the-box, these custom configuration files that are provided for you contain no bean definitions. To customize a specific authentication mode, you do the following:

1. You first copy the custom configuration file for the desired authentication mode from the JAR into the WEB-INF\classes\auth\custom folder of your MicroStrategy Library installation directory.

2. Then you add your custom bean definitions to this copied configuration file.
3. For simple customizations, you typically only need to change the values of some bean properties in the configuration file . However, for more complex customizations, you may need to sub-class one or more beans and override the default beans with custom bean definitions that use your bean classes.

Sub-classing Java bean classes

• AuthModeConfig

  The AuthModeConfig bean is the top-level bean in any authentication mode XML configuration file. This bean is responsible for connecting the authentication mode-specific beans defined in this XML configuration file to the overall Authentication Module infrastructure defined in MainConfig.xml.

  The AuthModeConfig bean has four configurable properties, which described in the table below.

  Property	Required / Optional	Description
  authMode	R	Defines the authentication mode handled by this bean definition
  entryPoint	R	Defines the bean responsible for displaying the GUI for this authentication mode
  filter	R	Defines the bean responsible for handling a login request for this authentication mode
  protocolFilters	O	Defines the filters responsible for handling protocol-specific requests for this authentication mode

  Each authentication mode uses its own version of the beans in the table above. A more detailed description of these beans is provided below.

  • entryPoint bean

    This bean is activated when the Authentication Module infrastructure detects an unauthorized request to access a protected resource. It is responsible for displaying the GUI for the specified authentication mode. Normally, this bean either redirects to the local HTML or JSP page (Standard, LDAP authentication mode) or to an external SSO authentication endpoint (SAML).

  • filter bean

    This bean is responsible for handling a login request for the specified authentication mode. Because authentication is a complex process, this bean usually delegates certain authentication tasks to child beans configured via this bean's properties. The table below lists typical helper beans involved in handling authentication requests:

    Bean	Description
    authenticationProvider	This bean is responsible for authenticating a user based on information extracted from the login request.
    iServerCredentialsProvider	This bean is responsible for creating and populating an instance of IServerCredentials defining the credentials for creating IServer sessions. The IServerCredentials object is passed to the SessionManager's login method, which creates the IServer session.
    authenticationSuccessHandler	This bean is responsible for actions after successful authentication. Most out-of-the-box configurations refer to the default "loginSuccessHandler" bean defined in MainConfig.xml.
    authenticationFailureHandler	This bean is responsible for actions after authentication failure. Most out-of-the-box configurations refer to the default "loginFailureHandler" bean defined in MainConfig.xml.

• Protocol-specific beans

  Some authentication modes require authentication code to interact with external SSO (SAML) or the browser (Kerberos) in accordance with certain protocols. The protocol-specific beans are responsible for handling the corresponding protocol-specific requests.

• Multi-mode support beans

  You can enable several authentication modes within one MicroStrategy Library installation. A multi-mode login page allows users to select the authentication mode they want to use. The beans responsible for multi-mode support are configured in MainConfig.xml. The two most important beans for multi-mode support are MultiModeLoginEntryPoint and MultiModeLoginFilter.

  • MultiModeLoginEntryPoint

    This bean is always activated first whenever an unauthorized request to a protected resource is detected. If the application is configured to support only one authentication mode, the MultiModeLoginEntryPoint bean simply delegates to the corresponding supported authentication mode-specific entry point. Otherwise, the MultiModeLoginEntryPoint bean checks to see if this request contains an authentication mode parameter. If so, it delegates to the corresponding authentication mode-specific entry point. Otherwise, it displays the multi-mode login page.

  • MultiModeLoginFilter

    This filter bean is activated when a user clicks one of the action buttons (Login, Integrated, SAML, Guest) on the multi-mode login page. From the button that is clicked, it determines which authentication mode is requested by the user and delegates to the corresponding authentication mode-specific filter.