API Workshop Amsterdam presented by API Architect Ronnie Mitra

Building an API Strategy:

Introduction and the Business of APIs

Ronnie Mitra

Principal API Architect - Europe

Layer 7 API Academy

API Management

virtual cloud on-premise

API Academy

Mike Amundsen Ronnie Mitra

www.apiacademy.co

Business Drivers

API Styles

-- Break --

The Developer Experience

API Architecture

Securing APIs

-- Break --

Principles of URI Design

Agenda

What are Web APIs?

Connecting things

Connecting computer programs

API

All programmers are API designers

Connections between modules

Language Dependant

APIs are constrained by the syntax of the language

… over the web

Web APIs

Language Independent

APIs are constrained by the syntax of the web

Most API Design principles can be applied

Some design principles are unique to Web APIs

Web of

Documents

Web of

Apps Web of

Services

Web of

Things

The web is ubiquitous

And universally accessible

Publishers retain control

Private/Partner or Closed APIs

Acme Corp. API

Acme Corp. App

Public or Open APIs

Acme Corp. API

Third Party App

Priority: Lower Cost

Priority: Increased Adoption

why build an API?

Innovation

Consumer Reach

Revenue Source

Marketing

Integration

Light Bulb designed by Jean-Philippe Cabaroc from The Noun Project

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Revenue Source

Revenue Source

http://www.flickr.com/photos/inside-south-africa/485356704

£0.10 per API Call

Revenue Source

1000 calls/month

5000 calls/month

Revenue Source

500 calls/month

1000 calls/month

5000 calls/month

Revenue Source

Is your content worth paying for?

Revenue Source

Internal Revenue (chargeback)

Cost Reduction

Revenue Source

Strategy Implications:

• Maximize uptime and reliability

• Target high revenue consumers

• Competitive differentiators are a must

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Consumer Reach

Consumer Reach

Platforms are not forever!

Consumer Reach


• UX driven interfaces

• Specialization may be required

• Difficult to update applications

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Marketing

Affiliate Programs

Sometimes you pay the developer.

Marketing

Draw new visitors in.

Marketing

Marketing

Stay above the noise:

New channels

Information-centric marketing

Marketing


• Terms and Services are very important

• Identify and reward top performers

• Limit calls and restrict access when needed

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Innovation


Innovation from within

Innovation


Innovation outside your borders

Innovation


When does innovation happen?

Innovation



• Design interface for general use

• Identify success stories

• Eliminate misuse

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Integration

Business driven integration

Regulatory driven integration

Integration


• Reduce cost

• Reduce cost

• Reduce cost

Observational Learning: Five Famous Stories of Public APIs

2000 – ebay

Started with a paid developer program in 2000

Made it free in 2005

Consumer Reach

Marketing

Large developer eco-system Large app eco-system

25% of eBay listings come from their API!

salesforce

2000 – salesforce

Integration

Revenue Source

API as a cloud enabler

2004 – Flickr

web 2.0 generation the social evolution

Consumer Reach

Marketing

The rise of self-service Announced 6 billion photos in August 2011

2006 – Amazon Web Services

Started as an online book shop… Became a department store…

now?

Jeff Bezos Connect everything

http://www.flickr.com/photos/zippy/2430495092

2004: Hey, why don’t we sell this?

Revenue Source

Estimated revenue: $1.5B in 2012

http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise

Twilio or stripe

2007 - Twillio

Revenue Source

The API is the business

100,000 developer milestone in 2012

Web API Modern Timeline

2000

Salesforce API ebay API

2002

Amazon API

2004

Flickr API 2006

Twitter API Facebook API Google (Maps) API

2012

Programmableweb.com has 7144 registered APIs

Sources: apievangelist.com

programmableweb.com

internetarchive.com

Steve Yegge Rant

oreilly.com

2005

ebay makes APIs free

2004

First Web 2.0 Conference

2010

Salesforce adds HTTP API

2008

Programmableweb.com has 1000 registered APIs

2005

Programmableweb.com launched 54 APIs registered.

Original APIs are still successful

New business models have emerged

Know your drivers – design accordingly

Summary


Introduction and the Business of APIs

Ronnie Mitra


Layer 7 API Academy


URI Style Design Tips

Ronnie Mitra


Layer 7 API Academy

URI Style

GET PUT

POST DELETE

+ URI

URI Style

GET /students/1232

URI Style

• familiar to web developers • designed for HTTP • URIs are intuitive

Advantages

URI Style

• limited to HTTP methods • URI design is not standard • can be ‘chatty’

Trade-offs

What is ‘good’ API Design? • Easy to learn

• Easy to use, even w/o documentation

• Hard to misuse

• Easy to read and maintain code that uses it

• Sufficiently powerful to satisfy requirements

• Easy to extend

• Appropriate to audience

Joshua Bloch, Principal Software Engineer, Google.

Principles of URI Style API Design

• URIs should be intuitive and ‘hackable’

• The interface should adhere to standards (RFC 2616 and RFC 3986)

• The design should be extendable

Naming URIs

• Names matter!

• Establish reserved words and key words

• Names should be meaningful (to the application developer)

Naming URIs – Examples

Bad: • /Core_Items_DSTSM_1

Good: • /charges

Defining Resources

• Translate interactions into nouns

• Build a resource model

• Avoid RPC/Tunnel style names

• Not everything fits well into the CRUD + Object space

Map Interactions

Interaction: “retrieve all my user’s messages” Object: Message

Resource Model

Message

Title

Author

Body

Recipient n n

n

1

n

1

n n

Avoid RPC Names

Interaction: “Retrieve newest messages” RPC-style Name: getNewMessages

Not Always Easy

Interaction: “Perform a spell-check on this message” Object: Message? What method is ‘spell-check’?

Not Always Easy

Interaction: “Perform a spell-check on this message” Object: SpellChecker

Types of Resources

Lots of nouns A few operators or controllers

Relationships

myapi/messages

myapi/messages/14

myapi/messages/title

myapi.com/ronnie/messages/title

Relationships

Don’t expose relationships unless they are useful to the developer

Each path segment should be actionable

HTTP Methods

• GET • PUT • POST • DELETE • HEAD • OPTION • TRACE • CONNECT

GET

• Retrieve a representation

• ‘safe’ method according to RFC

• no user-requested side effects

• won’t impact data

• ‘Conditional GET’ is supported with caching

• Don’t abuse for non-read operations

PUT

• Write a representation

• Store the entity (full replacement)

• Idempotent

• Example:

PUT /myapi/messages/14

{Message}

Idempotence

No side-effects on identical calls PUT /myapi/messages/14

Result: Message Replaced


Result: Message Replaced

Full Replacement


{ “title”: “Welcome”}

{ “id”:”14” “title”:”Wlecome” “author”:”Ronnie” “body”: “Hi Glen, welcome to the team!” }

On the Server: { “title”:”Wlecome” }

Why not use PUT for partial update?

• Breaks HTTP specification

• No defined semantic – can produce unexpected results from a dev perspective

PATCH (Partial Update)

• RFC 5789 (HTTP Patch)

• Partially update an identified resource with the supplied entity

• Example:

PATCH /myapi/message/14

{Partial Message}

Patch Media Type

• RFC 6902 – JSON Patch

• Content-Type: application/json-patch+json

PATCH /myapi/message/14 HTTP/1.1

[

{ "op": “replace", "path": "/subject", "value": “new" },

{ "op": “add", "path": "/tags", "value": “urgent" }

]

Challenges with PATCH

• Not part of HTTP 1.1 spec

• Not widely adopted in implementations

• May not be familiar to developer audience

How do I implement PATCH in an environment that doesn’t

support it?

PATCH Workarounds

Turn the target data into a URI object:

HTTP PUT /myapi/messages/14/title

PATCH Workarounds

Tunnel the patch with a custom header:

X-HTTP-Method-Override: PATCH

PATCH Workarounds

Use a unique URL:

HTTP POST /myapi/patches/messages/14

HTTP POST /myapi/messages/14/patches

HTTP POST /myapi/messages/14;patch

PATCH Workarounds

Use PUT and break the specification

POST

• Write/Process an entity

• Accept entity as sub-ordinate resource

• Not Idempotent

• No identifier specified (factory pattern):

POST /myapi/messages

Non-Idempotent


Result: Message #14 Created


Result: Message #15 Created

DELETE

• Delete identified resource

• Example:

DELETE /myapi/messages/14

• Idempotent

Method Tunneling

• Older platforms may not support all verbs

• Need to resort to embedding the verb in a header or parameter

• Example:

GET myapi/shops?method=POST

• Avoid doing this

Representations

Expose object properties that are relevant to the developer

Embed child objects and properties, but need to decide on granularity

Design structures that are extensible – be careful when implementing schema

Representations - Granularity

{ “id” : “14” “title” : “Welcome” “body” : “Hello!” “author” : “38820” }

Representations - Granularity

{ “id” : “14” “title” : “Welcome” “body” : “Hello!” “author” : [ “id” : “38820”, “firstName” : “Ronnie” ] }

Representations – Granularity Considerations

Chattiness vs. Latency

Frequency of change

Interaction (what data is needed?)

Retrieve a Collection of Data

• Example: “Retrieve all store locations”

• GET /shops

Retrieve a Filtered Collection of Data

• Filter by requesting children

• GET /shops/london

• GET /shops/amsterdam

• Limited to objects and sub-objects

• Difficult to retrieve unions/joins of data

Retrieve a Filtered Collection of Data

• Example: “Retrieve all store locations in London”

• Use query parameter from URI spec

• GET /shops?location=London

• GET /shops?location=London,Amsterdam

• GET /shops?location=London&sort=distance

Complex Queries

“retrieve all shops within a radius of 10 km from a specific location that are open within specified hours and sell specific phones, devices and account plans”

GET /shops?radius=10&location=8882,28832&open_time=38882034&close_time=23882343&phones=iphone,blackberry,samsung&plans=monthly_3GB,monthly_4GB,pay_go_2GB

Complex Queries

URI space may be limited

Long queries can become difficult to manage

Use POST on an operator resource:

POST /shopsquery

{

“radius” : “10”, “location” : “388203,838200”,

“phones” : [“blackberry”, “iphone”]

}

Returning Collections

• array of results

• all properties and child elements?

• collection responses can be BIG!

Pagination

• Just like websites – break data up into manageable ‘pages’

Pagination

• data page mechanism

/api/resource?page=3

• fixed page size

Page 1 Page 2 Page 3 Page 4 Page 5 Page 6

• easy to navigate

Pagination

• offset + count mechanism

/api/resource?offset=10&count=20

• client app dictates page size

10 30

• client calculates offset and count for pages

Pagination

• use links to navigate

{“href”:“/api/resource?offset=11&count=20”, “rel”:“next”}

• client doesn’t have to calculate location

• easier to navigate through pages

Pagination

• use defaults to reduce ‘friction’

• reduces learning curve for new developers


/api/resource


Field Projection

•‘property selection’, ‘zooming’

• Collections can be too big for some client

• Allow client to select properties in representations

Field Projection - Example

GET /myapi/messages?fields=title,body

{

[{“id”: “1”, “title” : “hi!”, “body” : “hello”}…]

}

Linking

• Use links as identifiers

{

[

{“id”: “/myapi/messages/13”},

{“id”: “/myapi/messages/14”}

]

}

Linking

Advantages:

• Developer doesn’t need to construct URI

• URIs can change!

Trade-offs:

• Query parameters increase complexity

Implementing Linking

Lots of Standards:

• HAL

• SIREN

• Collection + JSON

• ATOM

• XML LINKING

• HTML

Implementing Linking

Lots of APIs just do this:

{“link_name” : “link”}

Implementing Versioning

• myapi/v1/path • Try to extend instead of version • Don’t break what is already there • Clients should ignore what they don’t understand

• Introduce breaking changes if you want to drive developers away.

Content Types

• XML • JSON • HTML

XML

• Not the same as SOAP / Tunnel Style

• Widely used (AJAX, mobile, server)

• W3C Standard, RFC 3023

JSON

• Usage rising

• Popular amongst next-gen developers

• JavaScript everywhere

• RFC 4627

XML vs. JSON?

• Not very different

• ‘<‘ vs. ‘{‘

• Similar performance overhead

• Most clients support both (XML more widely supported)

• What do your developer’s prefer?

HTML

• Hypermedia content type

• Web Form: application/x-www-form-urlencoded

• Useful for simple name/value pair input

• Easy for developers to implement

Selecting a Representation

• Content Negotiation • HTTP Accept Header

• URI based • /myapi/messages.xml

Status Codes

• 1xx: Informational • 2xx: Success • 3xx: Redirection • 4xx: Client Error • 5xx: Server Error

Status Codes

• You MUST use the correct category

• The second part of the code (xx) is largely informational, but still important

• Reason phrases can be customized

Status Codes

Client libraries should handle status codes and act in an expected manner

Error Handling

• You might include an application level error code • Definitely Include a human readable error message

A Few Interactions

Asynchronous Request

Client Resource

202 Accepted

Fire and Forget

Asynchronous Request

Client Resource

202 Accepted

<link href=“…” rel=“status”/>

Status

Resource

200 OK

<status>complete</status> <link href=“…” rel=“result”/>

Server Callback

Client Resource

Register

200 OK

200 OK

Notify

Server Event (Long Poll)

Client Resource

Block and Wait

200 OK

HTTP Abuse

Optimizations

Optimizations

• Mobile and device platforms have unique bandwidth constraints

• Transport Level (HTTP)

• API Design

HTTP Optimizations

• Compression • Negotiation (Accept-Encoding) • Example:

• Is JSON more efficient than XML?

Accept-Encoding: compress, gzip

HTTP Optimizations

• Pipelining

• Multiple requests without waiting for response

• Supported in HTTP 1.1 (persistent connections)

• Idempotent actions only

API Design Optimizations

Reduce data size (pagination, field projection)

Reduce number of calls: • Composition • RPC batch • Caching

Composition

URI style APIs can be chatty

Combine interactions and expose on the server

Example:

/myapi/composer

Batching

URI style APIs can be chatty

Combine and invoke calls on the client

Can be complicated for the developer

Caching

Many forms of caching HTTP Caching avoids use of network Widely supported

Adaptive Responses

• Provide responses that are the best fit for the calling application •Examples: • Reduced granularity • Different defaults • UI Driven

URI Design Summary

• Some standards, but lots of choices • Design with developer in mind • Consistency and structure are important


URI Style Design Tips

Ronnie Mitra


Layer 7 API Academy



Ronnie Mitra


Layer 7 API Academy

designing APIs can be difficult

http://www.flickr.com/photos/nirufe/3469696707

?

Usability

Reliability

Simplicity

Security

Etc…

Software Qualities

Focus on the developer experience

(dx)

Interaction Design

Bill Moggridge

Usability

Human-Computer-Interaction

User Experience Design

Goal Oriented Design

http://www.flickr.com/photos/58754750@N08/5541472392/

A user-centric view of design.

Well designed products are easier to use.

Good design matters for Web APIs too.

Priority: Lower Cost

Priority: Increased Adoption

Portal

API

Portal

API

Developer

End User

Administrator

Portal

API

This is obvious right?

Why is this difficult to do in practice?

Reason #1

We project our own perspective.

Reason #2

We project our own biases.

Never use SOAP?

Why?

Consider keyboards…

http://www.flickr.com/photos/yvettemn/139890573/

http://www.flickr.com/photos/jonathanpberger/7126054997/

http://www.flickr.com/photos/novemberborn/286773981/

OR

It doesn’t matter that you don’t like SOAP.

What matters is what your developer base thinks!

(and what your objective is)

Reason #3

We make bad assumptions.

API publishers are also developers.

“I built a mobile app once.”

Reason #4

We lack the time, money or incentive for good design

“Best practices”, patterns and standards become shortcuts

Am I RESTfull enough?

So, how can we do better?

Developer-centric design requires effort and diligence.

Design with the developer in mind.

Ask them.

• Interviews

• Surveys

• Listen (blogs, presentations, tweets)

+

• Observe

• Prototype

• Analyze Historical Data

Consider all aspects of the DX:

Registration

Security

Troubleshooting

Learning

Interface Style

A Good DX = A Good System

Tunnel Style

URI Style

Hypermedia Style

Event Driven Style

Registration

Lazy Registration

Social Integration

Personalization

Development Activity Cycle

1. Learn

2. Code

3. Implement

4. Test

5. Fix

Portal

API

Learn

Code

Test

API

Learn

Test

API explorers and “live documentation” can shorten the

gap between visibility and feedback.

Learning

WADLs and WSDLs are nice

But provide real documentation for humans!

Hypermedia =/= zero documentation

TLS OAuth 2

Open ID Connect

Security

Security can hurt Usability

But… security can also improve the overall experience!

We need to think about the system as a whole

Complexity

• Sometimes complexity is necessary – that is ok

• Enough features to meet requirements

• Don’t hurt the DX – use structure and modularity

Structure and Consistency

Define a consistent Message Structure

{ “Response” : { “Errors” : {} }}


Define consistent standards for: • Naming • Collection structure • Content negotiation • Links


Enforcing standards requires organizational discipline

Especially difficult in large organizations!

Modularity

Partition APIs into modules or products From a DEVELOPER perspective!

“Frictionless” integration High rates of adoption Low cost integration

We want:

Behaviour Design

BJ Fogg

Visitor Invested Developer

Joy

Visitor

Invested Developer

Joy

Joy

A Sample DX Based Design Process

1. Define the problem space

2. Design interactions

3. Map the interaction to an API style

4. Prototype and get feedback

5. Iterate

The Problem Space

Why are we doing this?

Who are we building it for?

Innovation

Consumer Reach

Revenue Source

Marketing

Integration


Consider:

Platforms

Organizations

Languages

Who is this for?

The Problem Space

What are our:

Assumptions?

Constraints?

Shared terms and jargon?

Data Gathering

How do we learn about our target audience?

Interaction Model

Define requirements:

What interactions will benefit the developer?

What information is required to support the interaction?

Interaction Model

As a ___ I want to …

Map Interactions to an API Design

Which style?

Which formats?

How do we translate interactions?

Prototype

Don’t bind to real data or backend

Use something lightweight and easy to change

Do this early

Practical Prototyping

Write simple code or script in a language that is easy for you to implement.

var express = require('express'),

app = express();

var port = 8080;

app.listen(port);

app.get("/tasks", function(req, res) {

res.status(200).send(‘<response>

<tasks>

<task>

<name>Pick up Kai</name>

<priority>1</priority>

</tasks>

</response>’);

}


Configure an interface in a web or API platform

GET /tasks


Apply minimal security

Try writing throwaway client code

Ask target developers to write code and use the API

Make quick changes and try it again

Focus on the interactions that take place, rather than the interfaces

we expose

DX > Software Qualities

Usability Summary

• Focus on the developer

• Start by thinking in terms of interactions

• Effective for public and private APIs

Great API design can thrive in a developer-centric environment



Ronnie Mitra


Layer 7 API Academy


Architecture Foundations

Ronnie Mitra


Layer 7 API Academy

Architecture

http://www.flickr.com/photos/naomi_pincher/3306312873/

Layered Pattern

Representation Layer

Component != Connector

Component

Database

File System

Message Queue

Transaction Manager

Source Code

Components Are Private

Connector

Web Server

Browser Agent

Proxy Server

Shared Cache

Connectors Are Public

Client Server Connectors

Components

The Web

Representation Layer

Representation happens in the Connector

HTTP supports content negotiation

- Accept

- Content-Type

Differing clients (user-agents) === differing representations

- Desktop

- Browser

- Tablet

- Smartphone

Be prepared to support multiple representations

• Data and Interface Transformation • Focus on the interface (usability)

Representation

SOAP

Legacy

Security Layer

Security implementations are difficult:

• Mistakes are costly • Hard to understand specifications • Performance can suffer

Don’t implement API security in the implementation Enforce security at the edge

Where?

Caching Layer

Caching Layer

Caching Layer

Caching happens EVERYWHERE

HTTP supports Expiration Model and Validation Model Caching

Expiration Model

- Expires

- Cache-Control: max-age

Validation Model

- Last-Modified

- Etag, If-Match

Be prepared to support caching for both client and server

Squid, Varnish, Nginx, MemCacheD, NSURLConnection etc.

Orchestration Layer

• Chaining multiple calls • Aggregating and enriching data • ‘mashup’ external data with internal data

Orchestration:

Gateway Pattern

Abstraction of multiple interfaces

In Software Engineering: Façade Pattern

Benefits:

- Deliver a consistent experience

- Centralize API functionality

http://martinfowler.com/eaaCatalog/gateway.html

API Gateway

Gateway

API

API

Restrict Access Improve Performance Focus on Usability

The gateway doesn’t solve all our problems

API portals

Portal

API Management

Portal

Gateway

API

API

Nuts and Bolts of API Management

Developer Registration

Access Control

API Explorer

API Documentation

Social Engagement

Tracking and Reporting

We also apply this philosophy behind the firewall.

Architecture Summary

• Use a layered architecture

• Deploy a gateway for runtime

• Deploy a portal for developers


Architecture Foundations

Ronnie Mitra


Layer 7 API Academy


The Security Challenge

Ronnie Mitra


Layer 7 API Academy

The API security challenge:

Balancing Control and Accessibility

Identity Authentication Authorization Availability Integrity Privacy

Attack Surfaces and Identities

Portal

API

Developer

End User

Administrator

Portal

API

Developer

End User

Administrator

API

End User

Injection Attacks

Utilizing input parameters to inject data that compromises

the security of the targeted system.

Examples:

- SQL Injection

- Command Injection

- Code Injection

- Argument Injection

API Attack Example:

SQL Injection Attacks: APIs

GET http://host.com/aresource?token=

%E2%80%98or%20%E2%80%981%3D1

GET http://host.com/aresource?token=‘ or ‘1=1

select * from tokens where token = ‘’ or ‘1=1’;

APIs May Be A Direct Conduit

292

HTTP

Server

App

Server

Database

App

Objects

Often: • Self-documenting

• Closely mapped to object space

Denial Of Service Attacks

An attack which has the objective of making a service

unavailable to all users

Examples:

- XML/JSON parser attacks

- Jumbo messages

- Server overload

Overflow Attack

Intentionally sending too much data in order to exploit a

target systems by exceeding expected boundaries.

Examples:

Buffer Overflow

Cash Overflow

Cross Site Scripting (XSS) Attack

Embedding code within a server that will be

transmitted to users.

XSS API Example

296

Attacker

Web App Server

(browser+APIs)

Victim: Web

Browser

Client

<SCRIPT …>

1. API injects

script in

3. Browser loads

content with

embedded script

2. Server fails to

perform FIEO: Filter

Input, Escape Output

API

Interception of communication between two systems.

Man in the Middle Attack

OWASP Top Ten (2010 Edition)

Source: http://www.owasp.org/index.php/Top_10

http://www.owasp.org/index.php/Top_10

http://www.owasp.org/index.php/Top_10

Impersonating a registered application in order to access

an API resource.

Examples:

- Guessing application ID by brute force

- Retrieving application ID by sniffing traffic

- Cracking application to retrieve application ID

App Spoofing

how can I protect identity on a mobile device?

…

what happens if my mobile app is impersonated?

API

End User

Revenue Source

What the Fudge*! I didn’t make 10000 calls yesterday!!!!!!

I’m not paying that.

*This is what WTF actually stands for.

I didn’t buy 1000 mobile phones in

Russia!

I’m not paying that!

Forrester:

we are moving towards a ‘zero-trust’ model

New platforms, new languages:

• Ruby on Rails

• Node.js

• Scala

• Nginx

• Squid/Varnish/Traffic Manager

TLS OAuth 2

Open ID Connect

OAuth provides a

Delegated Authorization Framework

An imperfect analogy….

http://www.flickr.com/photos/drewleavy/5587005480

http://www.flickr.com/photos/24oranges/5791460046/

http://www.flickr.com/photos/grumbler/571106054/

http://www.flickr.com/photos/roboppy/238406811/

Your Money

This Shop Needs Your Money

You need to grant access to your money

http://www.flickr.com/photos/drewleavy/5587005480

I won’t tell.

I promise!

www.flickr.com/photos/auntiep/255249516

Granting access to someone to act

on your behalf.

Your resources

This app needs to act on your behalf

You need to grant access to your resources

Your google+ data

This app needs to access your Google+ data

You need to grant access to your resources

Hi Google.

I’d like to have access to a user’s data.

Hang on, let me ask…

He said yes. Here is your access code.

“Client” == application

“Resource owner” == end-user

The first step to understanding OAuth 2:

OAuth 2 Grant Types

- Authorization Code

- Implicit

- Resource Owner Password Credentials

- Client Credentials

Authorization Code Grant

326

Client Application

Resource Owner

Using

Application

Resource Server

I Wish I could access my resources through

this application…


327

Client Application

Resource Owner

Using

Application

Resource Server

…but I don’t trust this app enough to give it

my credentials.


Initiation

328

Client Application

Resource Owner Authorization Server

Resource Server

User Agent

Issue GET

request via

User-Agent


Initiation

329

Client Application


Resource Server

User Agent

Issue GET

request via

User-Agent

response_type

client_id

redirect_uri

scope

state

OAuth 2 Authorization Request

response_type – indicates grant type

client_id –application identifier

redirect_uri (optional) – address which the UA can use to respond to client

scope (optional) – space delimitted string: what the client wants to do

state (optional)– opaque string used to defeat CSRF attacks

Sample Authorization GET URL:

https://azserver/oauth2/authorize?response_type=code&client_id=my_id&state=state&r

edirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback


Resource Owner Authentication

331

Client Application


Resource Server

User Agent

Send

User

Authentication

Form

?

Authenticate


Authorization

332

Client Application


Resource Server

User Agent

Deliver

Grant

Screen

? ? ?

Approve

Grant

Request


Receipt of Authorization Code

333

Client Application


Resource Server

User Agent

Redirect

User-Agent

Client

Application

! Redirected

To

Client

Application

code

state

302


Access Token Request

334

Client Application


Resource Server

Request

Access

Token Return

Access

Token

and Optional

Refresh Token

grant_type

code

redirect_uri

client_id

200

AZ Code

AZ Code


Access Protected Resource

335

Client Application


Resource Server

Request

Resource

Using

Application

Return

Resource

200

Authorization Code Grant - Summary

Most Complex of OAuth 2 Grant Types

Provides full OAuth 2 capability

2 vs. 3 Legged Spectrum

337

Three

legged

Two

legged

OAuth 2 Challenges

It is a framework

OAuth 2 Challenges

New attack surfaces

Flexible, but complex for API publishers to implement

Utilizes redirection URIs (should be validated with strong rules)

Poor implementations will be exposed (see Facebook)

Not a solution to user authentication

OpenID Connect

Identity Access and Authentication (when combined with Open ID)

Built on top of OAuth 2

Not tied to any single vendor or identity provider

Open ID, Open ID Connect and OAuth 2

OAuth 2 allows an end-user to grant an application access to protected resources

However:

- The authorization server must still authenticate the end-user

- The client application is unable to determine information about the end-user

Client Application


User Agent

Send

User

Authentication

Form

?

Authenticate

OpenID Authentication can help the server authenticate the end-user

OpenID Connect provides a mechanism for the application to learn about the end-

user

Open ID, Open ID Connect and OAuth 2

Client Application


User Agent

Send

OpenID

Authentication

Form Authenticate

Retrieve User

Information

OpenID

Resource

Server

Portal

Who is using the API? How are they (mis)using it?

What would happen if the portal was exploited?

Portal

API

Developer

End User

API

Portal

API

Administrator

Where are the components deployed? Who owns the identity store?

Portal

API

Summary:

Challenge: Balancing Usability and Security

Old Threats Still Exist

New Styles and Access Models create new surfaces


The Security Challenge

Ronnie Mitra


Layer 7 API Academy

Technology

API Workshop Amsterdam presented by API Architect Ronnie Mitra