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 use of persistent 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 methods take advantage of this. There are several use cases for either type of authentication.

HTTP Basic Authentication

In HTTP basic authentication, the client application must supply a valid user and password in every service 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 web services accept the same accounts and credentials as the JasperReports Server user interface.

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.

The login Service

When making a login request, the user ID and password can be pass as URL arguments or as content in the request body:

The login service has several uses:

http://<host>:<port>/jasperserver[-pro]/rest/login?j_username=<userID>[%7C<organization_id>]

&j_password=<password>

The following example shows the HTTP request and response when testing the login service in a browser. In this case, the user credentials are passed as arguments and the browser sends a GET request. Because the GET request is meant only for testing, it does not return a cookie with the session ID.

The following example shows the content of a POST request where the credentials are passed in the content.

For optimal performance, the session ID from the cookie should be used to keep the session open. To do this, 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

Maintaining a session with cookies is not mandatory, and your application can use any combination of session cookie, HTTP Basic 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

JasperReports Server 4.7 introduced 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:

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.

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

The Security Check

The security check request is equivalent to a login request. You send the user credentials and you can tell from the response whether they are valid or not on the server. If they are valid, the server creates a user session or if the user has already performed an operation with valid credentials, it accesses the existing user session.

In either case, the successful response contains the JSESSIONID cookie of the user session. As with the login service, once you receive the session cookie, you should return it with future requests and use it to close the session as described in Logout.

If you specify accept: application/json in your request, the location of the redirect in case of success is always the file /scripts/bower_components/js-sdk/src/common/auth/loginSuccess.json. The content of this file is:

You can configure the location of this file. Edit the configuration file .../WEB-INF/applicationContext-security-web.xml and change the constructor value of the following bean:

Using an SSO Token

If you are using Single Sign-On for authentication, you can use the security check to submit the ticket.

For example, if you have configured the server to use CAS as your SSO provider, you can authenticate and receive the session ID with the following request:

The response has the same behavior as the password-based security check, including the use of a JSON file if requested.

Using a Pre-Authentication Token

When using a pre-authentication mechanism, the verification of the credentials is performed at the base URL of the server.

For example, if you have configured the server to use pre-authentication, you can authenticate and receive the session ID with the following request:

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 and include the JSESSIONID cookie in the request.