public interface

ExternalSecurity

com.microstrategy.web.app.ExternalSecurity
Known Indirect Subclasses

Class Overview

Title: ExternalSecurity.

Description: Out of the box, the Web Universal application provides its own built-in login page. For customers wishing to integrate Web Universal into a portal, they may opt to redirect the request to another custom login page. Finally, if an Intelligence Server session has already been established, then customers may want that existing session to be reused.
Prior to Web Universal, the existing form of security customization was offered through the Security Plug-in concept. In this approach, credentials were still collected through the MicroStrategy Login page, however, the external security agent had the ability to interpret these values in arbitrary ways. That is, instead of referring to an Intelligence Server user, the customer could interpret the user name supplied as a key into an employee database. The security plug-in was responsible for mapping these credentials to valid Intelligence Server user credentials. This form of security optimization is offered through the ExternalSecurity interface.
The other form of security enforcement is Authorization. This refers to the process of checking the validity of each individual request. In the context of the MicroStrategy Web application, this means checking whether a given user may proceed with a specific HTTP request.
ExternalSecurity is based on the notion of a single programming interface that is implemented by the client. Clients codify their security policies into an object (or set of objects) that implements this public interface. This interface represents the pact between the Web Universal application and the external security agent.

Summary

Constants
int AUTHENTICATION_REQUEST Indicates the request type was for authentication
int AUTHORIZATION_REQUEST Indicates the request type was for authorization
int COLLECT_SESSION_NOW Value that the handlesAuthenticationRequest() method might return if the session should be handled by ExternalSecurity methods
int INVALID_CREDENTIALS Reason why the handlesAuthenticationRequest() should be called: the session that was aviailable for use has wrong credential information
int LOGIN_FIRST Reason why the handlesAuthenticationRequest() should be called: There is no login first session or the login first session is invalid.
int MISMATCHED_PREFERENCES Reason why the Web ask for reconnect session.
int NO_SESSION_FOUND Reason why the handlesAuthenticationRequest() should be called: there was no session available for the application to use
int SESSION_CLOSED Reason why the handlesAuthenticationRequest() should be called: the session that was available for use has expired
int USE_CUSTOM_LOGIN_PAGE Value that the handlesAuthenticationRequest() method might return if the session should be prepared first by a custom login page specified by the ExternalSecurity component
int USE_MSTR_DEFAULT_LOGIN Value that the handlesAuthenticationRequest() method might return if the session should be handled by Web Universal
Public Methods
abstract boolean canReconnectSession(ContainerServices cntSvcs, WebIServerSession currentSession, int reason)
This method will be called each time Microstrategy Web tries to automatically reconnect a session that is still valid.
abstract boolean closeSessionOnLogout(RequestKeys reqKeys, ContainerServices cntSvcs, WebIServerSession user)
Method to be called when the user or system invokes a logout event.
abstract String getCustomLoginURL(String originalURL, String desiredServer, int desiredPort, String desiredProject)
Returns the URL of a custom page that will handle the authentication request, in case the handlesAuthenticationRequest() method returned USE_CUSTOM_LOGIN_PAGE
abstract String getFailureURL(int reqType, ContainerServices cntrSvcs)
Once it has been determined the request has failed, this method will provide the URL information where the user should be taken next.
abstract WebIServerSession getWebIServerSession(RequestKeys reqKeys, ContainerServices cntSvcs)
Create a new session object based on the information provided.
abstract int handlesAuthenticationRequest(RequestKeys reqKeys, ContainerServices cntSvcs, int reason)
Indicates how ExternalSecurity wants to handle the session (authentication) request
abstract boolean isRequestAuthorized(RequestKeys reqKeys, ContainerServices cntSvcs, WebIServerSession user)
Determines if the user is authorized to perform the incoming request
abstract boolean processMSTRLoginForm(RequestKeys reqKeys, ContainerServices cntrSvcs, LoginForm loginForm, int reason)
Manipulates the already created WebIServerSession instance and modifies it if required

Constants

public static final int AUTHENTICATION_REQUEST

Indicates the request type was for authentication

Constant Value: 1 (0x00000001)

public static final int AUTHORIZATION_REQUEST

Indicates the request type was for authorization

Constant Value: 2 (0x00000002)

public static final int COLLECT_SESSION_NOW

Value that the handlesAuthenticationRequest() method might return if the session should be handled by ExternalSecurity methods

Constant Value: 2 (0x00000002)

public static final int INVALID_CREDENTIALS

Reason why the handlesAuthenticationRequest() should be called: the session that was aviailable for use has wrong credential information

Constant Value: 3 (0x00000003)

public static final int LOGIN_FIRST

Reason why the handlesAuthenticationRequest() should be called: There is no login first session or the login first session is invalid.

Constant Value: 4 (0x00000004)

public static final int MISMATCHED_PREFERENCES

Reason why the Web ask for reconnect session.

Constant Value: 1 (0x00000001)

public static final int NO_SESSION_FOUND

Reason why the handlesAuthenticationRequest() should be called: there was no session available for the application to use

Constant Value: 1 (0x00000001)

public static final int SESSION_CLOSED

Reason why the handlesAuthenticationRequest() should be called: the session that was available for use has expired

Constant Value: 2 (0x00000002)

public static final int USE_CUSTOM_LOGIN_PAGE

Value that the handlesAuthenticationRequest() method might return if the session should be prepared first by a custom login page specified by the ExternalSecurity component

Constant Value: 3 (0x00000003)

public static final int USE_MSTR_DEFAULT_LOGIN

Value that the handlesAuthenticationRequest() method might return if the session should be handled by Web Universal

Constant Value: 1 (0x00000001)

Public Methods

public abstract boolean canReconnectSession (ContainerServices cntSvcs, WebIServerSession currentSession, int reason)

This method will be called each time Microstrategy Web tries to automatically reconnect a session that is still valid. At this point, it is always related to user preferences not matching the session values. There are certain user preferences that need to be applied at the time the session is created, namely:

  • Number and Date Locale
  • Session flags (cancel or remove pending jobs on logout)
Since user preferences are saved in the Metadata, the values provided when the session is created are "guessed" by Web or the ESM. After creating a session these values are compared with the actual Preferences values. If they do not match and there is enough information in the session to be able to reconnect, Web will invoke this method to confirm that the session can be reconnected with the correct preferences values. This method gets invoked even if the handlesAuthenticationRequest method returns COLLECT_SESSION_NOW, so customers implementing an ESM that creates a session need not to worry about applying user preferences themselves. This method is also invoked when a user changes one of these preferences through the application and the "Enable seamless login" setting is on.

Parameters
cntSvcs a ContainerServices valid instance
currentSession the WebIServerSession instance representing the current opened session.
reason The reason this method is called. Currently, there is only one reason MISMATCHED_PREFERENCES
Returns
  • If the ESM returns false, the session will not be reconnected and user-preferences will be used as-is.

public abstract boolean closeSessionOnLogout (RequestKeys reqKeys, ContainerServices cntSvcs, WebIServerSession user)

Method to be called when the user or system invokes a logout event. This method can also be used to perform any custom operations when the user is logged out and before the session is closed.

Parameters
reqKeys a RequestKeys valid instance
cntSvcs a ContainerServices valid instance
user the WebIServerSession instance representing the current opened session being used for the user request and the one from which the user is about to be logged out.
Returns
  • a boolean value indicating if the session should be disconnected from the IServer and project or not.

public abstract String getCustomLoginURL (String originalURL, String desiredServer, int desiredPort, String desiredProject)

Returns the URL of a custom page that will handle the authentication request, in case the handlesAuthenticationRequest() method returned USE_CUSTOM_LOGIN_PAGE

Parameters
originalURL the original url that was being called when the authentication request came up
desiredServer the server where the user requests to be logged to
desiredPort the port where the user requests to be logged to
desiredProject the project where the user requests to be logged to
Returns
  • a String value with the url where the use should be redirected to

public abstract String getFailureURL (int reqType, ContainerServices cntrSvcs)

Once it has been determined the request has failed, this method will provide the URL information where the user should be taken next.

Parameters
reqType an int value indicating which request was the one that failed: AUTHENTICATION_REQUEST or AUTHORIZATION_REQUEST
cntrSvcs ContainerServices initialized instance
Returns
  • a String with the URL to use for redirecting the user.

public abstract WebIServerSession getWebIServerSession (RequestKeys reqKeys, ContainerServices cntSvcs)

Create a new session object based on the information provided.

Parameters
reqKeys a RequestKeys valid instance
cntSvcs a ContainerServices valid instance
Returns

public abstract int handlesAuthenticationRequest (RequestKeys reqKeys, ContainerServices cntSvcs, int reason)

Indicates how ExternalSecurity wants to handle the session (authentication) request

Parameters
reqKeys a RequestKeys valid instance
cntSvcs a ContainerServices valid instance
reason an int value representing the reason why session handling is required
Returns
  • an int value indicating how the session handling should be processed

public abstract boolean isRequestAuthorized (RequestKeys reqKeys, ContainerServices cntSvcs, WebIServerSession user)

Determines if the user is authorized to perform the incoming request

Parameters
reqKeys a RequestKeys valid instance
cntSvcs a ContainerServices valid instance
user the WebIServerSession instance representing the current opened session being used for the user request
Returns
  • true if the request is authorized. Otherwise, returns false

public abstract boolean processMSTRLoginForm (RequestKeys reqKeys, ContainerServices cntrSvcs, LoginForm loginForm, int reason)

Manipulates the already created WebIServerSession instance and modifies it if required

Parameters
reqKeys a RequestKeys valid instance
cntrSvcs a ContainerServices valid instance
loginForm a LoginForm instance with the information used for generating the session by the application
reason int value indicating why this session instance was created
Returns
  • True if the login was successfully processed - session to use will be available with the getWebIServerSession() method on this instance - or False if it failed.