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 | character). |
|
|
j_password? |
Text |
The user’s password. If the server has login encryption enabled, the password must be encrypted as explained in Login Encryption. The argument is optional but authentication will fail without the password. |
|
|
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
However, maintaining a session with cookies is not mandatory, and your application can use any combination of session cookie, HTTP Basic Authentication, or both.
