Key Security

Key Security is one of the security measures that SOAJS provides to protect your services and their APIs. To use this security system, first a service should support Multitenancy because keys are associated with tenant applications. To generate a key, navigate to the Multitenancy section in the Dashboard UI, choose a tenant and generate a key for its application.

Keys secure our APIs with different techniques; they have expiry dates and they provide geo location and device security. Every key represents an object that contains this configuration. Based on how the key is configured, SOAJS security system will respond.

Property Name	Property Type	Mandatory	Description
extKey	String	YES	Encrypted version of the application key, should be provided in the headers of every request made to the service APIs.
expDate	Date	YES	Encrypted key expiry date value; after this date requests using this key will be blocked.
device	Object	NO	Configuration object that when provided, the device information in the request are checked for validation.
geo	Object	NO	Configuration object that when provided, the Location of the request sender is checked for validation.

The following sample represents an encrypted key, with an expiry date and only chrome browsers are allowed to call the API using this key From the ip address 127.0.0.1 only.

{
    "expDate": 1426074981752,
    "extKey": "aa39b5490c4a4ed0e56d7ec1232a428f77...",
    "device": {
        "allow": [
            {
                "family": "chrome", 'major': '41', 'minor': '0', 'patch': {'min': '2222', 'max': '2229'}
            }
        ],
        "deny": [
            {
                'family': 'IE'
            }
        ]
    },
    "geo": {
        "allow": ["127.0.0.1", "localhost"],
        "deny": ['121.5.6.7']
    }
}

Keys in Requests

Every encrypted key is a public key and should be provided in the request being made to a multitenant service API. When a public key is provided in the request, it is matched to see if it is valid. If valid and the remaining security checks, as mentioned above, pass then SOAJS loads the tenant information corresponding to the given key, adds that information to req.soajs and then the request is forwarded to API business logic to be handled.
When making a request to a multitenant service, the key should be provided either in the header or as a querystring parameter:

# provide the key in the header
  CURL -X GET -H "key:aa39b5490c4a4ed0e56d7ec1232a428f771e8bb83cfcee16de14f735d0f5da587d5968ec4f785e38570902fd24e0b522b46cb171872d1ea038e88328e7d973ff47d9392f72b2d49566209eb88eb60aed8534a965cf30072c39565bd8d72f68ac" "http://127.0.0.1:4020/hello?firstName=John&lastName=Doe"

# provide the key as a querystring parameter
  CURL -X GET "http://127.0.0.1:4020/hello?firstName=John&lastName=Doe&key=aa39b5490c4a4ed0e56d7ec1232a428f771e8bb83cfcee16de14f735d0f5da587d5968ec4f785e38570902fd24e0b522b46cb171872d1ea038e88328e7d973ff47d9392f72b2d49566209eb88eb60aed8534a965cf30072c39565bd8d72f68ac"

Private/Public Keys

Public encrypted keys have corresponding private keys in the database. When a key is checked, SOAJS looks for a private key that matches it in the tenants collection. Private keys support multiple public keys each with a different configuration and security permissions. Here is how the key schema looks like in the database:

{
    "key": "38145c67717c73d3febd16df38abf311",
    "extKeys": [
        {
            "expDate": 1430520478470,
            "extKey": "aa39b5490c4a4ed0e56d7ec1232a428f771e8bb83cfcee16de14f735d0f5da587d5968ec4f785e38570902fd24e0b522b46cb171872d1ea038e88328e7d973ff47d9392f72b2d49566209eb88eb60aed8534a965cf30072c39565bd8d72f68ac",
            "device": null,
            "geo": null
        }
        //...
    ],
    "config": { ... }
}

Private keys also contain services configuration. A service like Urac or as we demonstrated in Example03 require tenant key configuration in their business logic. This configuration varies from one key to another. Having that said, the service not only serves multiple tenants, but can serve multiple applications for that tenant where each business logic reads the configuration differently.

Code Sample

The below snippet represents a private key with one public key that has an expiry date. The key Geo Location Security configuration allows requests to be made from either localhost or 127.0.0.1 and if a request originates from 121.5.6.7, it is blocked and does not go through.
The Device Security configuration implies that the request should originate from a chrome browser and if Internet Explorer is used; it gets blocked as well. Device security also supports versions through a range between minor and major versions with patches. SOAJS uses useragent module to perform its device validation.

{
    "key": "695d3456de70fddc9e1e60a6d85b97d3",
    "extKeys": [
        {
            "expDate": new Date().getTime() + 86400000,
            "extKey": "aa39b5490c4a4ed0e56d7ec1232a428f7ad78ebb7347db3fc9875cb10c2bce39bbf8aabacf9e00420afb580b15698c04ce10d659d1972ebc53e76b6bbae0c113bee1e23062800bc830e4c329ca913fefebd1f1222295cf2eb5486224044b4d0c",
            "device": {
                "allow": [
                    {
                        "family": "chrome", 'major': '41', 'minor': '0', 'patch': {'min': '2222', 'max': '2229'}
                    }
                ],
                "deny": [{'family': 'IE'}]
            },
            "geo": {
                "allow": ["127.0.0.1", "localhost"],
                "deny": ['121.5.6.7']
            }
        }
    ],
    "config": {
        "dev": {
            "urac": { ... }
        }
    }
}

Browser not supported