So, you are building a new RESTful APIs and want your customers to build against these APIs. Or you have an appliance that you will ship to customer location which will call your APIs routinely.
In both of these scenarios, you want your customers (who are API clients) to authenticate before invoking protected APIs. Plus you also want to ensure that proper access control (authorization) is in place to ensure that the API clients can only call APIs they are authorized to invoke. In case of multi-tenant APIs, you also want to ensure that data is completely segregated.
SecureDB’s Encrypted IdM can act as Identity server for your APIs, saving you time and bringing in efficiency. This post delves into how to protect your APIs.
Components at play
The figure below shows different components at play.
Using SecureDB Encrypted IdM to protect APIs
API Client is a RESTful API client written to consume Your REST APIs. With SecureDB (Encrypted) Identity Manager (IdM) managing your API keys and other customer information Your REST APIs calls SecureDB (Encrypted) Identity Manager (IdM) to authenticate the API Client or to make authorization decisions.
Create API Keys
For every new customer, you may issue one or more API Keys (that is API Key and API Secret combination). This can be done by simply calling the /quickregister API as shown below.
|
1 2 3 4 5 6 |
curl -i -d '{"userName": "0KEPQXE50Q", "password": "fdkj^7dkjfsJSF786"}' -H "Content-Type: application/json" -H "Authorization: Basic SDU5WE201YUssQzpRRUNaTlNXV1TM1BJNjM=" -X POST https://api.securedb.co/securedbapi/account/45fgds7/default/quickregister |
Note: The URL will be different if you are using SecureDB Enterprise, our on-prem solution.
In the snippet above, we just created API Key and API Secret in SecureDB’s Encrypted IdM. You can pass this to your customer in a secure way. In a real life scenario, you may have a portal that let’s your customers download their API Key and API Secret. In that case, your portal would call the /quickregister API to create credentials. This API’s response has the UUID of the API Key:
|
1 2 3 4 5 6 |
{ "message": "Account created successfully.", "error": false, "data": "a48b99ed-a4ed-411e-896f-888ee0d86028", "errorCode": 0 } |
Client Authentication
Let’s assume that your APIs require your API clients to authenticate. You could ask your API clients to send API Key and API Secret combination during every call. If that’s the case, from your API code, simply pass the API Key and API Secret to be validated against SecureDB’s Encrypted IdM.
|
1 2 3 4 5 6 |
curl -i -d '{"userName": "0KEPQXE50Q", "password": "fdkj^7dkjfsJSF786"}' -H "Content-Type: application/json" -H "Authorization: Basic SDU5WE201YUssQzpRRUNaTlNXV1TM1BJNjM=" -X POST https://api.securedb.co/securedbapi/account/45fgds7/default/authenticate |
If the authentication is successful, SecureDB Encrypted IdM will send back 200 OK response. This will be your indication that you can serve the client’s request.
Instead of asking your API client to send API Key and API Secret with every request, you could ask the client to send pair only the first time. You could use the above API to authenticate the request, but instead return a JSON Web Token (JWT) to your API client. SecureDB Encrypted IdM supports JWT and can be used to authenticate subsequent API requests.
|
1 2 3 4 5 |
curl -i -d '{"userName": "0KEPQXE50Q", "password": "fdkj^7dkjfsJSF786"}' -H "Content-Type: application/json" -X POST https://api.securedb.co/securedbapi/account/45fgds7/default/authenticate |
To make SecureDB Encrypted IdM return JWT upon authentication, simply call the /authentication method without the Authorization header. The JWT is returnd by SecureDB Encrypted IdM as part of response header:
|
1 |
"authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTZWN1cmVEQiBJbmMuIiwiYXVkIjpbImN1c3RvbWVySWQ6OUFrYjVZanEiLCJkaXJlY3RvcnlJZDpkZWZhdWx0Iiwicm9sZU5hbWU6bm9uZSIsInVzZXJOYW1lOmsuYXJ0aGlrdmFzdWRldmFAZ21haWwuY29tIiwiYWNjb3VudElkOjZhNDZhNGY3LTNjZDYtNDZiYy04NTUzLTZhNTZlOGYyN2EwZCIsImlkOjhjNDEyNGMzLWNhNWMtNDNlMS04NjQzLWI2YWQxZGYyNmNlMyIsImNyZWF0aW9uVGltZToxNDUxNDI1MTIzMDc1IiwicGxhblR5cGU6RnJlZSIsIm1hcmtldHBsYWNlUmVmOm51bGwiXSwiZXhwIjoxNDUxNTExNTIzLCJqdGkiOiI0UUxZM3FIZzl4UEppczNoS2lRQ3p3IiwiaWF0IjoxNDUxNDI1MTIzLCJuYmYiOjE0NTE0MjUwMDMsInN1YiI6ImsuYXJ0aGlrdmFzdWRldmFAZ21haWwuY29tIn0.f0tUuYcyptoCfIuh1sXvbMnKR2i5ee_kVS-6i9v2CTs" |
You can pass this JWT to the API client and expect the client to send this token as part of every request. By default, this JWT is valid for 60 minutes (this time is configurable). Now, when your API client sends this JWT back to you, you can check the validity of the JWT yourself. To do this, you need to be able to make sure that the JWT was not tampered by the API client. In order to validate, you need to get the secret key that was used to construct the JWT signature. The secret key would act as a shared secret between your APIs and SecureDB Encrypted IdM.
Client Authorization
Now, let’s add authorization (access control) into the mix. SecureDB Encrypted IdM supports Roles and hence can aid you in implementing effective Role Based Access Control (RBAC).
Let’s now add a role to the API Key created earlier:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// Create a role called 'admin' curl -i -d '{"roleName": "admin"}' -H "Content-Type: application/json" -H "Authorization: Basic SDU5WE201YUssQzpRRUNaTlNXV1TM1BJNjM=" -X POST https://api.securedb.co/securedbapi/account/45fgds7/default/role // Add this role to the API Key created above. curl -i -d '{"ar_uuid":"a48b99ed-a4ed-411e-896f-888ee0d86028", "roleName":"admin"}' -H "Content-Type: application/json" -H "Authorization: Basic SDU5WE201YUssQzpRRUNaTlNXV1TM1BJNjM=" -X POST https://api.securedb.co/securedbapi/account/45fgds7/default/accountrole |
Now the API Key you issued earlier has a Role associated called admin. Now, let’s assume you want a certain API of yours to be accessible only by customer API Keys that have the Role called admin. You’ll be glad to know that SecureDB Encrypted IdM puts the Role into the JWT payload. So, after you validate the incoming JWT, you can pull the Role from JWT and make your authorization decision.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// JWT after base64 decoding { "iss": "SecureDB Inc.", "aud": [ "customerId:45fgds7", "directoryId:default", "roleName:admin", "userName:0KEPQXE50Q", "accountId:a48b99ed-a4ed-411e-896f-888ee0d86028", "id:8c4124c3-ca5c-43e1-8643-b6ad1df26ce3", ... ], "exp": 1451511523, ... } |
Lock the API Key
Now, let’s say one of your API client is misbehaving. Or hasn’t paid you money and you want to lock the API Key temporarily. This is easy too:
|
1 2 3 4 |
curl -i -d -H "Content-Type: application/json" -H "Authorization: Basic SDU5WE201YUssQzpRRUNaTlNXV1TM1BJNjM=" -X PUT https://api.securedb.co/securedbapi/account/45fgds7/default/<code class="highlight shell">lockusername/</code>0KEPQXE50Q |
All the subsequent authentication calls will fail until you unlock your customer’s API key. Similarly you can delete the API Key too. For a full list of APIs available, click here. To try the APIs, use our API Playground tool.
Summary
In short, SecureDB Encrypted IdM can not only be used as a secure Identity Manager for your Web applications. It can also form the back bone of your API strategy. Your APIs have the same Identity Management requirements as your Web applications. This is where SecureDB Encrypted IdM shines.
