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.