Securing The API Stronghold
The Ultimate Guide to API Security
Nordic APIs
This book is for sale at
http://leanpub.com/securing-the-api-stronghold
This version was published on 2015-09-23
This is a Leanpub book. Leanpub empowers authors and
publishers with the Lean Publishing process. Lean
Publishing is the act of publishing an in-progress ebook
using lightweight tools and many iterations to get reader
feedback, pivot until you have the right book and build
traction once you do.
2015 Nordic APIs AB
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . i
1. Introducing API Security Concepts . . . . . . . 1
1.1 Identity is at the Forefront of API Security . 2
1.2 Neo-Security Stack . . . . . . . . . . . . . . . 2
1.3 OAuth Basics . . . . . . . . . . . . . . . . . . 3
1.4 OpenID Connect . . . . . . . . . . . . . . . . 5
1.5 JSON Identity Suite . . . . . . . . . . . . . . . 6
1.6 Neo-Security Stack Protocols Increase API
Security . . . . . . . . . . . . . . . . . . . . . 6
1.7 The Myth of API Keys . . . . . . . . . . . . . 7
1.8 Access Management . . . . . . . . . . . . . 7
1.9 IoT Security . . . . . . . . . . . . . . . . . . . 7
1.10 Using Proven Standards . . . . . . . . . . . 8
2. The 4 Defenses of The API Stronghold . . . . . 9
2.1 Balancing Access and Permissions . . . . . 10
2.2 Authentication: Identity . . . . . . . . . . . . 12
2.3 Authorization: Access . . . . . . . . . . . . . 13
2.4 Federation: Reusing Credentials & Spreading
Resources . . . . . . . . . . . . . . . . . 14
2.5 Delegation: The Signet of (Limited) Power . 18
2.6 Holistic Security vs. Singular Approach . . . 19
2.7 Application For APIs . . . . . . . . . . . . . . 20
CONTENTS
3. Equipping Your API With the Right Armor: 3
Approaches to Provisioning . . . . . . . . . . . 22
3.1 Differences In API Approaches: Private, Public,
& Partner APIs . . . . . . . . . . . . . . . 23
3.2 Considerations and Caveats . . . . . . . . . 25
3.3 So Where Is The Middle Ground? . . . . . . 26
3.4 Real-World Failure . . . . . . . . . . . . . . . 27
3.5 Two Real-World Successes . . . . . . . . . . 29
3.6 Conclusion . . . . . . . . . . . . . . . . . . . 30
4. Your API is Vulnerable: 4 Top Security Risks
to Mitigate . . . . . . . . . . . . . . . . . . . . . . 32
4.1 Gauging Vulnerabilities . . . . . . . . . . . . 33
4.2 Black Hat vs. White Hat Hackers . . . . . . . 34
4.3 Risk 1 - Security Relies on the Developer . . 35
4.4 Risk 2 - Just Enough Coding . . . . . . . . . 36
4.5 Risk 3 - Misunderstanding Your Ecosystem 39
4.6 Risk 4 - Trusting the API Consumer With
Too Much Control . . . . . . . . . . . . . . . 40
4.7 Conclusion . . . . . . . . . . . . . . . . . . . 41
5. Deep Dive into OAuth and OpenID Connect . 42
5.1 OAuth and OpenID Connect in Context . . 42
5.2 Start with a Secure Foundation . . . . . . . 43
5.3 Overview of OAuth . . . . . . . . . . . . . . 44
5.4 Actors in OAuth . . . . . . . . . . . . . . . . 45
5.5 Scopes . . . . . . . . . . . . . . . . . . . . . . 46
5.6 Kinds of Tokens . . . . . . . . . . . . . . . . 46
5.7 Passing Tokens . . . . . . . . . . . . . . . . . 47
5.8 Profiles of Tokens . . . . . . . . . . . . . . . 48
5.9 Types of Tokens . . . . . . . . . . . . . . . . 49
5.10 OAuth Flow . . . . . . . . . . . . . . . . . . . 51
5.11 Improper and Proper Uses of OAuth . . . . 52
5.12 Building OpenID Connect Atop OAuth . . . 53
5.13 Conclusion . . . . . . . . . . . . . . . . . . . 56
CONTENTS
6. Unique Authorization Applications of OpenID
Connect . . . . . . . . . . . . . . . . . . . . . . . . 58
6.1 How OpenID Connect Enables Native SSO . 59
6.2 How to Use OpenID Connect to Enable
Mobile Information Management and BYOD 60
6.3 How OpenID Connect Enables the Internet
of Things . . . . . . . . . . . . . . . . . . . . 62
7. How To Control User Identity Within Microservices
. . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.1 What Are Microservices, Again? . . . . . . . 65
7.2 Great, So Whats The Problem? . . . . . . . 66
7.3 The Solution: OAuth As A Delegation Protocol 67
7.4 The Simplified OAuth 2 Flow . . . . . . . . . 68
7.5 The OpenID Connect Flow . . . . . . . . . . 69
7.6 Using JWT For OAuth Access Tokens . . . . 71
7.7 Let All Microservices Consume JWT . . . . . 72
7.8 Why Do This? . . . . . . . . . . . . . . . . . . 73
8. Data Sharing in the IoT . . . . . . . . . . . . . . 74
8.1 A New Economy Based on Shared, Delegated
Ownership . . . . . . . . . . . . . . . . 75
8.2 Connected Bike Lock Example IoT Device . 76
8.3 How This Works . . . . . . . . . . . . . . . . 76
8.4 Option #1: Access Tables . . . . . . . . . . . 77
8.5 Option #2: Delegated Tokens: OpenID Connect
. . . . . . . . . . . . . . . . . . . . . . . 78
8.6 Review: . . . . . . . . . . . . . . . . . . . . . 80
9. Securing Your Data Stream with P2P Encryption
. . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.1 Why Encrypt Data? . . . . . . . . . . . . . . . 83
9.2 Defining Terms . . . . . . . . . . . . . . . . . 84
9.3 Variants of Key Encryption . . . . . . . . . . 86
9.4 Built-in Encryption Solutions . . . . . . . . . 87
CONTENTS
9.5 External Encryption Solutions . . . . . . . . 88
9.6 Use-Case Scenarios . . . . . . . . . . . . . . 88
9.7 Example Code Executions . . . . . . . . . . 89
9.8 Conclusion . . . . . . . . . . . . . . . . . . . 90
10. Day Zero Flash Exploits and Versioning Techniques
. . . . . . . . . . . . . . . . . . . . . . . . . 91
10.1 Short History of Dependency-Centric Design
Architecture . . . . . . . . . . . . . . . . 92
10.2 The Hotfix Versioning . . . . . . . . . . . 93
10.3 Dependency Implementation Steps: EIT . . 95
10.4 Lessons Learned . . . . . . . . . . . . . . . . 96
10.5 Conclusion . . . . . . . . . . . . . . . . . . . 97
11. Fostering an Internal Culture of Security . . . 98
11.1 Holistic Security Whose Responsibility? . 99
11.2 The Importance of CIA: Confidentiality, Integrity,
Availability . . . . . . . . . . . . . . . 100
11.3 4 Aspects of a Security Culture . . . . . . . 105
11.4 Considering Culture . . . . . . . . . . . . . 106
11.5 All Organizations Should Perpetuate an Internal
Culture of Security . . . . . . . . . . . 107
Resources . . . . . . . . . . . . . . . . . . . . . . . . . 108
API Themed Events . . . . . . . . . . . . . . . . . 108
API Security Talks: . . . . . . . . . . . . . . . . . . 108
Follow the Nordic APIs Blog . . . . . . . . . . . . 109
More eBooks by Nordic APIs: . . . . . . . . . . . 109
Endnotes . . . . . . . . . . . . . . . . . . . . . . . . . 110
Preface
As the world becomes more and more connected, digital
security becomes an increasing concern. Especially in the
Internet of Things (IoT), Application Programming Interface
(API), and microservice spaces, the proper access
management needs to be seriously addressed to ensure
web assets are securely distributed.
During the Nordic APIs World Tour - a five day international
conference we held in May 2015 - our speakers
consistently reiterated the importance of API security.
So, to help providers secure their systems, we at Nordic
APIs have collated our most helpful advice on API security
into this eBook; a single tomb that introduces important
terms, outlines proven API security stacks, and describes
workflows using modern technologies such as OAuth and
OpenID Connect.
Founded on insights from identity experts and security
specialists, this knowledge is crucial for most web service
platforms that needs to properly authenticate, control access,
delegate authority, and federate credentials across
a system.
Following an overview of basic concepts, well dive into
specific considerations such as:
Vulnerabilities and what whitehackers look for
How to implement a secure versioning strategy
The three distinct approaches to API licensing and
availability
Preface ii
Performing delegation of user identity across microservices
and IoT devices
Using the Neo-Security stack to handle identity and
access control with OAuth 2.0 and OpenID workflows
Differentiating Authentication, Authorization, Federation,
and Delegation, and the importance of each
Using OpenID Connect for Native Single Sign On
(SSO) and Mobile Identity Management (MIM)
Ways to introduce a culture of security into your
organization
Securing your data stream at the point-to-point level
And more
Please read on, share, and enjoy the 5th free eBook from
the Nordic APIs team!
Bill Doerrfeld, Editor in Chief, Nordic APIs
Connect with Nordic APIs:
Facebook | Twitter | Linkedin | Google+ | YouTube
Blog | Home | Newsletter | Contact
1. Introducing API Security
Concepts
Knowing who has the right to do what with
your API is key to success - Andreas Krohn,
Dopter
Design all API security with public access in
mind - Phillipp Schne, Axway
Application Programming Interfaces or APIs are not only
an extension of the social web, but continue to seriously
disrupt entire industries, change how Business-tobusiness
(B2B) communication is throttled, spark innovation,
and even inspire social change. Simply put by
TechCrunch, APIs fuel the software thats eating the world.
Within this vibrant and quickly expanding economy, an
increasing amount of data is being funneled through
systems not designed with the scale of protection that is
necessary. The risk of cyber threat is now the highest it
has ever been, and it wont stop anytime soon. To combat
this threat we must take the smart precautions to arm our
systems. We build with the assumption that even private
APIs will sooner or later become exposed to the public,
and embrace proper security implementation as a top
concern.
1
Introducing API Security Concepts 2
1.1 Identity is at the Forefront of API
Security
API security isnt just about the API itself, but also about
the security of entire organizations and mobile products
when they intersect with APIs.
When developing an API, the security of the mobile device
matters just as much as the security of the API.
Does it have anti-virus software installed? Is it enrolled
in a mobile device management solution (MDM)? Does
it have mobile application management software (MAM)
installed? You also need to worry about enterprise security.
Are the servers secure? Do your machines have
intrusion detection?
At this junction of APIs, business, and mobile, lies the
individual. Only when you know who is at this core will you
know what they should be accessing and how they should
be accessing it.
1.2 Neo-Security Stack
When we start to expose high-value information and
resources, we need to have high-level assurance of who
is accessing them. API security is comprised of a number
of protocols, which Twobo Technologies refers to as the
Neo-Security stack. This standards-based cloud security
suite is usually comprised of these protocols and technologies:
OAuth 2: The open standard for secure, delegated
access
OpenID Connect: For federation which allows for
the secure exchange of user authentication data
Introducing API Security Concepts 3
JSON Identity Suite: The collection of JSON-based
protocols for representing the identity of users
SCIM: System for Cross-domain Identity Management
for user account provisioning and deprovisioning
U2F: Universal 2-factor authentication for asymmetrically
identifying users with a high degree of confidence
that they really are who they say they are
ALFA: For defining fine-grained authorization rules
in a JSON-like policy language (which compiles down
into XACML)
While the Neo-Security stack creates a comprehensive
security solution for mobility, it is a great challenge for API
developers to manage a myriad of specifications themselves.
1.3 OAuth Basics
As the risk associated with an individuals online identity
increases, we need to ask permission before exposing
identity and any vulnerable resources with an API. OAuth
is a framework used to build API security solutions - a
framework or meta-protocol under which we create other
protocols to define how tokens are handled. Despite its
name, OAuth is not for authentication, federation, or even
authorization; it helps delegate access, ie. giving an app
access to your data or service. A benefit of using OAuth is
that somebody else authenticates users.
These following factors make up OAuth2 Protocols:
Client: The web or mobile application involved
Introducing API Security Concepts 4
Authorization Server (AS): The security token service,
which issues credentials and tokens that represent
the resource owner
Resource Owner (RO): Authorizes or delegates access
to the RS
Resource Server (RS): Often the API itself, a collection
of libraries and web applications
How these four OAuth2 actors work together varies with
each integration. Well dive into the processes behind
common OAuth server flows in future chapters, but to
summarize:
OAuth Web Server Flow
A three-legged OAuth process occurs when an end
user specifies that he or she wants to delegate access to
a third-party application for use within the client application.
The client application then redirects this request to
the AS, which requires authentication for identification.
The AS then authorizes that client and the RO is redirected
back to the web app with a single-use access code.
The single-use access code is sent back to the AS, which
then converts it into an access token that the end user
may use to access the server. At the same time, the AS
may also send back a refresh token which will allow the
end user to use the same OAuth to access more than
once.
Essentially, the access token allows a user to call the API.
In return, the API gains access to information about both
the client and the resource owner and what path they
took, what client they are using, and who is the end user.
With this information, you are able to create much more
Introducing API Security Concepts 5
complete web access control decisions that improve API
security. Everything is built right into OAuth2, limiting
human-designed security errors.
1.4 OpenID Connect
OpenID Connect is a standard that complements OAuth
to add user identity to an API security solution. OpenID
Connect gives you a standardized identity layer with standardized,
researched risk mitigation and continuous examination
of new threats. OpenID Connect is often used
to connect internal applications and share user information.
OpenID Connect and its predecessor SAML focus on authentication
and federation, identifying a user before information
is pushed to a third-party. Using OpenID Connect,
you could give strategic partners similar access to
make API calls.
There are even third-party organizations responsible for
determining identity, often called an identity provider
or IdP. Developers are able to use an IdP and push that
access to a third-party app. This allows the IdP to act as
an identity provider as well as an API provider, allowing
the IdP, acting as an API, to exchange data with the app.
OpenID Connect builds on top of OAuth2 to define a
federation protocol. Optimized around the user consent
flows, OpenID adds identity-based information on top of
OAuth into the inputs and outputs.
SCIM Identifies User and Group Schemas for
Developers
SCIM defines the RESTful API protocol to manage and
Introducing API Security Concepts 6
specify user and group schemas and the properties on
them, including defining the markup for representing
things like first/last name, email address, actual address,
and phone number. It enables you to identify users within
groups so you can easily add or remove them, without
having to reinvent the API.
Different layers of the Neo-Security stack can be combined.
For example, OAuth is used to secure SCIM API
calls for instances like delegated access for creating and
updating users. SCIM and SAML or OpenID Connect can
be bound to provide just-in-time provisioning (JIT), which
allows you to create, update, and delete users without
tying it to an authentication event.
1.5 JSON Identity Suite
The identity-based information provided by OpenID Connect
is marked up in something called Jason Web Tokens
or JWTs (pronounced Jots.) JWTs are part of the JSON
Identity Suite that the Internet Engineering Task Force
(IETF) has defined. JWTs are designed to be light-weight
tokens that can be easily passed in that HTTP header.
They are like SAML tokens, but are less expressive, more
compact, with less security options, all encoded in JSON
instead of XML.
1.6 Neo-Security Stack Protocols
Increase API Security
Theres no doubt that security risk increases as more and
more APIs are opened up to connect and share information.
The technologies and procedures described in this
Introducing API Security Concepts 7
article aim to decrease vulnerability. Though the IETF has
outlined a set of protocols to guide API development and
exposition, API providers must educate themselves on
the language of security in order to avoid human error
and prevent API attacks.
1.7 The Myth of API Keys
There are many misunderstandings surrounding API security.
For one, API keys are not API security. API keys are
inherently insecure - essentially being a password that is
hardcoded into applications and often distributed all over
the place, giving anyone with the key access to the API.
OAuth is not API security either - simply adding OAuth to
an API does not make it secure. What an API needs is a
holistic approach to security, imbued with enterprise and
mobile security.
1.8 Access Management
An important API security case is user-to-user delegation.
This is when you give another person rights to access your
data instead of giving an app the rights to access your
data. This is made possible by using OAuth and OpenID
Connect with Delegated Tokens. A Delegated Token is
a form of OAuth Access Token that also contains user
information.
1.9 IoT Security
Securing APIs is important, but we need a holistic approach
to security. This is especially a challenge throughout
the IoT, since very important assets such as the lock
on our house or car will be made available online.
Introducing API Security Concepts 8
The dangers lie in the seams between the
devices and the Internet and that is what needs
to be carefully handled - Brian Mulloy, Apigee
According to Brian Mulloy, web developers know how to
handle security on the Internet using OAuth and OpenID
Connect. At the same time, device makers have experience
in securing the physical devices themselves. It is important
to think about security end-to-end, from physical
device all the way up to an app interacting with that device
via an API. One weak link can break the whole chain.
1.10 Using Proven Standards
Good API security is an enabler. Unless end users and
developers can trust your API, none of the business goals
you have defined will be fulfilled. Some reccomend that
you do not build your API security solution yourself, but
rather base your security on known standards and battle
tested products. Keep reading for actionable insights into
each section covered in this summary chapter.
2. The 4 Defenses of The API
Stronghold
At one point or another, your secure resources will be
attacked. This is the unfortunate reality of the modern
era, where the skills necessary to invasively crack open
a system, network, or API are more commonplace than
ever. Millions in resources and potential revenue can
be lost in a matter of hours due to poor planning or
implementation of a security protocol.
Private information, trade secrets, and even personal
data can be exposed to the skilled network penetrator
and used against you in ways that are as extreme as they
are varied. This chapter aims to bolster your defenses by
defining the four foundations of API security: Authentication,
Authorization, Federation, and Delegation.
The 4 Defenses of The API Stronghold 10
The Importance of Comprehension
One of the most common failures of understanding in
the development of API security is the idea that security
is a one size fits all solution. The idea that channels
of security function in a singular manner with variations
only in the final end-user experience is as wrong as it is
dangerous; this concept places the operator in a position
of fewer tools at their disposal than those trying to break
the system, in turn exposing your data to an extreme
level of unnecessary risk.
This issue is made worse by a common misunderstanding
regarding the differences between Authorization, Authentication,
Federation, and Delegation perpetuating
a gulf of misinformation and misapplication. This
chasm has caused many security woes in the API space.
Given that these four terms are what the entire concept
of API security rides on, it is imperative that you
understand them, their uses, and the implications of their
adoption. Lacking a basic understanding of security protocols,
methodologies, and concepts can mean the difference
between a prosperous, growth-oriented business
and a stagnant, deprecating business.
2.1 Balancing Access and Permissions
Having an API that allows for full access to the entirety
of your systems and resources is an absolute nightmare
its akin to being the lord of a castle, and leaving the
doors to your vault wide open it entices theft by its very
nature, and unnecessarily opens your materials to the
public space. As lord of your keep, why give marauders
an avenue for attack?
The 4 Defenses of The API Stronghold 11
What then is the proper response? Do we leave systems
open for the betterment of functionality and assume
users have positive intentions? Or do we follow a complete
opposite route, closing down every bit of functionality,
designing only proprietary systems?
The solution lies in combination of both approaches.
Assume your foe is out to get you at all times but
dont let this affect your need to do business. Constant
vigilance allows you to design your API in an intelligent
way, opening only that which needs to be opened, and
making sure those openings dont tie into vital systems
that could be damaged. Functionally, this means assigning
elements of authority to API consumers based on the
minimal amount of access they need to do the functions
they are required to do. By assigning different roles and
levels of responsibilities to clients, we can create a tiered
environment that keeps our data safe.
Understanding the implications of this system is of prime
importance specifically the differences between the
types of rights and authorities within the system as a
whole. In our definitions, well hark back to our castle
defense analogy. The brave and powerful knight Lancelot
is trying to return to the Arthurian court after a long
month of fighting bloodthirsty marauders lets see
what defenses he will have to pass
The 4 Defenses of The API Stronghold 12
2.2 Authentication: Identity
Tis I Lancelot cometh, bearing the password Guinevere. Authentication
is two-fold, establishing trust with identity and a
secret code.
Authentication is a base security layer that deals specifically
with the identity of the requesting party. Think of
authentication as an agreement based on trust. When
Lancelot reaches your drawbridge, he shouts his name
along with a secret code to a guard stationed on the
castle wall above. These two forms of identification will
ensure that Lancelot is identified only as Lancelot, and that
Lancelot is allowed to enter the castle.
In the real world, this level of security can take multiple
forms. When a user chooses to request data or resources,
they can face a number of protocols, log-in systems, and
The 4 Defenses of The API Stronghold 13
verification services. For instance, a user could log in using
an authentication service that only requires a username
and password. For greater levels of assurance, they may
then be asked to provide a single-use token generated on
a mobile device or keyfob.
2.3 Authorization: Access
Says here youre Round Table status. Authorization considers
what access level the user has with the system. [Image: CC-BYSA-3.0
via Wikimedia Commons]
Authorization is a completely separate level of security,
though its often confused with authentication; while authentication
verifies that the requester is who they say
they are, authorization determines the access level they
should be granted.
As Lancelot waits for the drawbridge to come down and
allow him in, the guard steps back and checks his Ye Olde
Book of Permissiones to make sure Lancelot has the right
to enter the castle. This is different from Authentication.
Whereas Lancelot proved he was who he said he was,
Authorization makes sure he has the right to enter the
The 4 Defenses of The API Stronghold 14
castle, and if he indeed has that right, what levels he can
access within the castle. These permissions are granted to
Lancelot by King Arthur, allowing Lancelot access to The
Round Table, among other resources that peasants cant
access.
Authorization is extremely important, but is often overlooked.
It is very easy for API developers to assume that,
because they need access to the API for their systems, setting
the user default permissions to SysOp or equivalent
full access is acceptable. This is a faulty line of thinking.
While the developer inherently requires a higher level of
access than the typical user, a consumer may only need
a small portion of calls or functions at any one time.
In that situation, leaving excess operations open makes
the system more vulnerable to hacks and unauthorized
access.
2.4 Federation: Reusing Credentials &
Spreading Resources
Federated security is a multi-purpose system:
for users, federated security systems allow for the
use of a small set of credentials with multiple systems,
services, applications, or websites.
for administrators, federated security allows for
the separation between the resources requested by
the user and the systems used to authenticate and
grant authority to the user.
For organizations, it allows them to centrally manage
the trust relationships they have with one another
and ensure, cryptographically, that that trust
is enforceable.
The 4 Defenses of The API Stronghold 15
Same User Credentials Across Multiple Services
With federation, the user is granted the ability to use
the same set of credentials across multiple services. By
having the authentication take place in one single domain,
other security realms that trust this primary domain can
reuse the authentication and trust the authenticity of the
identity established. This results in what is to what is
called a federation.
Any system in this federation can accept the credentials of
the authentication domain. The primary domain is what
we call an Identity Provider (IdP) or Asserting Party (AP);
the other security domains that trust the IdP to authenticate
users are referred to as Relying Parties (RP) or
Service Providers (SP). Authentication and identity data
are passed between these parties using tokens. These Tokens
are minted by a system called a Security Token Service
(STS) or a Federation Service (OAuth Authorization
Server and an OpenID Connect Provider are examples of
an STS and a Federation Service, respectively.)
The end result is that a STS hands a token to the user after
they first log into that authentication service. When the
user then requests access to another domain, the domain
registers that the user already has a token, and grants it
access without requesting another log-in.
