Authentication

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
HTTP Basic Authentication
The login Service
Login Encryption
The Security Check
Using an SSO Token
Using a Pre-Authentication Token
Logout

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:

HTTP Basic Authentication, where the user ID and password are sent in the header with every request. Basic authentication with REST is described in the next section.
Several login methods that, once authenticated, create a session and return a session ID that is used with subsequent requests. Use of the login service is optional, and it is useful only when HTTP Basic Authentication does not work.

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.

If a username or password contain UTF-8 characters, they may be corrupted by basic authentication and the services will always return an error. In this case, use the login service as described in The login Service.
With basic authentication, the server verifies user credentials for each API request. If your client applications perform many requests in a short time, you can avoid the overhead by using the login service or the security check and passing the session ID instead. For more information, see The Security Check.
If your client makes sporadic requests, for example running a report every hour, it is easier to use basic authentication and send the credentials in the same request.
However, sessions are kept for 20 minutes by default, so if your client makes a request every 15 minutes with the same credentials, the corresponding session will be kept in memory indefinitely. This can be a problem if you have many different clients running large reports, because some report output is stored in the user session, and they can fill up the available memory. In this case, you should use the logout call to make sure the memory is freed. For more information, see Logout.
If your server is configured with external authentication, repeatedly verifying credentials may be a performance issue you can avoid with the login service.
If your server is configured with SSO (Single Sign-On), you should use the security check method. For more information, see Using an SSO Token.
If your server is configured with Pre-Authentication, see Using a Pre-Authentication Token.

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.

In commercial editions where there is only one organization, such as in the JasperReports Server default installation, you should specify the user ID without any qualifiers, for example jasperadmin.
In commercial deployments with multiple organizations, the organization ID or organization alias must be appended to the user ID, for example jasperadmin|organization_1 or jasperadmin|org2.

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:

Method

URL

POST

GET

http://<host>:<port>/jasperserver[-pro]/rest/login/

http://<host>:<port>/jasperserver[-pro]/rest/login?<arguments>

Argument

Type/Value

Description

j_username

Text

The user ID. In commercial editions of the server that implement multiple organizations, the argument must specify the organization ID or alias in the following format: j_username%7Corganization_id (%7C is the encoding for the | character).

j_password?

Text

The user’s password. The argument is optional but authentication will fail without the password. If the server has login encryption enabled, the password must be encrypted as explained in Login Encryption.

Content-Type

Content

application/x-www-form-urlencoded

j_username=<userID>[%7C<organization_id>]&j_password=<password>

Example: j_username=jasperadmin&j_password=jasperadmin

or j_username=jasperadmin%7Corganization_1&j_password=jasperadmin

Return Value on Success

Typical Return Values on Failure

200 OK – Session ID in cookie (POST only), empty body.

401 Unauthorized – Empty body.

302 – License expired or otherwise not valid.

The login service has several uses:

POST method – Applications should use the POST method, because it returns the session cookie to use in future requests.
GET method – Developers can test the login service and the user credentials from a browser, which uses the GET method.
Credentials in arguments – When testing the login service in a browser, credentials are passed as arguments in the URL:

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

Credentials in content – When using the POST method, credentials can either be sent in the URL arguments as shown above, or sent in the content of the request, as shown in the second example below.

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.

GET /jasperserver/rest/login?j_username=jasperadmin&j_password=jasperadmin HTTP/1.1
Host: localhost:8080
User-Agent: Mozilla/5.0 (Windows NT 6.0; rv:5.0) Gecko/20100101 Firefox/5.0
Connection: keep-alive
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: No-cache
Cache-Control: no-cache
Expires: Wed, 31 Dec 1969 16:00:00 PST
Content-Length: 0
Date: Fri, 19 Aug 2011 00:52:48 GMT

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

POST /jasperserver/rest/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&j_password=jasperadmin
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=52E79BCEE51381DF32637EC69AD698AE; Path=/jasperserver
Content-Length: 0
Date: <span class="Code">Fri, 19 Aug 2011 01:52:48 GMT</span>

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:

Static key encryption – The server only uses one key that never changes. The client only needs to encrypt the password once and can use it for every REST service request.
Dynamic key encryption – The server changes the encryption key for every session. The client must request the new key and re-encrypt the password before every request using HTTP Basic Authentication or every session using the login service.

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.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/GetEncryptionKey/

Return Value on Success

Typical Return Values on Failure

200 OK – Body contains a JSON representation of public key:

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

200 OK – Body contains {Error: Key generation is off}

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.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]//j_spring_security_check?<arguments>

Argument

Type/Value

Description

orgId? Text The organization ID or alias. Required for organization admins and users when there is more than one organization defined. Not required for the system admin (superuser by default).

j_username

Text

The user ID.

j_password

Text

The user’s password. If the server has login encryption enabled, the password must be encrypted as explained in Login Encryption.

userLocale? Java locale string Set the optional locale for user in this session.
userTimezone? Java time zone Set the optional time zone for the user in this session.
Options
accept: application/json

Return Value on Success

Typical Return Values on Failure

302 Moved Temporarily – Response HTTP Header "Location" redirects to /loginsuccess.html by default, but often depends on the last session operation.

See below if you specify JSON.

302 Moved Temporarily – Response HTTP Header "Location" redirects to /login.html?error=1.

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:

{
"success":true
}

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:

<bean id="authSuccessJsonRedirectUrl" class="java.lang.String">
 
  <constructor-arg type="java.lang.String"
    value="/scripts/bower_components/js-sdk/src/common/auth/loginSuccess.json"/>
 
</bean>

Using an SSO Token

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

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]//j_spring_security_check?<arguments>

Argument

Type/Value

Description

ticket

Text

The ticket for your SSO mechanism. The default parameter name for an SSO authentication token is ticket. This parameter name can be changed in the configuration file applicationContext-externalAuth-<sso>.xml.

Options
accept: application/json

Return Value on Success

Typical Return Values on Failure

302 Moved Temporarily – Response HTTP Header "Location" redirects to /loginsuccess.html by default, but often depends on the last session operation.

302 Moved Temporarily – Response HTTP Header "Location" redirects to /login.html?error=1.

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:

GET http://localhost:8080/jasperserver-pro/j_spring_security_check?ticket=ST-40-CZeUUnGPxEqgScNbxh9l-sso-cas.eng.jaspersoft.com

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.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/?<arguments>

Argument

Type/Value

Description

pp Text The token for your pre-authentication mechanism. The default parameter name for a pre authentication token is pp. This parameter name can be changed in the configuration file .../WEB-INF/applicationContext-externalAuth-preAuth.xml.
Options
accept: application/json

Return Value on Success

Typical Return Values on Failure

302 Moved Temporarily – Response HTTP Header "Location" redirects to /loginsuccess.html by default, but often depends on the last session operation.

302 Moved Temporarily – Response HTTP Header "Location" redirects to /login.html?error=1.

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

GET http://localhost:8080/jasperserver-pro?pp=u%3DSteve%7Cr%3DExt_User%7Co%3Dorganization_1%7Cpa1%3DUSA%7Cpa2%3D1

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.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]//logout.htm

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