Introduction

In the Basic Service example, we learned to perform a heartbeat check on a service to monitor its health.

Moreover, sample tests to expose the basic functionalities of a SOAJS service, and those of the IMFV.

In this section, one of the APIs from the Basic Service example was secured with oAuth. When securing a service with oAuth, the service becomes accessible only to users with valid oAuth credentials.

Every request made to the service is first validated by the SOAJS oAuth Service before being forwarded to the service.

Code Walkthrough

This page shows you how to interact with example02 service after you install it and run it.

The code walkthrough is located in a sub page and explained in depth. Click here to read the explanation.

Service Exploration

To turn on oauth in a development environment you just need to start the environment as follow

Controller Installation

sudo soajs services start --env=example

Verify auth

To verify if oauth is running you need to login to soajs console and

go under deploy tab
select environment example
click on SOAJS catalog from the left menu
expand auth item
click on maintenance operations
select heartbeat

Using the Service APIs

In the Basic Service example, the "testGet" API was not designed to be secured with oAuth. In this example we added this security option to it.

The following example is a request to the testGet API, without providing the required authentication credentials.

# go to examples/example02 and start the service
cd soajs.examples/example02/
  
# start the soajs example environment
sudo soajs services start --env=example
  
# export necessary environment variables to create local awareness
export SOAJS_ENV=EXAMPLE
export SOAJS_SRVPORT=4022
export SOAJS_DEPLOY_MANUAL=1
export SOAJS_REGISTRY_API=127.0.0.1:21000
  
  
# start service
node .

# hit the API
curl -X GET "http://127.0.0.1:20000/example02/buildName?firstName=John&lastName=Smith"

As expected, the API replied with an error stating that The access token was not found. Thus, the user was not permitted to access the services of this API.

{result: false, errors: {codes: [ 400 ],details: [ { code: 400, message: "The access token was not found"}]}}

Login to oAuth

The user must login to oAuth and get an access token.

The code block below represents a request to the oAuth/token API.

The header contains the tenant key. More details regarding the tenant key can be found in the Multitenancy section in the documentation.

The Authorization in the header is used by oAuth to validate both posted body and is explained in detail in oAuth section under documentation.

The body, on the other hand, accepts three input parameters: username, password, grant_type.

curl -X POST -H "key:4ea5db4c70b6168aeede6a8a56cb4624efdb6cb2cf3c7b88cbc1f5d97080a44f18083fa195e20dcc0b42496ae268ea91c657dd9b252b72de14c862e64f8522a9dbdaa1ce0f48ba2d5ed5eff49b47d0f728bddb2080c8cbc7bde3771116192b51" "http://127.0.0.1:20000/oauth/token" -d 'username=example&password=password&grant_type=password'

The corresponding response contains the corresponding access_token, which expires in one hour (in this example), and refresh_token, that is used once the access_token expires.

{"token_type":"bearer","access_token":"30f3a13fcdb60cde1cdf576634cbb7777df31177","expires_in":3600,"refresh_token":"6ea967dfe6c005d86b6fb0b0331ed52b89a1cee7"}

TestGet with a valid oAuth access token

What follows is a new request to the testGet API. However, the request in this example contains the valid access_token obtained above. As can be seen in the code block below, the access_token is appended to the request.

curl -X GET "http://127.0.0.1:20000/example02/buildName?firstName=John&lastName=Smith&access_token=30f3a13fcdb60cde1cdf576634cbb7777df31177"

As a result, after validating the legitimacy of the access_token, the API responds with a successful response to the user.

{"result":true,"data":{"fullName":"John Smith"}}

Browser not supported