Login and Create a user

What you’ll learn

By the end of this guide you will learn to

  • Create a new User John with appropriate User Credentials .
  • use the BaseUser login and logout REST APIs to login and logout the generated User. You will do this with plain explorer

What you’ll need

To complete this guide, you will need the following -

  • a running NodeJS application built using the oeCloud.io.
  • a working REST client. You can use the Linux cURL command as a REST client if you have access to a Linux machine or have Git Bash installed on your Windows machine. REST addons for browsers, like Postman for Firefox or Google Chrome also can be used to complete this guide.
  • You can use your Application’s API Explorer also.

BaseUser vs AppUser

BaseUser is framework user model that stores user information like username (login id), password, email etc. Usually, applications developed using oeCloud.io framework, BaseUser Model is extended. In getting started guide of https://www.oeCloud.io portal, AppUser model extends BaseUser model. Therefore, if you are using application, you should always use AppUser model in this guide instead of BaseUser. If you are directly using github project, you should use BaseUser model in this guide.

How to complete this guide

Download and install oeCloud project from here. Follow Getting Started section.

If you already have application running, you can bypass the above step.

Login as admin user

Once you start application, framework by default creates admin user. User name, password for admin user is admin/admin.

you can login to admin user by posting following data to /BaseUsers/login method

{
"username" : "admin",
"password" : "admin"
}

you will receive response like below.

{
  "tenantId": "default",
  "roles": [
    "admin"
  ],
  "department": "adminstration",
  "username": "admin",
  "userTenantId": "default",
  "id": "AQt6X8iiQkFyIziJKcFdeN10AFl1kfo90PgAxu0IQuA9lxpbZ8IbdTbGD6LbHOIO",
  "ttl": 1209600,
  "created": "2017-05-22T13:53:32.908Z",
  "userId": "admin"
}

Access Token

  • “id”: “AQt6X8iiQkFyIziJKcFdeN10AFl1kfo90PgAxu0IQuA9lxpbZ8IbdTbGD6LbHOIO”, this information is very important. This is called access_token.
  • oeCloud.io identifies user based on access_token. For every request this token must be passed.
  • Swagger UI (/explorer) passes this token in every request as part of URL ?access_token=AQt6X8iiQkFyIziJKcFdeN10AFl1kfo90PgAxu0IQuA9lxpbZ8IbdTbGD6LbHOIO
  • Application may pass access token either in URL or part of cookie with same name.
  • When you are using Swagger UI, set access token using top-right text box available so that all subsequent requests will pass access_token in URL

Logout of admin user

You can logout by posing to /BaseUsers/logout method. you must pass Access_token to the request either as request parameter or cookie.

Create the new User

What you will essentially do is to POST the details of the User to be created in the JSON format, to the BaseUser API provided by the oeCloud.io. This API is an endpoint hosted by the running oeCloud framework and is of the form:

http://localhost:3000/api/BaseUsers

To create the User, carry out the following steps:

  • Open API explorer at http://localhost:3000/explorer/
  • POST the following User details to BaseUser Model.
{
"username":"john",
"password":"john",
"email":"john@xyz.com"
}
  • If you are using any other REST client POST the above data to http://localhost:3000/api/BaseUsers API.
  • If the application is running on a different machine, change the word localhost in the pasted command to the IP address of the machine where the application is running.
  • If the Data is POSTed successfully, the response status code should be **200 ** and the Response body should be as below:
{
  "username": "john",
  "email": "john@xyz.com",
  "id": "5922ee9288f4b87c18cd34c0",
  "_type": "BaseUser",
  "_createdBy": "system",
  "_modifiedBy": "system",
  "_createdOn": "2017-05-22T13:58:42.253Z",
  "_modifiedOn": "2017-05-22T13:58:42.253Z",
  "_autoScope": {
    "tenantId": "default"
  },
  "_isDeleted": false
}

Password Complexity

Rule for password complexity can be defined in config.json using following :

"passwordComplexity":{
      "regex":"^((?=.*[A-Z])(?=.*[a-z])(?=.*\\d)(?=.*[+$@$!%*#?&])[A-Za-z\\d+$@$!%*#?&]{8,20})$",
      "errMsg":"Password complexity not met. Password length should be minimum 8 and maximum 20.Password should contain atleast one capital, one small letter, one numaric and one special character(+$@$!%*#?&)."   
}
  • Here regex is Regular Expression according to password complexity requirements and errMsg is msg which will be sent if complexity doesn’t meet.
  • If regex value is blank nothing will get applied.

How to login

To login * John *, carry out the following steps:

  • Post following to /api/BaseUsers/Login method
{
  "username": "john",
  "password":"john"
}
  • you should see response similar to below
{
  "tenantId": "default",
  "roles": [],
  "username": "john",
  "userTenantId": "default",
  "id": "9bAWPV7x9TNkPhEIUxWLyAXoFpQLR2ayV1rSRwJbQtqMG6rAUhwGFJHYEuFiy3QC",
  "ttl": 1209600,
  "created": "2017-09-05T11:01:00.986Z",
  "userId": "59ae83c4a4280c3339090029"
}
  • This Id you get in the response body is used as Access Token throughout the Application to identify the Authenticated User.
  • In API Explorer you can set the Access Token using the Option given on the Header Set Access Token

How to logout

  • Do Post at /api/BaseUsers/Logout end point and ensure you pass access_token in url
POST /BaseUsers/logout/?access_token=<access token you got while login>

Note:

  • maxFailedLoginTries default value is 5, so after 5 wrong login account will be locked.
    This config can be set in config.json with property maxFailedLoginTries

  • after maxFailedLoginTries times wrong login, account will be locked and can be unlocked by admin using

//Only admin role user can access this unlock api
POST /BaseUsers/unlock/?access_token=<access token you got while login> 
  • TTL(Time to live) for access token can be set using accessTokenTTL property in config file.
{
  "accessTokenTTL": 180000
}

Internal Details

  • access_token is nothing but AuthSession table’s(or collection in MongoDB’s term) primary key.
  • access_token is used to authenticate and authorized the user. You must pass access_token either as request parameter or cookie in your REST API request.
  • Authsession model has got other information like tenant_id, username, ttl (time to live), roles of users etc.
  • All this information is available in callContext of every request. (options field dao)
  • If you want to add application specific information in context - when user login, you should add ‘before save’ hook on ‘AuthSession’ and add information.
  • This context is available throughout the web request.

Summary

Now you have seen

  • How to create a New User.
  • How to Login the User.
  • How to logout the User. Using the API endpoints provided by BaseUser Framework Model.