About Actuate JavaScript API security integration
The web service that provides reports also establishes security for a reporting web application. The actuate.initialize( ) function prompts users for authentication information if the web service requires authentication. The Actuate JavaScript API uses a secure session when a secure session already exists. Remove authentication information from the session by using actuate.logout( ).
To integrate an Actuate JavaScript API web page with an Actuate reporting web service, identify the web service from the following list:
*Deployment Kit using file-system repositories: Actuate Java Components provide web services that are secured by the application server that runs those services. These applications do not perform an authentication step initially, which enables the Actuate JavaScript API to integrate smoothly.
*Deployment Kit using a volume repository: Volumes are managed by Actuate BIRT iHub. To connect to a Deployment Kit that accesses a volume, an Actuate JavaScript API web page prompts the user for a user name and password if a secure session has not been established.
*iHub Visualization Platform client: iHub Visualization Platform client connects to a volume and requires authentication. To connect to an iHub Visualization Platform client, an Actuate JavaScript API web page prompts the user for a user name and password if a secure session has not been established. iHub Visualization Platform client provides a login page to establish the secure session.
See Using Visualization Platform security for information about customizing security for a Deployment Kit or iHub Visualization Platform client.
Establishing a secure connection to more than one web service
The actuate.initialize( ) function establishes a session with one Actuate web application service, requesting authentication from the user when the web service requires authentication. Use the actuate.authenticate( ) function for additional secure sessions with additional web services. Call actuate.initialize( ) before calling actuate.authenticate( ).
Use authenticate( ) as shown in the following code:
actuate.authenticate(serviceurl, null, userID, userpassword, null, callback, errorcallback);
*serviceurl is a URL for the Actuate web application service in use. This URL must correspond to an Actuate Deployment Kit for BIRT Reports or iHub Visualization Platform client application.
*null specifies the default settings for the RequestOptions object that is provided by the connected Actuate web application. RequestOptions sets custom or additional URL parameters for the request. To use custom or additional URL parameters, construct an actuate.RequestOptions object, assign the specific values to the object, and put the object into the custom or additional URL parameter.
*userID is the userid for authentication when loading Actuate JavaScript API resources. To force a user login, set this parameter to null.
*userpassword is the password for the userid parameter to complete authentication when loading Actuate JavaScript API resources. Use null to force the user to log in.
*null specifies no additional user credentials. This parameter holds information that supports external user credential verification mechanisms, such as LDAP. Add any required credential information with this parameter where additional security mechanisms exist for the application server upon which the web service is deployed.
*callback is a function to call after the authentication completes.
*errorcallback is a function to call when an exception occurs.
After authenticate( ) finishes, access resources from the Actuate web application service at the URL in serviceurl.
Application servers share session authentication information to enable a user to log in to one application context root and have authentication for another. For example, for Apache Tomcat, setting the crossContext parameter to "true" in the server.xml Context entries allows domains to share session information. The entries to share the authentication information from the web application with an Actuate Java Component look like the following example:
<Context path="/MyApplication" crossContext="true" />
<Context path="/ActuateJavaComponent" crossContext="true" />
Using a login servlet to connect to an Actuate web application
Actuate web applications provide a login servlet, loginservlet, that establishes a secure session with an Actuate web application service. Use the following code to use a form that calls loginservlet explicitly from a login page:
<form name="Login"
action="https://myApp/iPortal/loginservlet?" function="post">
<input type="text" name="userID" />
<input type="text" name="password" />
…
</form>
This code sets username and password variables in the session. When initialize( ) runs, the Actuate JavaScript API looks up the session map in the current HTTP session, using the service URL as the key. The Actuate JavaScript API finds the session established by login servlet and accepts the authentication for that service URL.
The login servlet authenticates the connection to an Actuate web service. Do not call the actuate.authenticate( ) function to authenticate the connection when using loginservlet.
Using a custom servlet to connect to an Actuate web application
Actuate web applications provide single-sign-on functionality to authenticate users using a custom security adapter. See Using Visualization Platform security for details on creating and using a custom security adapter matching a specific deployment scenario.
Unloading authentication information from the session
The Actuate JavaScript API keeps authentication information encrypted in the session. To remove this information from the session, use actuate.logout( ). Use logout( ) as shown in the following code:
actuate.logout( serviceurl, null, callback, errorcallback );
*serviceurl is a URL for the Actuate web application service to log out from. This URL must correspond to an Actuate Deployment Kit for BIRT Reports or iHub Visualization Platform client application.
*null specifies the default settings for RequestOptions that are provided by the connected Actuate web application. RequestOptions sets custom or additional URL parameters for the request. To use custom or additional URL parameters, construct an actuate.RequestOptions object, assign the specific values to the object, and put the object into the custom or additional URL parameter.
*callback is a function to call after logout( ) completes.
*errorcallback is a function to call when an exception occurs.
After logout( ) finishes, the authentication for the serviceurl is removed. Authenticate again to establish a secure connection.