07 - Core - Security

Security in SOAJS is split into three categories:

• Key security
• Device security
• Geolocation security

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.

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": { ... }
        }
    }
}