JReport Server provides a working set of JSP pages and servlets that form a web application to schedule and run reports, and view results. This web application is only available to registered users who identify themselves and log in to JReport Server.
JReport Server provides an administrative function where user information is maintained. An administrator can register users with JReport Server, set passwords for them, and associate them with groups and roles. This database of user information is used to validate the user name and password that is used to log in to the web application.
Only users who have logged in to the web application and created a session can access the web pages. The session is a state that is maintained across multiple HTTP Requests using the Jave EE servlet container's service to manage the session, and pass it into the JSP and servlet with each HTTP Request.
Each JSP page and servlet in the web application starts off with code that checks if the current HTTP Request is from a user who is already logged in. If it is, the rest of the code executes because this user is a known user. There may be more permissions checks within the code to control the specific request, but the user is allowed to access the web page.
If the current HTTP Request is not from a user who is already logged in, then the code attempts to log in the user using information available in the current HTTP Request.
If it is not possible to log in a user, then the JSP code recognizes that it is an Unauthorized request and does not allow the rest of the code to execute. It may send back an Unauthorized message (HTTP 401) to the browser or may do something else depending on configuration settings.
JRepor Server provides multiple ways for a user to log into the JReport web application.
The JReport Server web pages does the login process in the order shown, but this discussion will cover them in reverse order because it is a better sequence to introduce the topics.
When there is no current user logged in to the web session, JReport Server looks for specific query parameters that it has designated as a way to pass in login credentials in the URL. This is a proprietary login protocol developed to make it easy to identify a user by passing along the login request in the URL along with the report operation request. A set of query parameters are defined that are used to pass in the login credentials for a user.
If these query parameters exist, JReport Server will use their value and try to login the identified user to the session. If the credentials are valid, then the user is logged in to the session, and the web page can be accessed. Later HTTP Requests from that user will show that the user is logged in to the session.
Details about these parameters can be found in the javadoc entry for HttpUtil.checkLogin(), which is the method that does the checking.
Here is an example URL requesting the JSP page viewVersion.jsp with credentials passed in to log in user "scott" with password "tiger".
http://localhost:8888/jinfonet/viewVersion.jsp?jrs.cmd=jrs.view_ver_def&jrs.rst_version=1&jrs.ver_suff=.pdf&jrs.report=/SampleReports/InvoiceReport.cls?jrs.auth_id=scott?jrs.auth_pwd=tiger
If no user is currently logged-in to the session, and the user "scott" with password "tiger" were a registered JReport user, then the viewVersion.jsp page would run and the user scott would become logged in to the session.
When there is no current user logged in to the web session, JReport Server looks at the HTTP Request header for the Authorization field. This is an element that follows standard HTTP protocol for HTTP Requests. Typically, it is filled in by the browser, based upon values entered by the user in a login dialog form presented by the browser when it receives a Unauthorized Request (HTTP 401) response to a URL request.
The browser responds to the Unauthorized Request response by presenting the user with the login dialog, then submitting the original URL request again (automatically), but this time with the HTTP Header having the Authorization field filled in with the user's credentials.
The browser remembers the user credentials and will send them in the HTTP Header Authorization for all subsequent requests to the same URL.
The JSP pages of JReport Server look in the HTTP Header Authorization field for user credentials and if found, will use them to validate the user. If the credentials validate a known user, that user is logged in to the web session, and the page requested by the URL runs. Later HTTP Requests from that user will show that the user is logged in.
As part of the HTTP Authentication protocol, JReport Server will respond to the browser when no user is logged in to the session. It sends back the Unauthorized Request (HTTP 401) response, expecting that the browser will gather credentials from the user and request the same HTTP Request again, with the HTTP Header now containing the Authorization field. The JSP page will see the Authorization field on the second time the request URL is sent.
HTTP Authentication is performed by this sequence of HTTP transmissions, and this processing by the server and browser.
Note: The web page security system using HTTP Authentication and URL query parameters to pass in credentials requires a secure network connection (SSL) to be effectively secure. Over a non secure network, both the HTTP Authentication and URL query technique are lightweight security systems that should not be used in a production system.
When there is no current user logged in to the web session, JReport Server will make a call to an external helper class method, asking it to return the User ID to use for the web session. If the method call returns a User ID, JReport Server will validate that the User ID is registered with JReport Server and if it is, it will log that user in.
This external helper class method is getExternalAuthorizedUser(). It is one of the methods defined in the Java interface HttpExternalAuthorized. This Java interface defines a class that developers can implement that will co-ordinate with the login protocol used by JSP pages in JReport Server as is described here.
When developers implement HttpExternalAuthorized and deploy it, it is registered with JReport Server. When this happens, it turns on what is called Single Sign On. This is a system that allows a local application to control how to log a user in, and to co-ordinate with JReport Server JSP pages so they do not enter into the HTTP Authentication dialog that would require a user to login to the system twice - once for the application and once for JReport Server.
The implementation of getExternalAuthorizedUser() can identify the user that is logged in to the application's web session and have JReport Server log that user in to the JReport Server web session automatically.
If no user is currently logged in to the application session, then the call to getExternalAuthorizedUser() will return a null. This tells JReport Server to work down the list of the other ways it has to login a user based on information in the HTTP Request. It will look in the HTTP Header, then it will look in the URL for query parameters. Eventually, if it fails to find any credentials it will recognize that the request for the web page is an Unauthorized Request.
At this point, it calls the HttpExternalAuthorized method >handleUnAuthenticatedRequst(). This method in the Java interface defines the function that can be implemented by developers to handle the case of a web page receiving an Unauthorized Request.
The implementation can generate an HTTP Response that redirects the browser to the application's login workflow and tell JReport Server to not engage in an HTTP Authentication dialog with the browser.
The explanation so far is about how login credentials are obtained to validate and login a user to the web session.
When the user name and password is obtained, JReport Server will validate if the login credentials match to a JReport Server user.
The built-in system for doing this looks at the information for the set of users that were registered with JReport Server using the administrative tasks for managing users. It validates that the password is correct for the given username based upon the information inside JReport Server's user database.
Application provides validation of user during login
JReport Server defines the AuthenticationProvider Java interface that developers can implement that will do validation that a password is correct for the given username, using the application's user database.The developers can implement an instance of the AuthenticationProvider Java interface and register it with JReport Server. Then this class and its method isValidUser() will be used to validate the user instead of using the built-in validation method.
An example of an implementation of the AuthenticationProvider Java interface is available in the sample source area in the file DemoAuthenticationProvider.java in <install_root>\help\samples\APISecurity.
Once the JSP page is deemed accessible following the rules for login and validation, the JSP page is allowed to run. The JSP page is run when an JReport user is correctly logged in to the web session. However, it may be that the logged in user does not have permission to do the requested operation or have rights for the target resource of the operation. The user may not have permission to run a report, or the user may have permission to run a report, but not the specified one in the specified catalog.
This aspect of whether the user is authorized for the request is determined by JReport Server evaluating the information in the user database that was added by an administrative task to manage users and their permissions.
Application limits actions based on permissions
JReport Server defines the AuthorizationProvider Java interface that developers can implement that will replace the built-in system for evaluating permissions and determining authorization.
The developers can implement an instance of the AuthorizationProvider Java interface and register it with JReport Server. Then this class and its methods checkPrivilege() and isPermissionOK() will be used to determine privilege instead of using the built-in authorization methods.
An example of an implementation of the AuthorizationProvider Java interface is available in the sample source area in the file DemoAuthorizationProvider.java in <install_root>\help\samples\APISecurity.
There are two folders in the sample code area of the release that can be used to learn more about web page security.
One contains a set of JSP pages that can be run to try out various styles of accessing a JSP page to see how the login dynamics works. This is the folder <install_root>\help\samples\APISecurity\LoginLogout. The entry point to the set of JSP pages is loginIndex.jsp. Read the comments in the JSP page to understand how to run the demonstration.
The other contains two implementations of HttpExternalAuthorized and a set of JSP pages that can be used to learn more about Single Sign On. This is the folder <install_root>\help\samples\APISecurity\SingleSignOn. The entry point to the set of JSP pages is customIndex.jsp. Read the comments in the java files and the JSP page to understand how to run the demonstration.