getFailureURL

The getFailureURL method is used to redirect the user to a custom error page in the event of an authentication or authorization failure. The string returned by this method provides the URL for the error page to be displayed.

• If a session is not alive or MicroStrategy Web cannot create a new session during the authentication work-flow, this method is called and the AUTHENTICATION_REQUEST constant is passed in as the reason. 

• If a user is not authorized to access a page, this method is called and the AUTHORIZATION_REQUEST constant is passed in as the reason. This reason will be set if the isRequestAuthorized method in the implementation of the ESM returns false.

When this method is called and either NULL or an empty string is returned, the appropriate MicroStrategy Web error page is displayed.

The following information is provided to help you use this method when you create a custom External Security Module.

• Method signature 

• Parameters 

• Return values 

• Pre-conditions 

• Post-operation

Method signature

public String getFailureURL(int reqType, ContainerServices cntSvcs)

Parameters

The following parameters are passed into the getFailureURL method:

• reqType

  This parameter indicates whether it is an authentication failure or an authorization failure.

  • AUTHENTICATION_REQUEST

    This constant is passed in if the reason for the failure is that the session is not alive or a new session cannot be created.

  • AUTHORIZATION_REQUEST

    This constant is passed in if the reason for the failure is that the user is not authorized to access the requested page.

• cntSvcs

  This parameter allows the External Security Module to directly interact with the container for tasks such as inspecting session variables and other data values associated with the incoming request.

Return Values

The getFailureURL method returns a string representing the URL of the custom error page to which the user will be directed in the event of an authentication or authorization failure. The construction of the URL is the responsibility of the External Security Module. If the return value is NULL (the default value) or an empty string, the appropriate MicroStrategy Web error page is displayed.

Pre-conditions

This call is not made with every request. It is called whenever:

• A failure is detected during authentication. 

• A failure is detected during authorization.

Post-operations

The following operations take place after the method call has finished, based on the return value:

• If this method returns a non-NULL or non-empty string, the request is redirected to the URL represented by the string. 

• If this method returns a NULL or empty string, the application displays the appropriate error page, as defined in errors.xml. The error page displayed is determined by the reason for which the getFailureURL method was called. (default)