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 |
| • | Argument-based Authentication |
| • | The login Service |
| • | Login Encryption (Deprecated) |
| • | 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:
| • | Stateless authentication – Your client sends user credentials with every API request. This is the traditional RESTful behavior and fully supported by JasperReports Server. Clients may send credentials using HTTP Basic Authentication, where the user ID and password are sent in the header with every request, or argument-based authentication, where the user ID and password are included in URL arguments. |
| • | User session management – Your client performs a login operation first, and then sends a session cookie with every API request. As with a user interface, your client performs a logout operation when done. Use of the login and logout services is optional, but it can improve performance under heavy user loads. |
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.
| • | If your client makes sporadic requests, for example running a report every hour, it is easier to use basic authentication and send the credentials with each request. See HTTP Basic Authentication. |
| • | If a username or password contains UTF-8 characters, it may be corrupted by basic authentication and the services will always return an error. In this case, you can send the username and password in URL arguments with each request. See Argument-based Authentication. |
| • | If your client applications perform many requests in a short time, you can avoid the overhead of stateless authentication by using the login service once and passing the session ID cookie instead with each request. For more information, see The login Service. |
| • | 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. |
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:
| • | Use locale and time zone arguments on any REST API to specify the language and time in the response, for example to localize a report. It is also possible for the same user to make several requests with different locales or time zones. Once you specify a locale or time zone for a given user, the server sets a cookie so that it applies to all requests. See Argument-based Authentication. |
| • | When doing many requests with the same locale and time zone, you can also specify the locale and time zone arguments with the login service. The language and time will be set with a cookie for all future requests. See The login Service. |
| • | If you never specify any locale or time zone arguments, the default locale and default time zone on the server will be used for all operations. |
In the case of external authentication, how you perform REST authentication depends on the type of mechanism:
| • | If your server is configured with an external authentication that requires a username and password, such as LDAP, then you can use any authentication method that submits those values: HTTP basic authentication, argument-based authentication, or the login service with credentials in arguments or the request body. However, repeatedly verifying external credentials may cause a performance issue, in which case you should use the login service and the session cookie it returns. |
| • | If your server is configured with SSO (Single Sign-On), use the updated v2 login service to send the token. For more information, see The login Service. |
| • | If your server is configured with Pre-Authentication, specify the pp argument in every API request, as shown in Argument-based Authentication. |
None of these authentication methods provide privacy, meaning that passwords are sent in plain text or easily reversed encodings. Tibco 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.
| • | 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. When the organization ID or alias is added to an argument in the URL, you should use the encoded form: jasperadmin%7Corganization_1 |
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:
| Method | URL | ||
| any | http://<host>:<port>/jasperserver[-pro]/rest_v2/<service/and/path>[?<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: userID%7CorgID (%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 (Deprecated).
pp TextThe 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.
userLocale Java locale string An optional argument to set the locale for this user. The locale can affect both server strings such as messages and report content if localized by Domains. The server sets a cookie with this value so that it is used in every subsequent request until changed. If this argument is never specified for a given user, the server's default locale is used. Specify a Java locale string such as fr (French) or de (German). userTimezone Java time zone An optional argument to set the time zone for this user. The server sets a cookie with this value so that it is used in every subsequent request until changed. If this argument is never specified for a given user, the server's default time zone is used. The time zone names are those supported by java.time.ZoneID, which are defined in the tz database.
Return Value on Success
Typical Return Values on Failure
The normal response for the requested operation.
401 Unauthorized – Login failed or j_username or j_password was missing, body of response is empty.
403 Forbidden – License expired or otherwise not valid.
For example, the following request will return all repository resources in the Public folder that the sample user Joeuser has permission to read:
When using pre-authentication on the server, specify only the pp arugument, for example (%3D is the encoding for =, and %7C for |):
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 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:
• Login with username and password in the URL arguments. • Login with username and password in the request body. • Login with a ticket for servers configured for single sign-on (SSO).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 Tibco 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).
Method
URL
POST
GET (config.)
http://<host>:<port>/jasperserver[-pro]/rest_v2/login[?<arguments>]
http://<host>:<port>/jasperserver[-pro]/rest_v2/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%7CorgID (%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 (Deprecated).
ticket
Text
The user's ticket for your SSO mechanism, when enabled. This argument is not valid when j_username and j_password are specified. For example:
ticket=ST-40-CZeUUnGPxEqgScNbxh9l-sso-cas.example.com
The default parameter name for an SSO authentication token is ticket. This parameter name can be changed in the configuration file WEB-INF/applicationContext-externalAuth-<sso>.xml.
userLocale Java locale string An optional argument to set the locale for this user session. The locale can affect both server strings such as messages and report content if localized by Domains. The server sets a cookie with this value so that it is used in every subsequent request until changed. When omitted, the server's default locale is used during this session. Specify a Java locale string such as fr (French) or de (German). userTimezone Java time zone An optional argument to set the time zone for this user. The server sets a cookie with this value so that it is used in every subsequent request until changed. When omitted, the server's default time zone is used during this session. The time zone names are those supported by java.time.ZoneID, which are defined in the tz database.
Content-Type
Content
application/x-www-form-urlencoded
j_username=<userID>[%7C<organizationID>]&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, body of response is empty.
400 Bad Request – Missing j_username or j_password.
401 Unauthorized – Login failed, body of response is empty.
403 Forbidden – License expired or otherwise not valid.
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:
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:
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:
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:
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:
• 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 request. The client must request the new key and re-encrypt the password before every request using HTTP Basic Authentication including 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:
200 OK – Body contains {Error: Key generation is off}
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.
Method
URL
GET
http://<host>:<port>/jasperserver[-pro]/logout.html
Header Cookie: $Version=0; JSESSIONID=52E79BCEE51381DF32637EC69AD698AE; $Path=/jasperserver
Recommended Comments
There are no comments to display.