ISAM cookbook for Advanced API Protection
By growing internet-based services and raising the number of internet users, the way companies and organizations build and provide their services has dramatically changed. Nowadays most businesses provide new business value for their consumers by exposing their services as APIs. These APIs facilitate the creation and exchange of information between organizations and their customers.
Every new development brings new challenges. Security breach through an organization’s APIs can damage the reputation of the organization and threaten the user information. OAuth 2.0 and API Key are two common methods to protect APIs. But in real-world scenarios, these methods are not sufficient and it requires the user to carry out further action through a remote channel for mitigating the risk of fraud and other abuses. When used in the context of banking APIs, PSD2 requires ASPSPs to use Strong Customer Authentication (SCA) and essentially Multi-Factor Authentication (MFA).
For facilitating API management, big companies like Google, Oracle, Microsoft, and IBM have introduced their own products. By acquiring Apigee, Google introduced a Cross-Cloud API Management Platform. Azure API Management has been developed by Microsoft and Oracle API Manager has been built by Oracle. IBM has introduced API Connect as its API Management Platform. Beside the API Connect there are two other IBM products that can be used to build an API Management ecosystem: IBM Security Access Manager and IBM DataPower.
Cookbook for API Protection
During the last year, my colleague Mehrdad A. and I were acquiring valuable knowledge in the way of protecting APIs. We designed protection mechanisms for some real-world scenarios and developed our mechanisms by using IBM Security Access Manager as the API gateway and Authorization Server. We documented our experiences and now we decided to share it as a cookbook.
This cookbook provides a step-by-step guide to configuring an IBM Security Access Manager Virtual Appliance to demonstrate API Protection scenarios. It was written to work with a fresh installation of IBM Security Access Manager 9.0.5.
This book begins with API definition and then, describes security principles of APIs. At the end of chapter 1, we go through ISAM OAuth 2.0 workflows and describe ISAM Mobile Multi-Factor Authentication.
Chapter 2 briefly introduce our high-level architecture and required components for this architecture. This chapter ends with an overview of our lab scenarios.
We create and configure required backend servers in chapter 3. All the backend servers run in a virtual machine and hopefully, we will create docker files for them in near future.
In chapter 4 we create and configure required reverse proxies in ISAM and at the end of this chapter, we configure Advanced Access Control.
Scenarios in this book are based on OAuth 2.0 protocol and Mobile Multi-Factor Authentication mechanisms. In chapter 5 we describe a step-by-step guide to deploy these mechanisms in ISAM. To maintain MMFA authenticators information, it is required to configure SCIM. This chapter provides a manual to configure SCIM.
In chapter 6 we show that how ISAM can be used to implement a simple API protection mechanism using OAuth Protocol.
Chapter 7 brings a more sophisticated protection mechanism to tackle the issues mentioned in chapter 6. In this chapter we use some infomaps without describing them more.
Chapter 8 shows how we can leverage ISAM AAC to implement fine-grained access control policies.
Finally, in Chapter 9 we dive into our infomaps and describe them one by one.
High-level Architecture
The high-level architecture and networking for the environment described in this book, may be summarized as follow:
All the lab scenarios in this book have three entities:
- API Server: this entity provides 3 simple banking APIs and the APIs would be accessed through ISAM WebSeal. We consider that there is no direct Access to API Server except ISAM WebSeal.
- Merchant App: Merchant App is a Third Party Application that consumes API Server endpoints. Merchant is considered to be an untrusted application and it requires OAuth access token for calling APIs. It has no direct access to API Server and access should be carried out through WebSeal. Merchant is considered to be as an OAuth Client.
- Dashboard Application: this application is a trusted one that serves web interface for OAuth grant management, dynamic client registration and device registration. End-users and OAuth clients(Merchant in our scenarios) can use this application.
Simple API protection Scenario
In all scenarios in this book, the user should delegate access to its APIs to the Merchant. We used the OAuth 2.0 protocol for the delegation flow. The picture below shows the flow for user access delegation:
After a successful access delegation, Merchant can call APIs that are belonged to access token scope. A simple API call with minimum protection by using OAuth-EAS in ISAM can be shown as depicted below:
The OAuth-EAS scenario has some limitations. In some cases, calling API requires more security controls. As an example If you want to provide payment APIs to the merchants, in addition to OAuth Access Token, it is required that users verify every transaction via a second-factor authentication mechanism. By attaching an API Protection policy to a resource, we can’t attach any other access control policies.
Advanced API Protection
Real world APIs require more sophisticated protection mechanisms. In chapter 7 we discussed a scenario in which we protect APIs using OAuth along with MMFA. After a successful access delegation, Merchant can call APIs belonging to access token scope. The following steps should be carried out in an API call:
In this chapter, we imported some mapping rules without discussing them more. In chapter 9 we went through these mapping rules and described the ideas behind each one of these files.
Context-based Access Policy
Most of the access scenarios in the real world require more granularity for doing an access decision. As an example in our Balance API, Merchant must not be allowed to get the balance of user2 with user1 Access Token or Merchant with a non-financial Access Token must not be allowed to access financial APIs. For implementing these access policies, ISAM has introduced context-based access control policies.
In chapter 8 we focused on context-based access control policies to protect APIs. These scenarios have been discussed in this chapter:
- Fine-grained access control based on the Access Token username
- Fine-grained access control based on the Account value
- Fine-grained access control based on the Amount value
- Fine-grained access control based on OAuth Scope.
A deep dive into our mapping rules
Some scenarios for using MMFA has been discussed in detail in “IBM Verify Cookbook Mobile Multi-Factor Authentication with IBM SAM”. There is a big difference between scenarios we considered for Protecting APIs and scenarios that have been discussed in that book. In their scenarios, user authentication state and AAC policies stay within the same HTTP session. In our scenarios, Merchant calls APIs in its HTTP session and user authenticate against AAC policies in a different HTTP session. In fact, Merchant calls APIs on behalf of the user by presenting the user’s OAuth token and depending on the access policy defined for APIs it may require the user to do more authentication steps. So to access an API, two different authentication flows should be carried out, one by OAuth access token on Merchant side and the other on the user side.
The problem is how we can branch authentication policies between Merchant and user in a way that after a successful authentication on user side we could tell the Merchant that the user side authentication has been done successfully. We came up with four ideas to tackle this issue:
- Branching Authentication Policy Using cache mechanism
- Branching Authentication Policy Using an external service
- Branching Authentication Policy Using a custom encryption mechanism
- Branching Authentication Policy Using STS
Branching Authentication Policy Using cache mechanism
In the post here, Shane Weeden has discussed a technique to branching authentication policy between two different HTTP sessions. The challenge that has been discussed in this post was about managing state information between the different AAC policies, since starting a new policy will not preserve the “context” object that was being populated from the first policy. He mentioned that this can easily be carried out with the help of a Javascript InfoMap to programmatically store the context you want to share using one of these methods:
- IDMappingExtUtils.setSPSSessionData(key, value)
- IDMappingExtUtils.getIDMappingExtCache().put(key, value, timeout)
We used this idea to implement our API Protection approach. The following steps shown by red color should be carried out to store a shared context between user and merchant:
setSPSSessionData is faster and more efficient than getIDMappingExtCache as it is in memory, but as the state information needed to persist across user and Merchant sessions we must use getIDMappingExtCache. Using getIDMappingExtCache will downgrade performance and in case of clustering multiple ISAMs, it requires to use a single Cache for all ISAMs.
Branching Authentication Policy Using an external service
In this approach, we used an external service to create shared storage between Merchant and user. The following steps shown by red color should be carried out to use an external service as shared storage:
Calling an external service for every request may significantly downgrade performance. Furthermore, you should responsible for the availability of the external service as well as the security of it.
Branching Authentication Policy Using a custom encryption mechanism
We used some cryptographic techniques to create a trust relationship between Merchant and user. The following steps shown by red color should be carried out to create a trust relationship:
For implementing this approach it’s not required to have a federation license and in terms of performance, this approach may be a good one but it brings some security concerns. As there is no facility in ISAM to store custom confidential data, cryptographic keys should be hardcoded in infomaps.
Branching Authentication Policy Using STS
The Security Token Service(STS) is a component of the federation runtime that accepts WS-Trust XML/SOAP requests for the validation and exchange of one security token type for another. It is used by the federation runtime, and can also be used by standalone WS-Trust clients, or by the ISAM reverse proxy for “TFIM-SSO” junctions.
We leveraged STS to create a trust relationship between Merchant and user. The following steps shown by red color should be carried out to create a trust relationship:
Resources
We put all resources required in this book in Github. Below are the links for a pdf version of our book and all components mentioned in this book:
License
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to Authsaz Group, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. Authsaz Group, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to Authsaz Group for the purposes of developing, using, marketing.
Each copy or any portion of these sample programs or any derivative work must include a copyright notice as follows:
© Authsaz Group 2019. Portions of this code are derived from Authsaz Group. Sample Programs.
© Copyright Authsaz Group 2019. All rights reserved.
Conclusion
This book contains information regarding API protection mechanisms. Scenarios mentioned in this book have been implemented using ISAM but you can use other solutions and products to implement these scenarios.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. We would really appreciate any feedback you can provide regarding technical, typographical, and theoretical issues.
Acknowledgement
We would like to acknowledge the help of all the people involved in this project and, more specifically, to siyamak abdollahzadeh that took part in the reviewing process.
