rest api security

REST API Security

Les Hazlewood @lhazlewood

PMC Chair, Apache Shiro

Expert Group Member, JEE Application Security (JSR-375)

Founder & CTO, Stormpath

About Stormpath

• User Management API for Developers

• Password security

• Authentication and Authorization

• LDAP & Active Directory Cloud Sync

• Instant-on, scalable, and highly available

• Free for developers

Overview

• HTTP Authentication

• HTTP Authentication Schemes Comparison

• API Key Authentication

• Token Authentication

• Authorization

REST API Focus

• Eliminate server state

• Secure user credentials

• Secure server endpoints

• Expose access control rules

• SPAs and Mobile: ‘Untrusted Clients’

Learn more at Stormpath.com

https://stormpath.com/?utm_source=slideshare&utm_medium=slide link&utm_campaign=rest security webinar slides

HTTP(S) Authentication & Authorization



Authentication

Proving you are who you say you are.



Authorization

Ensuring someone is allowed to do what they

are trying to do.



HTTP Authentication & Authorization

• Authorization header

• No Custom Headers!

• Stay spec-standard

• No pre-flight CORS requests (browsers) req’d

• Custom schemes easily supported



Authorization header

How does it work?



Authorization header

How does it work?

Challenge Response protocol



1. Request

GET /admin HTTP/1.1



2. Challenge

HTTP/1.1 401 Unauthorized

WWW-Authenticate: scheme-name <stuff>

*multiple schemes allowed, typically set as multiple WWW-Authenticate headers



3. Re-Request

GET /admin HTTP/1.1

Authorization: scheme-name <stuff>



Example: HTTP Basic Authentication



1. Request (Basic)

GET /admin HTTP/1.1



2. Challenge (Basic)

HTTP/1.1 401 Unauthorized

WWW-Authenticate: Basic realm=“MyApp”



3. Re-Request (Basic)

GET /admin HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==



Schemes

• Basic

• Digest Schemes (OAuth 1.0a)

• Bearer Token Schemes (OAuth2)

• Custom



HTTP Basic



HTTP Basic

String value = username + ‘:’ + raw_password

String schemeValue = base64_encode(value)

...

GET /admin HTTP/1.1

Authorization: Basic schemeValue



HTTP Basic

Pros:

• Very easy to use

• Supported by everything

Cons:

• Raw password always transmitted

• Easy to leak raw password if not careful (logging)

• Susceptible to Man-In-The-Middle attacks

• HTTPS *always* required

• Client must constantly retain/reference the raw password (server clients usually ok, browser clients not ok)



Digest Schemes



Digest Schemes: Client

request.headers[‘Client-Id’] = getMyId()

String digest = hmacSha256(request, password)

String val = ‘Foo ‘ + digest

request.headers[‘Authorization’] = val

send(request)



Digest Schemes: Server

String clientId = request.headers[‘Client-Id’]

byte[] password = lookupPassword(clientId);

String serverComputedDigest =

hmacSha256(request, password)

String val = request.headers[‘Authorization’]

String clientSpecifiedDigest = val.remove(‘Foo ‘)

if (clientSpecifiedDigest != serverComputedDigest) {

sendError(401, response)

return

}

//otherwise request is authenticated



Digest Schemes: OAuth 1.0a example

Authorization: OAuth realm="http://sp.example.com/",

oauth_consumer_key="0685bd9184jfhq22”,

oauth_token="ad180jjd733klru7",

oauth_signature_method="HMAC-SHA1",

oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",

oauth_timestamp="137131200",

oauth_nonce="4572616e48616d6d65724c61686176”



Digest Schemes

Pros:

• Probably most secure

• Password never sent over the wire

• HTTPS not required (but your data may still require HTTPS)

• Can guarantee end-to-end HTTP message authenticity(HTTPS cannot do this)

• Not susceptible to Man-In-The-Middle attacks

Cons:

• Very difficult to design safely

• Difficult to understand and use

• Difficult to implement libraries

• Client still must retain a constant reference to the password(server clients usually ok, browser clients not ok)



Bearer Token Schemes




Authorization: Bearer opaque-token




• opaque-token can be whatever you want*

• *should always be cryptographically-signed

and expire



Bearer Token Schemes: OAuth 2 Example

Authorization: Bearer eyJ0eXAiOiJKV

1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3M

iOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzOD

AsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc

19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-

92K27uhbUJU1p1r_wW1gFWFOEjXk




Pros:

• Easier to use than digest

• De-facto standard token format (JWT)

• Can contain state – no server sessions needed

• Does not require constant access to the user password

Cons:

• HTTPS always required, during and always after login (not a big deal nowadays)

• Cannot guarantee end-to-end HTTP message authenticity (like digest schemes can)

• Susceptible to Man-In-The-Middle attacks

• Token creation and renewal workflows can be very complicated and confusing depending on use case (OAuth2 confuses many people).

• When used for Browser or Mobile, additional security still required (Origin checks, CSRF-protection, etc)

• Token content is not standard – applications can open themselves to attack



Custom Scheme



Custom Scheme

• Only if you really, Really, REALLY know what

you’re doing.

Seriously.

No, rly. Srsly.

• Non-standard, so you essentially must

provide your own client libraries.



Custom Scheme

• Stormpath has a custom SAUTHC1 digest scheme

• Authenticates the entire HTTP Message, including the Body (OAuth 1.0a does not)

• Uses nonces to prevent replay attacks

• Uses key derivation algorithms and HMAC-SHA-256

• We use it for our own SDKs*

• If you’re curious:

https://github.com/stormpath

(search for ‘sauthc1’ in any stormpath-sdk-* project)

*Basic still supported for non-SDK clients or ‘weird’ environments


https://github.com/stormpath


API Key Authentication



API Key Example

ID : YLNVXG091ZO1BSANZ5U6DCTIX

Secret:

ZediwUeDCNl13ldjaFKFQzz0eD13PO931DLAopdeywixaeUAhsip+92iaY



API Keys

• Entropy

• Password Independent

• Scope

• Speed

• Limited Exposure

• Traceability



API Keys

• Can be thought of as a really long username and password pair.

• Can be used with any HTTP Authentication Scheme that accepts a username and password: Basic, Digest, OAuth2, etc.

• Almost exclusively used for server-to-server communication.

• Never embed API Key secrets in untrusted clients like JavaScript or mobile applications.



HTTP Basic with API Key

String value = apiKeyId + ‘:’ + apiKeySecret

String schemeValue = base64_encode(value)

...

GET /admin HTTP/1.1

Authorization: Basic schemeValue



Token Authentication



Why not just use Session IDs?



Session ID Problems

• They’re opaque and have no meaning

themselves (they’re just ‘pointers’).

• Service-oriented architectures might need a

centralized ID de-referencing service



Session ID Problems

• Opaque IDs mean clients can’t inspect them

and find out what it is allowed to do or not - it

needs to make more requests for this

information.

• Susceptible to CSRF attacks



Session ID Problems

• Sessions = Server State!

• You need to store that state somewhere

• Session ID look up server state on *every

request*.

• Really not good for distributed/clustered apps

• Really not good for scale



Token Authentication to the rescue!



How do you get a Token?



Example: your SPA, your server



1. Token Request

POST /token HTTP/1.1

Origin: https://foo.com

Content-Type: application/x-www-form-urlencoded

grant_type=password&username=username&password=

password

*Assert allowed origin for browser-based apps



2. Token Response

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

{

"access_token":"2YotnFZFEjr1zCsicMWpAA",

“token_type":"example",

“expires_in":3600,

"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",

"example_parameter":"example_value”

}



3. Resource Request

GET /admin HTTP/1.1

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA



Example: Token Request using an API Key

POST /token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=apiKeyId&cli

ent_secret=apiKeySecret

*Assert allowed origin for browser-based apps



How does the server create a Token?



JSON Web Tokens (JWT)

• A URL-safe, compact, self-contained string with

meaningful information that is usually digitally

signed or encrypted.

• The string is ‘opaque’ and can be used as a

‘token’.

• Many OAuth2 implementations use JWTs as

OAuth2 Access Tokens.




• You can store them in cookies! But all those

cookie security rules still apply (CSRF

protection, etc).

• You can entirely replace your session ID with

a JWT.




In the wild they look like just another ugly string:

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEjXk




But they do have a three part structure. Each

part is a Base64-encoded string:

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEjXk

Header

Body (‘Claims’)

Cryptographic Signature




Base64-decode the parts to find the juicy bits:

{"typ":"JWT","alg":"HS256"

}

{"iss”:”http://trustyapp.com/”,"exp": 1300819380,“sub”: ”users/8983462”,“scope”: “self api/buy”

}

tß´—™à%O˜v+nî…SZu¯µ€U…8H×

Header

Body (‘Claims’)

Cryptographic Signature




The claims body is the best part! It can tell:

{

"iss”:”http://trustyapp.com/”,

"exp": 1300819380,

“sub”: ”users/8983462”,

“scope”: “self api/buy”

}

Who issued the token





{


"exp": 1300819380,

“sub”: ”users/8983462”,


}


When it expires





{


"exp": 1300819380,

“sub”: ”users/8983462”,


}


When it expires

Who it represents





{


"exp": 1300819380,

“sub”: ”users/8983462”,


}


When it expires

Who it represents

What they can do




Great! Why is this useful?

• Implicitly trusted because it is cryptographically

signed (verified not tampered).

• It is structured, enabling inter-op between

services

• It can inform your client about basic access

control rules (permissions)*

• And the big one: statelessness!*servers must always enforce access control policies




So, what’s the catch?

• Implicit trust is a tradeoff – how long

should the token be good for? how will you

revoke it? (Another talk: refresh tokens)

• You still have to secure your cookies!

• You have to be mindful of what you store in

the JWT if they are not encrypted. No

sensitive info!



Authorization



Authorization

• JWT Claims can have whatever you want

• Use a scope field that contains a list of

permissions for that user

• Client can inspect the claims and scope and turn

on or off features based on permissions*

• *Server must always assert permissions



In addition to user authentication and data security, Stormpath can handle authentication and authorization for your API, SPA or mobile app.

• API Authentication

• API Key Management

• Authorization

• Token Based Authentication

• OAuth

• JWTs

http://docs.stormpath.com/guides/api-key-management/

Implementations in your Library of choice:

https://docs.stormpath.com/home/

Use Stormpath for API

Authentication & Security


http://docs.stormpath.com/guides/api-key-management/

https://docs.stormpath.com/home/


Follow Us on Twitter

@lhazlewood @goStormpath



rest api security

Software