REST API Security

Sign up for Stormpath: https://api.stormpath.com/register
More from Stormpath: https://stormpath.com/blog

Companion slides for Stormpath CTO and Co-Founder Les REST API Security Webinar. This presentation covers all the RESTful best practices learned building the Stormpath APIs. This webinar is full of best practices learned building the Stormpath API and supporting authentication for thousands of projects. Topics Include:

- HTTP Authentication
- Choosing a Security Protocol
- Generating & Managing API Keys
- Authorization & Scopes
- Token Authentication with JSON Web Tokens (JWTs)
- Much more...

Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Transcript

1. REST API Security Les Hazlewood @lhazlewood PMC Chair, Apache Shiro Expert Group Member, JEE Application Security (JSR-375) Founder & CTO, Stormpath
2. 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
3. Overview • HTTP Authentication • HTTP Authentication Schemes Comparison • API Key Authentication • Token Authentication • Authorization
4. 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
5. HTTP(S) Authentication & Authorization Learn more at Stormpath.com
6. Authentication Proving you are who you say you are. Learn more at Stormpath.com
7. Authorization Ensuring someone is allowed to do what they are trying to do. Learn more at Stormpath.com
8. HTTP Authentication & Authorization • Authorization header • No Custom Headers! • Stay spec-standard • No pre-flight CORS requests (browsers) req’d • Custom schemes easily supported Learn more at Stormpath.com
9. Authorization header How does it work? Learn more at Stormpath.com
10. Authorization header How does it work? Challenge Response protocol Learn more at Stormpath.com
11. 1. Request GET /admin HTTP/1.1 Learn more at Stormpath.com
12. 2. Challenge HTTP/1.1 401 Unauthorized WWW-Authenticate: scheme-name <stuff> *multiple schemes allowed, typically set as multiple WWW-Authenticate headers Learn more at Stormpath.com
13. 3. Re-Request GET /admin HTTP/1.1 Authorization: scheme-name <stuff> Learn more at Stormpath.com
14. Example: HTTP Basic Authentication Learn more at Stormpath.com
15. 1. Request (Basic) GET /admin HTTP/1.1 Learn more at Stormpath.com
16. 2. Challenge (Basic) HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realm=“MyApp” Learn more at Stormpath.com
17. 3. Re-Request (Basic) GET /admin HTTP/1.1 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Learn more at Stormpath.com
18. Schemes • Basic • Digest Schemes (OAuth 1.0a) • Bearer Token Schemes (OAuth2) • Custom Learn more at Stormpath.com
19. HTTP Basic Learn more at Stormpath.com
20. HTTP Basic String value = username + ‘:’ + raw_password String schemeValue = base64_encode(value) ... GET /admin HTTP/1.1 Authorization: Basic schemeValue Learn more at Stormpath.com
21. 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) Learn more at Stormpath.com
22. Digest Schemes Learn more at Stormpath.com
23. Digest Schemes: Client request.headers[‘Client-Id’] = getMyId() String digest = hmacSha256(request, password) String val = ‘Foo ‘ + digest request.headers[‘Authorization’] = val send(request) Learn more at Stormpath.com
24. 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 Learn more at Stormpath.com
25. 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” Learn more at Stormpath.com
26. 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) Learn more at Stormpath.com
27. Bearer Token Schemes Learn more at Stormpath.com
28. Bearer Token Schemes Authorization: Bearer opaque-token Learn more at Stormpath.com
29. Bearer Token Schemes • opaque-token can be whatever you want* • *should always be cryptographically-signed and expire Learn more at Stormpath.com
30. Bearer Token Schemes: OAuth 2 Example Authorization: Bearer eyJ0eXAiOiJKV 1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3M iOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzOD AsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc 19yb290Ijp0cnVlfQ.dBjftJeZ4CVP- 92K27uhbUJU1p1r_wW1gFWFOEjXk Learn more at Stormpath.com
31. Bearer Token Schemes 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 Learn more at Stormpath.com
32. Custom Scheme Learn more at Stormpath.com
33. 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. Learn more at Stormpath.com
34. 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 Learn more at Stormpath.com
35. API Key Authentication Learn more at Stormpath.com
36. API Key Example ID : YLNVXG091ZO1BSANZ5U6DCTIX Secret: ZediwUeDCNl13ldjaFKFQzz0eD13PO931DLAopdeywixaeUAhsip+92iaY Learn more at Stormpath.com
37. API Keys • Entropy • Password Independent • Scope • Speed • Limited Exposure • Traceability Learn more at Stormpath.com
38. 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. Learn more at Stormpath.com
39. HTTP Basic with API Key String value = apiKeyId + ‘:’ + apiKeySecret String schemeValue = base64_encode(value) ... GET /admin HTTP/1.1 Authorization: Basic schemeValue Learn more at Stormpath.com
40. Token Authentication Learn more at Stormpath.com
41. Why not just use Session IDs? Learn more at Stormpath.com
42. 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 Learn more at Stormpath.com
43. 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 Learn more at Stormpath.com
44. 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 Learn more at Stormpath.com
45. Token Authentication to the rescue! Learn more at Stormpath.com
46. How do you get a Token? Learn more at Stormpath.com
47. Example: your SPA, your server Learn more at Stormpath.com
48. 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 Learn more at Stormpath.com
49. 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” } Learn more at Stormpath.com
50. 3. Resource Request GET /admin HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA Learn more at Stormpath.com
51. 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 Learn more at Stormpath.com
52. How does the server create a Token? Learn more at Stormpath.com
53. 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. Learn more at Stormpath.com
54. JSON Web Tokens (JWT) • 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. Learn more at Stormpath.com
55. JSON Web Tokens (JWT) In the wild they look like just another ugly string: eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJ pc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQo gImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnV lfQ.dBjftJeZ4CVPmB92K27uhbUJU1p1r_wW1gFWFOEj Xk Learn more at Stormpath.com
56. JSON Web Tokens (JWT) 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 Learn more at Stormpath.com
57. JSON Web Tokens (JWT) 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 Learn more at Stormpath.com
58. JSON Web Tokens (JWT) 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 Learn more at Stormpath.com
59. JSON Web Tokens (JWT) 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 When it expires Learn more at Stormpath.com
60. JSON Web Tokens (JWT) 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 When it expires Who it represents Learn more at Stormpath.com
61. JSON Web Tokens (JWT) 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 When it expires Who it represents What they can do Learn more at Stormpath.com
62. JSON Web Tokens (JWT) 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 Learn more at Stormpath.com
63. JSON Web Tokens (JWT) 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! Learn more at Stormpath.com
64. Authorization Learn more at Stormpath.com
65. 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 Learn more at Stormpath.com
66. 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 Learn more at Stormpath.com
67. Follow Us on Twitter @lhazlewood @goStormpath Learn more at Stormpath.com