Secure REST with JAX-RS

Secure REST with JAX-RS Carol McDonald, Java Architect

Agenda
REST Primer
RESTful Design and API Elements
Building a Simple Service
Security
Q & A

REpresentational State Transfer
Get
http://www.depot.com/parts
Response XML data = REpresentational State Transfer
The URL identifies the resource
HTTP GET method operates on the resource
html page is transferred to the browser
REpresentational State transfer
The page ( application state ) is stored on the client (browser)
Click on the link (resource) in page ( hypermedia )
New state transfer occurs

REST Tenets
Resources ( nouns )
Identified by a URI , For example:
http://www.parts-depot.com/parts
Methods ( verbs ) to manipulate the nouns
Small fixed set:
GET, PUT, POST, DELETE
Read, Update, Create, Delete
Representation of the Resource
data and state transferred between client and server
XML, JSON ...
Use verbs to exchange application state and representation

HTTP Example Request GET /music/artists/beatles/recordings HTTP/1.1 Host: media.example.com Accept: application/xml Response HTTP/1.1 200 OK Date: Tue, 08 May 2007 16:41:58 GMT Server: Apache/1.3.6 Content-Type: application/xml; charset=UTF-8 <?xml version="1.0"?> <recordings xmlns="…"> <recording>…</recording> … </recordings> Method Resource Representation State transfer

REST in Five Steps*
Everything is a Resource
All Resources expose a standard interface
Link things together
Multiple representations
Stateless communications
Uniform Interface

Everything is a Resource Every resource has an id, URI is the id
Everything is a Resource
a Resource has an Identifier
http://company.com/customers/123456

Every Resource has an Id http://company.com/customers/123456 Resource Collection name Primary key http://company.com/customers/123456/orders/12 http://example.com/orders/2007/11 http://example.com/products?color=green URI is the id, Every resource has a URI
URIs identify :
items, collections of items, virtual and physical objects, or computation results.

REST in Five Steps*
Give everything an ID
All Resources expose a standard interface
use Standard methods: GET,PUT,POST,DELETE
Stateless communications
Uniform Interface

Use Standard HTTP Methods
Example
GET /store/customers/123456

Use Standard Methods:
/orders
GET - list all orders
POST - submit a new order
/orders/{order-id}
GET - get an order representation
PUT - update an order
DELETE - cancel an order
/orders/average-sale
GET - calculate average sale
/customers
GET - list all customers
POST - create a new customer
/customers/{cust-id}
GET - get a customer representation
DELETE- remove a customer
/customers/{cust-id}/orders
GET - get the orders of a customer
Order Customer Mgmt Example http://www.infoq.com/articles/rest-introduction

Use Standard HTTP Methods
HTTP Get, Head
Should not modify anything
Cache-able
With Correct use of Last-Modified and ETag
Idempotency:
PUT, DELETE, GET, HEAD can be repeated and the results are the same

REST in Five Steps*
Use standard methods
Stateless communications * Inspired by Stefan Tilkov: http://www.innoq.com/blog/st/presentations/2008/2008-03-13-REST-Intro--QCon-London.pdf

Link Things Together
Representations contain links to other resources
Service provides links in response to the Client
Enables client to move the application from one state to the next by following a link
Representations contain links to other resources: <prop self=" http://example.com/orders/101230 "> <customer ref=" http://example.com/customers/bar "> <product ref=" http://example.com/products/21034 "/> <amount value="1"/> </order>

REST in Five Steps*

Multiple Representations
Offer data in a variety of formats, for different needs
XML
JSON
(X)HTML
Support content negotiation
Accept header GET /foo Accept: application/json
URI-based GET / foo.json

content negotiation Multiple Representations Content-type HTTP header Accept HTTP header Request GET /music/artists/beatles/recordings HTTP/1.1 Host: media.example.com Accept : application/xml Response HTTP/1.1 200 OK Date: Tue, 08 May 2007 16:41:58 GMT Server: Apache/1.3.6 Content-Type : application/xml; charset=UTF-8 <?xml version="1.0"?> <recordings xmlns="…"> <recording>…</recording> … </recordings> Format Representation

REST in Five Steps*

Stateless Communications
HTTP protocol is stateless
Everything required to process a request contained in the request
No client session on the server
Eliminates many failure conditions
application state kept on Client
Service responsible for resource state

Common Patterns: Container, Item Server in control of URI
Container – a collection of items
List catalog items: GET /catalog/items
Add item to container: POST /catalog/items
with item in request
URI of item returned in HTTP response header
e.g. http://host/ catalog/items/1
Update item: PUT /catalog/items/1
with updated item in request
Good example: Atom Publishing Protocol

Common Patterns: Map, Key, Value Client in control of URI
List key-value pairs : GET /map
Put new value to map: PUT /map/{key}
with entry in request
e.g. PUT /map/dir/contents.xml
Read value: GET /map/{key}
Update value: PUT /map/{key}
with updated value in request
Remove value: DELETE /map/{key}
Good example: Amazon S3

Key Benefits
Server side
Uniform Interface
Cacheable
Scalable
Easy failover
Client side
Easy to experiment in browser
Broad programming language support
Choice of data formats
bookmarkable

Agenda
REST Primer
RESTful Design and API Elements with JAX-RS
Status
Q & A

JAX-RS: Clear mapping to REST concepts
High level, Declarative
Uses @ annotation in POJOs
Jersey – reference implementation of JSR 311
Download it from http://jersey.dev.java.net
Comes with Glassfish, Java EE 6
Tools support in NetBeans

Resources
Resource class
POJO, No required interfaces
ID provided by @Path annotation
Relative to deployment context
Annotate class or “ sub-resource locator” method
http://host/ctx/orders/12 http://host/ctx/orders/12/customer @Path( "orders/{id}") public class OrderResource { @Path("customer") CustomerResource getCustomer(...) {...} }

Request Mapping
Annotate resource class methods with standard method
@GET , @PUT , @POST , @DELETE , @HEAD
annotations on parameters specify mapping from request data
Return value mapped to http response
@Path("orders/ {order_id} ") public class OrderResource { @GET Order getOrder( @PathParam (" order_id ") String id) { ... } }

Multiple Representations Static and dynamic content negotiation
Annotate methods or classes
@Produces matches Accepts header
@Consumes matches Content-Type header
@GET @Consumes("application/json") @Produces({"application/xml","application/json"}) String getOrder(@PathParam("order_id") String id) { ... }

Multiple Representations : JAX-RS consuming
Annotated method parameters extract client request information
@PathParam extracts information from the request URI
@QueryParam extracts information from the request URI query parameters
http://host/catalog/items/ 123 http://host/catalog/items/ ?start=0

Multiple Representations : JAX-RS consuming http://host/catalog/items/?start=0 http://host/catalog/items/123 @Path("/items/") @ConsumeMime(“application/xml”) public class ItemsResource { @GET ItemsConverter get( @QueryParam ("start") int start ) { ... } @Path( "{id}/" ) ItemResource getItemResource( @PathParam ("id")Long id ){ ... } }

Multiple Representations : Supported Types
JAX-RS can automatically (un)-marshall between HTTP request/response and Java types
“Out-of-the-box” support for the following
text/xml, application/xml, application/json – JAXB class
*/* – byte[]
text/* – String
application/x-www-form-urlencoded - MultivaluedMap<String, String>
response

Multiple Representations @Post @ConsumeMime(“application/x-www-form-urlencoded”) @ProduceMime(“application/xml”) public JAXBClass updateEmployee( MultivalueMap<String, String> form) { ... Converted to a map for accessing form's field converted to XML

Multiple Representations : producing a response Use Response class to build “created”response @Path(“/items”) class Items { @POST @ProduceMime(“application/xml”) Response create(Ent e) { // persist the new entry, create URI return Response.created ( uriInfo.getAbsolutePath(). resolve(uri+"/")).build(); } }

Uniform interface: HTTP request and response C: POST /items HTTP/1.1 C: Host: host.com C: Content-Type: application/xml C: Content-Length: 35 C: C: <item><name>dog</name></item> S: HTTP/1.1 201 Created S: Location: http://host.com/employees/1234 S: Content-Length: 0

Response Codes and Custom Responses
JAX-RS returns default response codes
GET returns 200 OK
PUT returns 201 CREATED
See
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
200 OK 201 Created 202 Accepted 203 Non-Authoritative Information 204 No Content 205 Reset Content 206 Partial Content 207 Multi-Status 226 IM Used . . .

JAX-RS provides Response class @PUT public Response putUser( @PathParam(“id”) int id) { if (!id.equals(userid) ) return Response .status(409).entity( "userids differ").build();
JAX-RS provides Response class:
to specify response codes, to add onto the response
can construct more sophisticated return result
Can build responses for redirects, errors, ok, setting headers, etc

WebApplicationException Example @GET public Employee getEmployee( @PathParam(“id”) int id) { if (!doesEmployeeExist(id)) throw new WebApplicationException( new Throwable("Resource for " + uriInfo.getAbsolutePath() + " does not exist."), 404); Response: HTTP Status 404 -
Use it when the method has a return type
Simple error indicator

Link Things Together
UriInfo provides information about the request URI and the route to the resource
UriBuilder provides facilities to easily build URIs for resources
@Context UriInfo info ; OrderResource r = ... UriBuilder b = info.getBaseUriBuilder(); URI u = b.path(OrderResource.class).build(r.id);

Statelessness: JAX-RS
The default component lifecycle is per-request
A new instance created for every request
Reduces concurrency issues
HTTP session life-cycle is not supported
On server side Developer must model state
As resource state in the representations

Agenda
REST Primer
Deployment Options
Status

Example RESTful Catalog

Example RESTful Catalog Service Catalog Database Web container (GlassFish™) + REST API Browser (Firefox) HTTP

URIs and Methods:
/items
GET - list all items
POST – add item to catalog
/items/{id}
GET - get an item representation
PUT - update an item
DELETE – remove an item
Item Catalog Example http://www.infoq.com/articles/rest-introduction

Methods Java method name is not significant The @HTTP method is the method @Path(“/items”) class ItemsResource { @GET Items get() { ... } @POST Response create(Item) { ... } } class ItemResource { @GET Item get(...) { ... } @PUT void update(...) { ... } @DELETE void delete(...) { ... } }

RESTful Catalog
Dojo client, JAX-RS, JAXB, JPA
DB Registration Application JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

Entity Classes
Use JPA to map/retrieve data from the database as entities
expose entities as RESTful resources
entity = resource identified by URL
http://host/catalog/items/123 public class Item { int id; String name; String descr; String url; } @Entity @Id Item ID NAME DESC URL

Converter Classes
JAXB to convert the domain objects (JPA entities ) into XML and/or JSON .
DB JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

ItemConverter JAXB annotated @XmlRootElement(name = "item") public class ItemConverter { private Item entity; private URI uri; @XmlAttribute public URI getUri() { return uri; } @XmlElement public Long getId() { return (expandLevel > 0) ? entity.getId() : null; } ... }

XML <item uri="http://localhost/Web/resources/items/1/" > <description> black cat is nice</description> <id>1</id> <imagethumburl>/images/anth.jpg</imagethumburl> <name>not Friendly Cat</name> <price>307.10</price> <productid>feline01</productid> </item>

JSON { "@uri":"http://host/catalog/resources/items/1/", "name":"Friendly Cat", "description":"This black and white colored cat is super friendly.", "id":"1", "imageurl":" http://localhost:8080/CatalogService/images/anthony.jpg " }

ItemsConverter JAXB annotated @XmlRootElement(name = "items") public class ItemsConverter { private Collection<ItemConverter> items; private URI uri; @XmlAttribute public URI getUri() { return uri; } @XmlElement public Collection<ItemConverter> getItem() { ... return items; } }

XML <?xml version="1.0" encoding="UTF-8"?> <items uri="http://localhost/Web/resources/items/"> <item uri="http://localhost/Web/resources/items/1/" > <description> black cat is nice</description> <id>1</id> <imagethumburl>/images/anth.jpg</imagethumburl> <name>not Friendly Cat</name> <price>307.10</price> <productid>feline01</productid> </item> <item . . . </item> </items>

JSON { "@uri":"http://host/catalog/resources/items/", " item ":[ {"@uri":"http://host/catalog/resources/items/1/", "name":"Friendly Cat", "description":"This black and white colored cat is super friendly.", "id":"1", "imageurl":"http://localhost:8080/CatalogService/images/anthony.jpg"}, {"@uri":"http://host/catalog/resources/items/2/", "name":"Fluffy Cat", "description":"A great pet for a hair stylist! "id":"2", "imageurl":"http://localhost:8080/CatalogService/images/bailey.jpg"} ] }

Resource Classes
Items Resource retrieves updates a collection of Item entities
/items – URI for a list of Items
Item resource retrieves or updates one Item entity
/item/1 – URI for item 1
DB JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

Get Items @Path("/items/") public class ItemsResource { @Context protected UriInfo uriInfo; @GET @Produces ("application/json") public ItemsConverter get(){ return new ItemsConverter( getEntities(), uriInfo.getAbsolutePath()); } Performs JPA Query, returns list of entities JAXB class responds with JSON responds to the URI http://host/catalog/items/ responds to HTTP GET

Get Item @Path("/items/") public class ItemsResource { @Path("{id}/") public ItemResource getItemResource( @PathParam ("id") Long id) { return new ItemResource (id, context); } } public class ItemResource { @GET @Produces ( "application/json") public ItemConverter get() { return new ItemConverter(getEntity(), context.getAbsolutePath(), expandLevel); } JAXB class http://host/catalog/items/123

Agenda
REST Primer
Security
Q & A

Securing your REST Web Service
Authentication for Identity Verification
Authorizaton
Encryption

Authentication: Configure web.xml <login-config> <auth-method>BASIC</auth-method> <realm-name>admin</realm-name> </login-config>

Authentication: Configure web.xml <login-config> <auth-method>BASIC</auth-method> <realm-name>admin</realm-name> </login-config>
Login-config:
defines how HTTP requests should be authenticated
Auth-method:
BASIC, DIGEST, or CLIENT_CERT. corresponds to Basic, Digest, and Client Certificate authentication, respectively.
Realm-name:
Name for database of users and groups that identify valid users of a web application
realm

Authentication: Configure web.xml <security-constraint> <web-resource-collection> <url-pattern>/secure/*</url-pattern> <http-method>POST</http-method> </web-resource-collection> ...
security constraint
defines access privileges to a collection of resources
url-pattern:
URL pattern you want to secure
Http-method:
Methods to be protected

Authentication: Configure web.xml <security-constraint> ... <auth-constraint> <description>only let admin login </description> <role-name>admin</role-name> </auth-constraint>
auth-constraint:
names the roles authorized to access the URL patterns and HTTP methods declared by this security constraint

Encryption: Configure web.xml <security-constraint> ... <user-data-constraint> <description>SSL</description> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
user-data-constraint: NONE, INTEGRAL, or CONFIDENTIAL
how the data will be transported between client and server

Authentication: Configure web.xml <security-role> <role-name>admin</role-name> </security-role>
security-role:
lists all of the security roles used in the application
For every <role-name> used in <auth-constraints> must define a corresponding <security-role>
http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html

Authentication: map roles to realm <sun-web-app> <security-role-mapping> <role-name>admin</role-name> <principal-name> admin </principal-name> </security-role-mapping> </sun-web-app>
security-role-mapping:
Assigns security role to a group or user in Application Server realm
Realm:
database of users and groups that identify valid users of a web application (FILE, LDAP
LDAP realm

Authentication: map roles to realm file realm

Authorization Annotations @Path("/customers") @RolesAllowed({"ADMIN", "CUSTOMER"}) public class CustomerResource { @GET @Path("{id}") @Produces("application/xml") public Customer getCustomer(@PathParam("id") int id) {...} @RolesAllowed("ADMIN") @POST @Consumes("application/xml") public void createCustomer(Customer cust) {...} @PermitAll @GET @Produces("application/xml") public Customer[] getCustomers() {} } roles permitted to execute operation any authenticated user

JAX-RS Security Context public interface SecurityContext { public Principal getUserPrincipal(); public boolean isUserInRole(String role); public boolean isSecure(); public String getAuthenticationScheme(); } Determine the identity of the user check whether user belongs to a certain role whether this request was made using a secure channel

JAX-RS Security Context @Path("/customers") public class CustomerService { @GET @Produces("application/xml") public Customer[] getCustomers(@Context SecurityContext sec ) { if ( sec.isSecure () && ! sec.isUserInRole ("ADMIN")){ logger.log( sec.getUserPrincipal () + " accessed customer database."); } ... } } Determine the identity of the user check whether user belongs to a certain role

Java EE 6
JAX-RS is part of Java EE 6
Applications deployed in a Java EE 6 Web container will have access to additional resources:
Resources @Resources
EJB @EJB
...
Stateless session EJBs as resource classes
More portable deployment with Servlet 3.0

Agenda
REST Primer
Deployment Options
Status

Summary
REST architecture is gaining popularity
Simple, scalable and the infrastructure is already in place
JAX-RS (JSR-311) provides a high level declarative programming model
http://jersey.dev.java.net

For More Information
Reference Implementation
http://jersey.dev.java.net/
Marc's Blog
http://weblogs.java.net/blog/mhadley/
Paul's Blog
http://blogs.sun.com/sandoz/
http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html
Carol's Blog
http://weblogs.java.net/blog/caroljmcdonald/

For More Information
RESTful Java with JAX-RS

Presenter’s Name
[email_address]
Carol McDonald Java Architect http://weblogs.java.net/blog/caroljmcdonald/

http://www.slideshare.net	88
http://owen.com	73
http://localhost	9
http://wjhwsh.blogspot.com	8
http://sysdecom-projects.com	3
https://twitter.com	2
http://wjhwsh.blogspot.cz	2
http://wjhwsh.blogspot.de	1
http://wildfire.gigya.com	1
http://static.ak.facebook.com	1
http://wjhwsh.blogspot.it	1
http://wjhwsh.blogspot.co.uk	1

Secure REST with JAX-RS

by Carol McDonald on Nov 23, 2009

Accessibility

Categories

Upload Details

Usage Rights

12 Embeds 190

Statistics

Secure REST with JAX-RS Presentation Transcript