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

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

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.eyJ
pc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQo
gImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnV
lfQ.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEj
Xk

But they do have a three part structure. Each
part is a Base64-encoded string:
eyJ0eXAiOiJKV1QiLA0KICJhb
GciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJle
HAiOjEzMDA4MTkzODAsDQogIm
h0dHA6Ly9leGFtcGxlLmNvbS9
pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVPmB92K27uhbUJU
1p1r_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:
{
"exp": 1300819380,
“sub”: ”users/8983462”,
}
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

Follow Us on Twitter
@lhazlewood @goStormpath

Rest API Security

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Rest API Security (20)

More from Stormpath (20)

Recently uploaded (20)

Rest API Security