Authentication Methods

This chapter demonstrates several ways for REST client applications to authenticate with JasperReports Server. Choose an authentication method that matches the usage patterns and needs of your REST client application.

This chapter includes the following sections:

Overview of REST Authentication

When using the REST API, the client application must provide a valid user ID and password to JasperReports Server. The REST services support two types of authentication:

Normally, RESTful implementations do not rely on the persistent user sessions, such as the login service and user sessions stored on the server. However, the JasperReports Server architecture automatically creates user sessions internally, and the login method takes advantage of this. There are several use cases for either type of authentication.

As with logging in from the web UI, you can send a user-specific locale and time zone during REST API authentication. To specify a locale and timezone, choose from the following possibilities:

In the case of external authentication, how you perform REST authentication depends on the type of mechanism:

None of these authentication methods provide privacy, meaning that passwords are sent in plain text or easily reversed encodings. Jaspersoft recommends that you configure your server and clients to use HTTPS to provide end-to-end privacy and security. Alternatively, JasperReports Server has a login encryption feature that hides passwords. If this feature is enabled on your server, you must encrypt your passwords before sending them in REST requests. For more information, see Login Encryption (Deprecated).

HTTP Basic Authentication

HTTP basic authentication is stateless, meaning that your client application must supply a valid user and password in every API request. The user ID and password are concatenated with a colon (:) and Base64-encoded in the HTTP request header. Usually, your client library does this for you. For example, the default organization admin’s credentials are jasperadmin:jasperadmin, which is encoded as follows:

Authorization: Basic amFzcGVyYWRtaW46amFzcGVyYWRtaW4=

The REST API services accept the same accounts and credentials as the JasperReports Server user interface.

When your server implements external authentication, such as using LDAP, you can submit the username and password with HTTP basic authentication as well.

If login encryption in enabled in your server, you must encrypt the password before base64-encoding it with the username. For more information about encryption, see Login Encryption (Deprecated).

Argument-based Authentication

Some UTF-8 characters in usernames and passwords are not properly handled by the encoding in HTTP basic authentication, and such requests will return an error. To get around this, all services of the REST API accept arguments for the username and password in the URL. This method also works when your server is configured to check username and passwords with external authentication, for example using LDAP. All services also recognize the pp argument that you use when your server is configured for pre-authentication.

Use the following arguments as an alternate method to send user credentials in a stateless manner with each API request:

For example, the following request will return all repository resources in the Public folder that the sample user Joeuser has permission to read:

http[s]://<host>:<port>/jasperserver[-pro]/rest_v2/resources/Public?j_username=joeuser%7Corganization_1&j_password=<password>

When using pre-authentication on the server, specify only the pp arugument, for example (%3D is the encoding for =, and %7C for |):

http[s]://<host>:<port>/jasperserver[-pro]/rest_v2/resources/Public?pp=u%3Djoeuser
%7Cr%3DUSER,SALES%7Co%3DHeadquarters%7Cpa1%3DUSA%7Cpa2%3DLosAngeles

Even if you implement HTTPS, you should be aware that plain-text passwords in URLs may appear in your app server's logs, and you should protect such log files. To prevent this security issue, change your logging rules or implement login encryption as described in Login Encryption (Deprecated).

The login Service

The login service allows your client to send user credentials to the server, verify the credentials, and receive a session cookie. By explicitly creating and maintaining a user session, your client can manage the user session and optimize the resources it uses. For more information, see Overview of REST Authentication.

As of JasperReports Server 8.2, reports executions and Input Controls are no longer session dependent. The new behavior is as follows:

In case at step 3, if the user logs out, then the associated cache will be cleared; furthermore, the user at step 5 won't see the results.

As of JasperReports Server 7.1, the REST v1 login service (rest/login) was deprecated and removed from the API. It is replaced with the similar REST v2 login service (rest_v2/login). This section documents the use of the new rest_v2/login API.

The rest_v2/login service allows REST clients to submit authentication credentials in several ways and receive a server cookie that can be used to identify the user session in subsequent API operations. The supported authentication methods are:

When external authentication such as LDAP is configured in the server, clients are still required to submit the username and password in one of the first two methods above.

Sending passwords in plain text is strongly discouraged, therefore Jaspersoft recommends that you configure your server and clients to use HTTPS, or that you use the login encryption feature. For more information, see Login Encryption (Deprecated).

Because browsers submit URLs with the GET method, you can test the login service and test credentials by submitting requests from a web browser. With developer tools in your browser, you can see the server's response, and when successful, the session cookie it contains. Credentials must be passed as arguments in the URL, as shown in the following example:

http[s]://<host>:<port>/jasperserver[-pro]/rest_v2/login?j_username=<userID>[%7C<orgID>]&
j_password=<password>

Client applications typically use the POST method, and they gather the session cookie from the response to use in future requests. Credentials can be sent either in the URL arguments, as shown above, or in the content of the request, as shown in the following example:

POST /jasperserver/rest_v2/login HTTP/1.1
User-Agent: Jakarta Commons-HttpClient/3.1
Host: localhost:8080
Content-Length: 45
Content-Type: application/x-www-form-urlencoded
j_username=jasperadmin%7Corganization_1&j_password=jasperadmin

When the login is successful, the server sends the "200 OK" response containing a cookie for the session ID of the now-logged-in user:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=52E79BCEE51381DF32637EC69AD698AE; Path=/jasperserver
Content-Length: 0
Date: Fri, 3 Aug 2018 01:52:48 GMT

For optimal performance, the session ID from the cookie should be used to keep the session open. Usually, your REST library will automatically include the cookie in future requests to the other RESTful services. For example, given the response to the POST request above, future requests to the repository services should include the following line in the header:

Cookie: $Version=0; JSESSIONID=52E79BCEE51381DF32637EC69AD698AE; $Path=/jasperserver

By default, the session timeout on the server is 20 minutes of inactivity. Beyond that time, requests using the session cookie will fail due to lack of authentication. Your client will need to authenticate again using any of the methods described in this chapter.

Maintaining a session with cookies is not mandatory, and your application can use any combination of session cookie, stateless authentication, or both. However, if you use the session ID, it is good practice to close the session as described in Logout. Closing the session frees up any associated resources in memory.

Login Encryption (Deprecated)

As of release 7.5, the HTTP parameter encryption described in this section is deprecated. This feature is no longer supported because the Javascript libraries it uses are no longer supported. Jaspersoft recommends using TLS (Transport Level Security) to implement HTTPS and secure communication between your users and the server.

JasperReports Server supports the ability to encrypt plain-text passwords over non-secure HTTP. Encryption does not make passwords more secure, it only prevents them from being readable to humans. For more information about security and how to enable login encryption, see the JasperReports Server Security Guide.

When login encryption is enabled, passwords in both HTTP Basic Authentication and using the login service must be encrypted by the client. Login encryption has two modes:

The GetEncryptionKey service does not take any arguments or content input.

{
  "maxdigits":"131",
  "e":"10001",
  "n":"9f8a2dc4baa260a5835fa33ef94c..."
}

After using this service to obtain the server’s public key, your client must encrypt the user's password with the public key using the Bouncy Castle library and the RSA/NONE/NoPadding algorithm. Then your client can send the encrypted password in simple authentication or using the login service.

Logout

While REST calls are often stateless, JasperReports Server uses a session to hold some information such as generated reports. The session and its report data take up space in memory and it's good practice to explicitly close the session when it is no longer needed. This allows the server to free up and reuse resources much faster.

To close a session and free its resources, invoke the logout page. The request must include the JSESSIONID cookie, which your REST client libraries should do automatically.