Introduction

This is the API documentation of Spring Lemon Demo application. This API can be called from browser based front-ends (e.g. AngularJS single page applications), as well as non-browser clients.

Basics

Before we dive in, let’s first look at a few key thing to keep in mind when using the API.

CORS

Your API could be accessed from multiple clients. One of those could be a JavaScript web front-end, such as an AngularJS single page application.

When developing a JavaScript web front-end, you will have two choices:

  1. Put it in the same project, say inside src/main/resources/static, and deploy both the server and the client as a single unit.

  2. Keep it separate, say as a Grunt project, and deploy it in a different domain. For example, your API could be hosted at example.cfapps.io, whereas your AngularJS application could be hosted at www.example.com.

If you go for the second option, your JavaScript can’t call your API unless you deal with the same origin policy.

Spring Lemon uses CORS at the server side to deal with this. You just have to add a line like this in application.properties:

lemon.cors.allowed-origins: http://localhost:9000,http://www.example.com

You may also need a little configuration at the client side. For example, in AngularJS, you will need to set the withCredentials flag of $http service, like this:

angular.module('myApp', ['ngCookies', ... ])
.config(['$httpProvider', function ($httpProvider) {

    $httpProvider.defaults.withCredentials = true;
    ...
}]);

Refer documentation and resources for more details.

CSRF

CSRF is a well known security vulnerability. If you do not know about it, Spring Security reference material explains it beautifully.

To handle CSRF, Spring Lemon sends a token to the client in each response. The token is sent as a cookie, named XSRF-TOKEN. Then, in each PATCH, POST, PUT or DELETE request, it expects the same token as a header named X-XSRF-TOKEN. An exception is thrown if the tokens do not match.

So, your client application should first send a GET request for getting the token, and then use that in POST kind of requests. Also, be aware that Spring Security removes or changes the cookie after certain events, like logout. Hence, after these events, your client application will again need to send some GET request and get the new token. Ping (see below) can be used for this.

When wrong CSRF token is sent, the response looks like this:

HTTP/1.1 403 Forbidden

{
"status": 403,
"error": "Forbidden",
"message": "Expected CSRF token not found. Has your session expired?",
"path": "/accessed_url"
}

Refer documentation and resources for more details.

CSRF and AngularJS

If your AngularJS client resides in the same project, say inside src/main/resources/static, you don’t have to do anything special for CSRF. When sending a request, the $http service of AngularJS automatically puts the value of the XSRF-TOKEN cookie in a header named X-XSRF-TOKEN.

If you have the client as a separate project that is to be hosted separately though, you will have to add the header on your own. The easiest way to do it is to write an AngularJS $http interceptor, like this:

angular.module('myApp')
  .factory('XSRFInterceptor', function ($cookies, $log) {

    var xsrfToken;

    var XSRFInterceptor = {

      request: function(config) {

        if (xsrfToken) {
          config.headers['X-XSRF-TOKEN'] = xsrfToken;
          $log.info("X-XSRF-TOKEN being sent to server: " + xsrfToken);
        }

        return config;
      },

      response: function(response) {

        var newToken = $cookies.get('XSRF-TOKEN');

        if (newToken) {
          xsrfToken = newToken;
          $log.info("XSRF-TOKEN received from server: " + xsrfToken);
        }

        return response;
      }
    };

    return XSRFInterceptor;
  });

You then need to configure the interceptor as below.

angular.module('myApp', [...])
   .config(['$httpProvider', function ($httpProvider) {

   $httpProvider.defaults.withCredentials = true;
   $httpProvider.interceptors.push('XSRFInterceptor');
   ...

}]);

Handling Errors

If some request data would not comply to the business rules, the API would respond with 422 Unprocessable Entity, with a JSON body holding field-wise error details. For example, trying to sign up with some invalid data could produce the following JSON data:

{
  "timestamp": 1494764056076,
  "status": 422,
  "error": "Unprocessable Entity",
  "exception": "javax.validation.ConstraintViolationException",
  "message": "Validation Error",
  "path": "/api/core/users",
  "errors": [
    {
      "field": "user.password",
      "code": "{com.naturalprogrammer.spring.invalid.password.size}",
      "message": "Password must be between 6 and 50 characters"
    }
  ]
}

Each error in errors above will have three fields:

  1. field: Name of the field, or null in case of a form level error.

  2. code: The error code.

  3. message: An internationalized message, which could vary depending on the locale of the user.

Format of the error data

Obviously, the format of the error JSON, its field names and codes would vary from request to request. Maintaining a documentation of each error for each request would be cumbersome. We may take that up sometime in future, but for now, the best way to know the format for any request would be to look at the actual response body by using a tool, such as the google chrome developer tools or Postman.

JSON vulnerability

By default, Spring Lemon prefixes JSON responses with )]}',\n. This is done as a protection against the JSON vulnerability. Your client application would need to strip this )]}',\n. It’s done automatically if you are using the $http service of AngularJS.

If you want to disable this protection, maybe because your API is not meant to be called from browsers, add the following line in application.properties:

lemon.enabled.json-prefix: false

Common terms

Some terms that we would be using often in the documentation are given below.

ADMIN

A user having "ADMIN" in his roles collection.

Unverified user

A user having "UNVERIFIED" in his roles collection.

Blocked user

A user having "BLOCKED" in his roles collection.

Bad user

An unverified or blocked user.

Good user

A user who is not bad.

Bad ADMIN

An ADMIN who is a bad user.

Good ADMIN

An ADMIN who is a good user.

Common Business Rules

This section documents the common business rules, which are referred from multiple places in the API documentation.

Accessing Users

Who is permitted to edit a User entity

Editing the fields

A user can be edited either by himself or a good ADMIN.

Adding or removing roles

  1. roles can only be edited by good ADMINs.

  2. A user can’t edit his own roles even if he is a good ADMIN.

Confidential fields

When fetching a user (either by email or id), . createdDate, lastModifiedDate, password, verificationCode and forgotPasswordCode are not returned. . email and username are not returned if the logged in user does not have right to edit the fields (see above) of the user being fetched.

User entity validation constraints

email

  1. Should not be null

  2. Should not be blank

  3. Should be between 4 and 250 characters long

  4. Should be well-formed email format

  5. Should be unique

password

  1. Should not be null

  2. Should not be blank

  3. Should be between 4 and 30 characters long

name

  1. Should not be blank

  2. Should be between 1 and 50 characters long

Data structure

This section documents some data structures used in the application.

User data

Fetch user by email or id returns data about a user. The data looks like this:

{
    "id": 24,
    "version": 5,
    "email": "admin@example.com",
    "roles": [
        "ADMIN"
    ],
    "unverified": false,
    "blocked": false,
    "admin": true,
    "goodUser": true,
    "goodAdmin": true,
    "editable": true,
    "rolesEditable": false,
    "name": "Administrator",
    "username": "admin@example.com",
    "authorities": [
        {
            "authority": "ROLE_ADMIN"
        },
        {
            "authority": "ROLE_GOOD_ADMIN"
        },
        {
            "authority": "ROLE_GOOD_USER"
        }
    ]
}

Note that the fields that the logged in user wouldn’t have rights to view would be omitted. Refer the documentation and resources for more details.

Ping

Sends a GET request to the server. This is useful for fetching the CSRF cookie after an event that would have changed the CSRF token, e.g. logout. See the discussion on CSRF above for more details.

In summary, you may need to call this before any request that results in CSRF mismatch error.

Request

GET /api/core/ping HTTP/1.1
Accept: */*
Host: www.example.com

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=a5aaae27-731c-46eb-a2d6-b36c5fd77057; Path=/
Date: Sun, 21 May 2017 15:55:24 GMT

Notice how we get the CSRF cookie in the response, which is to be sent as a header in next requests.

Business rules

  1. Should return a 204 No Content with a cookie named "XSRF-TOKEN"

Positive test cases

  1. Should return a 204 No Content with a cookie named "XSRF-TOKEN"

Ping and create session

From a browser based client, you may like to create a session so that you can use cookie based authentication. To do so, call this.

Request

GET /api/core/ping-session HTTP/1.1
Accept: */*
Host: www.example.com

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=03125b3f-d04d-42fd-b3e6-80757bff5080; Path=/
Set-Cookie: JSESSIONID=CF6D03825A4F815F9D1357CF92385C61; Path=/; HttpOnly
Date: Sun, 21 May 2017 15:55:23 GMT

Notice the classic JSESSIONID cookie in the response.

Business rules

  1. Should return a 204 No Content with a cookie named "JSESSIONID"

Positive test cases

  1. Should return a 204 No Content with a cookie named "JSESSIONID"

Get context

Gets useful application properties and current user data.

Tip
 Call this to fetch useful application properties and current-user data when an AngularJS application starts.

Request

GET /api/core/context HTTP/1.1
Accept: application/json;charset=UTF-8
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=d74c6a5c-4d12-413e-83d7-58477e21d5c4; Path=/
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:24 GMT
Content-Length: 733

{
  "context" : {
    "shared" : {
      "fooBar" : "123..."
    }
  },
  "user" : {
    "id" : 12,
    "email" : "admin@example.com",
    "roles" : [ "ADMIN" ],
    "unverified" : false,
    "blocked" : false,
    "admin" : true,
    "goodUser" : true,
    "goodAdmin" : true,
    "editable" : true,
    "rolesEditable" : false,
    "authorities" : [ {
      "authority" : "ROLE_ADMIN"
    }, {
      "authority" : "ROLE_GOOD_USER"
    }, {
      "authority" : "ROLE_GOOD_ADMIN"
    } ],
    "name" : "Administrator",
    "accountNonExpired" : true,
    "accountNonLocked" : true,
    "credentialsNonExpired" : true,
    "username" : "admin@example.com",
    "enabled" : true,
    "new" : false
  }
}

Fields

Path Type Description

context

Object

Context object containing attributes like reCaptchaSiteKey

context.shared

Object

All the lemon.shared.* properties that are defined in application\*.yml

user

Object

Logged-in user details

user would be omitted if nobody is logged in.

Refer documentation and resources to know how to customize this response and other details.

Business rules

The current-user data, reCaptchaSiteKey, and the lemon.shared.* properties should be there in the response. Current-user data shouldn’t include any confidential fields.

Positive test cases

  1. When not logged in, reCaptchaSiteKey, lemon.shared.* properties should be there in the response. Current user data should be absent.

  2. When logged in, reCaptchaSiteKey, lemon.shared.* properties should be there in the response. Current user data should look as above, with confidential fields omitted..

Login

Logs the user in. To remember the user for 15 days, send a rememberMe parameter set as true.

Request

POST /login HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 2de4bf75-df0e-472b-8aa5-6131970d4b8f
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

username=admin%40example.com&password=admin%21&rememberMe=true

Parameters

Parameter Description

username

The login id

password

Password

rememberMe

Whether to remember the login even after session expires

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=6A1271909C372A891F59F1CF20C44D79; Path=/; HttpOnly
Set-Cookie: XSRF-TOKEN=; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/
Set-Cookie: XSRF-TOKEN=14d619d3-9816-4faa-b2ac-0c0b8bcc9a38; Path=/
Set-Cookie: rememberMe=YWRtaW5AZXhhbXBsZS5jb206MTQ5NjU5MTcyMjU1NjphN2I1YzczYTExYjk2ZDNmM2EwNDA2ZTc1NjdkOWEwNA; Max-Age=1209600; Expires=Sun, 04-Jun-2017 15:55:22 GMT; Path=/; HttpOnly
Content-Type: application/json
Content-Length: 590
Date: Sun, 21 May 2017 15:55:21 GMT

{
  "id" : 3,
  "email" : "admin@example.com",
  "roles" : [ "ADMIN" ],
  "unverified" : false,
  "blocked" : false,
  "admin" : true,
  "goodUser" : true,
  "goodAdmin" : true,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_ADMIN"
  }, {
    "authority" : "ROLE_GOOD_USER"
  }, {
    "authority" : "ROLE_GOOD_ADMIN"
  } ],
  "name" : "Administrator",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "admin@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. Upon successful login, current-user data should be returned as the response.

  2. Giving wrong credentials should respond with 401 Aunauthorized.

  3. Spring security token based remember-me rules apply. Importantly,

    1. A rememberMe cookie is returned when rememberMe=true is passed as a request parameter.

    2. Sending the remember me cookie from a different session within 15 days would log the user in.

    3. Upon logout, the cookie is reset.

Positive test cases

  1. When a good ADMIN logs in, the response should contain

    1. his name

    2. a roles collection with role "ADMIN"

    3. goodAdmin as true

  2. When rememberMe=true parameter is sent, a rememberMe cookie is received. That cookie can be used in a different session to log the user in. Upon logging out from that session, the rememberMe cookie is reset.

Negative test cases

  1. Giving wrong credentials should respond with 401 Aunauthorized.

  2. A wrong rememberMe cookie should not log a user in.

Logout

Logs a user out.

Request

POST /logout HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 35d2c53a-4981-48b5-9d10-a63082adc33a
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/
Set-Cookie: rememberMe=; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/
Set-Cookie: XSRF-TOKEN=; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/
Date: Sun, 21 May 2017 15:55:23 GMT

Business rules

  1. Should log the user out, and send a 200 OK.

Positive test cases

  1. Should log the user out, and send a 200 OK.

Switch user

Switching to another user

Let’s a good ADMIN switch to another user. For example, a support guy can switch to another user while examining a complaint.

Request

POST /login/impersonate HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 33e68dfe-b18d-412a-8efc-12b7bbd619a0
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

username=user1%40example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Content-Length: 507
Date: Sun, 21 May 2017 15:55:37 GMT

{
  "id" : 86,
  "email" : "user1@example.com",
  "roles" : [ "UNVERIFIED" ],
  "unverified" : true,
  "blocked" : false,
  "admin" : false,
  "goodUser" : false,
  "goodAdmin" : false,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_UNVERIFIED"
  } ],
  "name" : "User 1",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "user1@example.com",
  "enabled" : true,
  "new" : false
}

Switching back

Request

POST /logout/impersonate HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 23ba1635-6248-4dba-b881-8b832eeeda98
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Content-Length: 591
Date: Sun, 21 May 2017 15:55:37 GMT

{
  "id" : 85,
  "email" : "admin@example.com",
  "roles" : [ "ADMIN" ],
  "unverified" : false,
  "blocked" : false,
  "admin" : true,
  "goodUser" : true,
  "goodAdmin" : true,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_ADMIN"
  }, {
    "authority" : "ROLE_GOOD_USER"
  }, {
    "authority" : "ROLE_GOOD_ADMIN"
  } ],
  "name" : "Administrator",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "admin@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. Only good ADMINs should be able to switch.

Positive test cases

  1. A good ADMIN should be able to switch to another user, and then switch back.

Negative test cases

  1. A non-admin should not be able to switch.

  2. An unauthenticated user should not be able to switch.

  3. A bad ADMIN should not able to switch.

Sign up

Signs up a new user and logs him in. A verification mail is sent to his email.

Request

POST /api/core/users HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 7f2234a6-68ac-460c-91c8-525c6630491e
Content-Type: application/json;charset=UTF-8
Host: www.example.com
Content-Length: 85

{
  "email" : "user1@example.com",
  "password" : "user1!",
  "name" : "User 1"
}

Add captchaResponse field if you want captcha validation. Sign up let’s you use the new reCAPTCHA from Google. If you use it, captchaResponse field should hold the captcha response. To use it,

  1. At the server side, set a couple of properties, as described in the getting started guide.

  2. At the client side, for an AngularJS client, angular-recaptcha works great. Remember to send the captcha response in the captchaResponse field.

If you don’t want Captcha, e.g. in a demo app, just don’t provide the captcha related properties in application.yml.

Response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:36 GMT
Content-Length: 507

{
  "id" : 80,
  "email" : "user1@example.com",
  "roles" : [ "UNVERIFIED" ],
  "unverified" : true,
  "blocked" : false,
  "admin" : false,
  "goodUser" : false,
  "goodAdmin" : false,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_UNVERIFIED"
  } ],
  "name" : "User 1",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "user1@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. Nobody should have already logged in.

  2. Email, password and name should be valid.

  3. The role UNVERIFIED is added to the user upon sign up.

  4. Password is stored encoded.

  5. After successful sign up

    1. The user is signed in.

    2. A verification mail is sent to the given email id.

Positive test cases

  1. A user should be able to sign up.

  2. After signing up

    1. The user should have signed in.

    2. His role should be UNVERIFIED.

    3. A verification mail should have been sent to the user.

Negative test cases

Sign up will respond with errors if you try it

  1. After being already logged in.

  2. With invalid email, password or name.

  3. Using an email id which is already signed up.

  4. With invalid captcha.

Resend verification mail

A verification mail is sent to users upon sign up. But, sometimes they may miss it. So, when a unverified user signs in, you may like to show him a button or something to resend the verification mail. Clicking on that should send a request to your API as below.

Request

GET /api/core/users/74/resend-verification-mail HTTP/1.1
Accept: */*
Host: www.example.com

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=7ed7fb98-323f-4d51-9217-90c61817c9a8; Path=/
Date: Sun, 21 May 2017 15:55:35 GMT

Business rules

  1. The user should exist.

  2. Current-user should have permission to edit the given user.

  3. The user should not have been verified.

  4. A new verification code isn’t generated. The existing verification code is used instead. It’s because sometimes the user might find the old mail, and try verifying with that.

Test cases

Positive

  1. An unverified user should be able to resend his verification code. The verificationCode of the user should not change in the process.

  2. A good ADMIN should be able to resend the verification mail of another unverified user.

Negative

  1. Providing unknown user id

  2. Trying

    1. without logging in

    2. logging in as a different user

    3. logging in as a bad ADMIN

    4. while already verified

Verify user

After a user signs up, he receives a verification mail. The mail contains a link with an embedded verificationCode. Clicking on it takes the user to the front-end application, where he is first asked to login if he is not already, and then click a verify button. On clicking verify, a POST request is sent as below.

Request

POST /api/core/users/00a1bf2c-7290-4275-ae7d-91c5c9386f8f/verify HTTP/1.1
Accept: */*
X-XSRF-TOKEN: d8af53a1-e780-4d30-a2d6-282067ce6513
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

Path parameters

Table 1. /api/core/users/{verificationCode}/verify
Parameter Description

verificationCode

The verification code

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:41 GMT
Content-Length: 494

{
  "id" : 113,
  "email" : "user1@example.com",
  "roles" : [ ],
  "unverified" : false,
  "blocked" : false,
  "admin" : false,
  "goodUser" : true,
  "goodAdmin" : false,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_GOOD_USER"
  } ],
  "name" : "User 1",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "user1@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. The user must have logged in.

  2. The user must not have already verified.

  3. Verification code shouldn’t be blank.

  4. Verification code should match the code that was mailed to the user while signing up.

  5. Upon successful verification, the UNVERIFIED role of the user is removed, and the verification code that was stored in the user record is wiped out.

  6. Upon successful commit, security principal’s UNVERIFIED role is removed, and it’s flags such as goodUser are computed again.

  7. Updated current-user data is returned.

Positive test cases

  1. A new user should be able to sign in, get a verification mail, and verify himself. Check that after verification,

    1. The same user is returned in the response.

    2. His UNVERIFIED role is removed.

    3. His verificationCode is set as null.

    4. Current-user, which is the user himself, has the following changes:

    5. UNVERIFIED role is removed

    6. He is now a good user

Negative test cases

  1. Re-verifying after successful verification.

  2. Trying with wrong verification code.

  3. Trying without logging the user in.

Forgot Password

When a user forgets his password, he can post a form as below.

Request

POST /api/core/forgot-password HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 904a5204-94ac-43c8-b125-178d1bb3696f
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

email=user1%40example.com

It would create a secret forgotPasswordCode, and mail the user a link including that code, looking like https://your-front-end.com/users/{forgotPasswordCode}/reset-password.

Clicking on the link should allow the user to reset his password.

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:31 GMT

Business rules

  1. A user with the given email should exist.

  2. The email should be well-formed, and not null or blank.

Positive test cases

  1. Upon posting,

    1. A secret code should be generated and stored in the User entity.

    2. A mail containing the code should be sent to the user.

Negative test cases

  1. Providing a null, blank or not well formed email.

  2. Not having a user with the given email address.

Reset password

In the Forgot Password section, we saw how a user gets a link with a forgotPasswordCode. Clicking on the link should take him to a front-end form, where he should enter a new password. Upon submitting that form, a request as below should be sent.

Request

POST /api/core/users/c7171ffd-e40d-4bea-a8ab-7e557896d758/reset-password HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 904a5204-94ac-43c8-b125-178d1bb3696f
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

newPassword=a-new-password

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:32 GMT

Business rules

  1. The user should have initiated the forgot password process.

  2. The user shouldn’t already have reset the password.

  3. The new password should be valid.

Positive test cases

  1. The password of the user should be updated, i.e., the user should then be able to login using the new password.

Negative test cases

The following tries should respond with errors:

  1. Trying with wrong forgotPasswordCode.

  2. Repeating resetting password.

  3. Invalid new password.

Fetch user by email

Example use case - a good ADMIN fetching a user, maybe for changing its roles.

Request

GET /api/core/users/fetch-by-email?email=user1%40example.com HTTP/1.1
Accept: */*
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=d487d066-53d5-4d88-8ba7-b9645061febf; Path=/
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:30 GMT
Content-Length: 525

{
  "id" : 42,
  "version" : 1,
  "email" : "user1@example.com",
  "roles" : [ "UNVERIFIED" ],
  "unverified" : true,
  "blocked" : false,
  "admin" : false,
  "goodUser" : false,
  "goodAdmin" : false,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_UNVERIFIED"
  } ],
  "name" : "User 1",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "user1@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. Email should be well formed, and not be blank.

  2. A user with the given email should exist.

  3. The confidential fields would be null in case the current user does not have rights to see those.

Positive test cases

  1. A user should be able to fetch his data, including the confidential email and username. But other confidential fields would be omitted.

  2. A good ADMIN should be able to fetch another user’s data, including the confidential email and username. But other confidential fields would be omitted.

  3. A i) bad ADMIN, ii) non-admin or iii) anonymous user should be able to fetch another user’s data. But all the confidential fields would be omitted.

Negative test cases

  1. Providing blank or non-well-formed email.

  2. Providing an unknown email id.

Fetch user by ID

Example use case - viewing the profile of a user.

Request

GET /api/core/users/39 HTTP/1.1
Accept: */*
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=281ea03c-d4c9-416a-bce9-b1a497d3a776; Path=/
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:29 GMT
Content-Length: 609

{
  "id" : 39,
  "version" : 0,
  "email" : "admin@example.com",
  "roles" : [ "ADMIN" ],
  "unverified" : false,
  "blocked" : false,
  "admin" : true,
  "goodUser" : true,
  "goodAdmin" : true,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_ADMIN"
  }, {
    "authority" : "ROLE_GOOD_USER"
  }, {
    "authority" : "ROLE_GOOD_ADMIN"
  } ],
  "name" : "Administrator",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "admin@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. A user with the given id should exist.

  2. The confidential fields would be omitted in case the current-user does not have rights to see them.

Positive test cases

  1. A user should be able to fetch his data, including the confidential email and username. But other confidential fields would be omitted.

  2. A good ADMIN should be able to fetch another user’s data, including the confidential email and username. But other confidential fields would be omitted.

  3. A bad ADMIN, non-admin or an anonymous user should be able to fetch another user’s data. But all the confidential fields would be omitted.

Negative test cases

  1. Providing an unknown id.

Update user

Updates the name and roles of a user.

Request

PATCH /api/core/users/97 HTTP/1.1
Accept: */*
X-XSRF-TOKEN: d9aa0bf0-1b3d-4589-9bce-12bc42fffe52
Content-Type: application/json;charset=UTF-8
Host: www.example.com
Content-Length: 371

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "Edited name"
}, {
  "op" : "replace",
  "path" : "/email",
  "value" : "should.not@get.replaced"
}, {
  "op" : "replace",
  "path" : "/unverified",
  "value" : false
}, {
  "op" : "replace",
  "path" : "/admin",
  "value" : true
}, {
  "op" : "replace",
  "path" : "/version",
  "value" : 0
} ]

If you have added more updatable fields to User, they can also be updated using this request.

What is version

User, like all VersionedEntity, has a version column, which is incremented on each update.

While updating, it is first checked that the given version is equal to the version in the database record. Otherwise, it is assumed that someone else has updated the record concurrently, and the update fails. To use it, you will typically

  1. Along with the data to be updated, fetch the version column as well.

  2. When the user submits the updated data, send the version back along with the updated data.

Precisely, we are talking about optimistic locking. Refer documentation and resources for more details.

Response

Please note that the response is the data of the logged-in user, who isn’t necessarily the updated one.

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:39 GMT
Content-Length: 591

{
  "id" : 96,
  "email" : "admin@example.com",
  "roles" : [ "ADMIN" ],
  "unverified" : false,
  "blocked" : false,
  "admin" : true,
  "goodUser" : true,
  "goodAdmin" : true,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_ADMIN"
  }, {
    "authority" : "ROLE_GOOD_USER"
  }, {
    "authority" : "ROLE_GOOD_ADMIN"
  } ],
  "name" : "Administrator",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "admin@example.com",
  "enabled" : true,
  "new" : false
}

Business rules

  1. A user with the given id should exist.

  2. Current-user should have permission to edit the given user.

  3. roles will be updated only if the current-user has permission to edit the roles.

    1. If UNVERIFIED role is removed from a user, his verificationCode should be set to null.

    2. If UNVERIFIED role is added to a user, a verificationCode should also be generated, and a verification mail should be sent to the user.

  4. The new name should be valid.

  5. The version column should be incremented on successful update.

  6. The user shouldn’t have been already updated concurrently, i.e. the input version should match the version in the database. Otherwise, expect a 409 response.

  7. If a user is updating himself, upon successful commit, the Security principal object is updated with the new name.

Positive test cases

  1. A non-admin user should be able to update his own name, but changes in roles should be skipped. The name of security principal object should also change in the process. The version column should be updated.

  2. A good ADMIN should be able to update another user’s name and roles. Check that the name of security principal object should NOT change in the process by mistake.

    1. When making a user UNVERIFIED, a verificationCode should be generated.

    2. When making a user verified, the verificationCode should be set to null.

Negative test cases

  1. Providing an unknown id in the path.

  2. A non-admin trying to update the name and roles of another user.

  3. A bad ADMIN trying to update the name and roles of another user.

  4. A good ADMIN trying to change his own roles.

  5. Providing an invalid name.

  6. A change in version occuring.

Change password

Changes the password of a user

Request

POST /api/core/users/36/change-password HTTP/1.1
Accept: */*
X-XSRF-TOKEN: c3d8f682-5611-41ad-8c2d-d6351224c5a5
Content-Type: application/json;charset=UTF-8
Host: www.example.com
Content-Length: 102

{
  "oldPassword" : "user1!",
  "password" : "new-password",
  "retypePassword" : "new-password"
}

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:28 GMT

Business rules

  1. A user with the given id should exist.

  2. Current user should have permission to edit the given user.

  3. oldPassword, password and retypePassword should not be null or blank, and should be between 6 and 30 characters long. oldPassword should match the user’s existing password.

  4. password and retypePassword should be same. (Ideally, this validation could have been left to the front-end. But, we thought to make this a server feature, for exibihiting how to code form-level custom validation.)

  5. If a user is changing his own password, after successful commit, he should be logged out.

Positive test cases

  1. A non-admin user should be able to change his password. After changing password, he should have been logged out.

  2. A good ADMIN should be able to update another user’s password.

Negative test cases

  1. Providing an unknown id in the path.

  2. A non-admin trying to update the password of another user.

  3. A bad ADMIN trying to update the password of another user.

  4. Providing invalid passwords.

  5. Providing wrong old password.

  6. password and retypePassword not being same.

Requesting for changing email

A user (or a good ADMIN) can request for changing email id, by using the following request.

Request

POST /api/core/users/58/request-email-change HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 694add07-5b7b-4654-9f34-4a8496b65d95
Content-Type: application/json;charset=UTF-8
Host: www.example.com
Content-Length: 642

{
  "id" : null,
  "version" : null,
  "email" : null,
  "password" : "user1!",
  "roles" : [ ],
  "verificationCode" : null,
  "forgotPasswordCode" : null,
  "newEmail" : "new@example.com",
  "changeEmailCode" : null,
  "apiKey" : null,
  "captchaResponse" : null,
  "unverified" : false,
  "blocked" : false,
  "admin" : false,
  "goodUser" : false,
  "goodAdmin" : false,
  "editable" : false,
  "rolesEditable" : false,
  "authorities" : null,
  "name" : null,
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : null,
  "enabled" : true,
  "new" : true
}

On receiving such a request, an email containing a link is sent to the new email id. A secret changeEmailCode is embedded in the link. Clicking on the link brings the user back to the front-end, where first he should log in if he is not already. Then, he would click a button for sending the final email change request for doing the final change.

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:33 GMT

Business Rules

  1. A user with the given id should exist.

  2. Current user should have permission to edit the given user.

  3. password should match the password of current-user.

  4. newEmail should not be blank, should be of a valid email format.

  5. newEmail should not already be used by any user.

  6. The user should be logged out after the email has changed.

Positive test cases

  1. A UNVERIFIED non-admin user should be able to request changing his email.

  2. A good ADMIN should be able to request changing the email of another user.

Negative test cases

  1. Providing an unknown id in the path.

  2. A non-admin trying to request changing email of another user.

  3. A bad ADMIN trying to request changing email of another user.

  4. Providing null password and email.

  5. Providing blank password and email.

  6. Providing invalid email.

  7. Providing wrong password.

  8. Providing non-unique email.

Change email

When a user requests for changing his email, a mail is sent to him, which contains a link with a changeEmailCode embedded. Clicking on the link brings him back to the client, where first he should login if he is not already. He then would click a button for proceeding with the change, which will send the following request to the server.

Request

POST /api/core/users/77e6fcf2-eb71-4d7b-8f3d-0e5d7c69afbd/change-email HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 936d969c-b1f7-4536-8d1e-b8f63611492a
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

Path Parameters

Table 2. /api/core/users/{changeEmailCode}/change-email
Parameter Description

changeEmailCode

The code that was mailed to the user

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:26 GMT

The server will verify the changeEmailCode, and then do the change and log the user out.

Business rules

  1. The given changeEmailCode should not be blank.

  2. The given changeEmailCode should match that of the current user in the database.

  3. Before replacing email with newEmail, uniqueness should again be checked.

  4. On success

    1. The user should be made verified if he is not already.

    2. The user should be logged out.

Positive test cases

  1. An unverified user, who had requested to change his email and had received the email with the link, should be able to change his email. The newEmail and changeEmailCode should be made null after the change, and he should have got verified. Also, he should have been logged out.

Negative test cases

  1. A good ADMIN trying to post the changeEmailCode of another user.

  2. Providing wrong changeEmailCode.

  3. Trying the operation without having requested first.

  4. Trying after some user registers the newEmail meanwhile, leaving it non unique.

Create API Key

Creates an API key for a user, which can be used later for authorizing requests.

Request

POST /api/core/users/1/api-key HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 315e4729-90a3-4487-b0b7-35acd52cc5a2
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: www.example.com

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:20 GMT
Content-Length: 57

{
  "apiKey" : "859d1e7b-7cbb-485c-b252-6e1c7a017aed"
}

Business Rules

  1. A user with the given id should exist.

  2. Current user should have permission to edit the given user.

Use API Key

The API key of a user can be used for custom token authentication, as below.

Request

PATCH /api/core/users/1 HTTP/1.1
Authorization: Bearer 1:859d1e7b-7cbb-485c-b252-6e1c7a017aed
Accept: */*
Content-Type: application/json;charset=UTF-8
Host: www.example.com
Content-Length: 282

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "Edited name"
}, {
  "op" : "replace",
  "path" : "/unverified",
  "value" : true
}, {
  "op" : "replace",
  "path" : "/admin",
  "value" : true
}, {
  "op" : "replace",
  "path" : "/version",
  "value" : 1
} ]

Headers

Name Description

Authorization

Custom token authentication - of the format userId:api-key

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: XSRF-TOKEN=56dc9c2a-4469-4087-8fa9-bd66471d2b17; Path=/
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 21 May 2017 15:55:20 GMT
Content-Length: 588

{
  "id" : 1,
  "email" : "admin@example.com",
  "roles" : [ "ADMIN" ],
  "unverified" : false,
  "blocked" : false,
  "admin" : true,
  "goodUser" : true,
  "goodAdmin" : true,
  "editable" : true,
  "rolesEditable" : false,
  "authorities" : [ {
    "authority" : "ROLE_ADMIN"
  }, {
    "authority" : "ROLE_GOOD_USER"
  }, {
    "authority" : "ROLE_GOOD_ADMIN"
  } ],
  "name" : "Edited name",
  "accountNonExpired" : true,
  "accountNonLocked" : true,
  "credentialsNonExpired" : true,
  "username" : "admin@example.com",
  "enabled" : true,
  "new" : false
}

Remove API Key

The API key of a user can be removed as below.

Request

DELETE /api/core/users/1/api-key HTTP/1.1
Accept: */*
X-XSRF-TOKEN: 2d9da505-71ed-4cf3-935c-b9f225d30c61
Host: www.example.com

Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Date: Sun, 21 May 2017 15:55:21 GMT

Business Rules

  1. A user with the given id should exist.

  2. Current user should have permission to edit the given user.