#stormpath

It’s here. <3 backgrounds for this moon were drawn by my sister!!

6 March 2017:

Stormpath was founded with a mission: to build an authentication and user management service that developers love and trust. Today, we’re excited to announce that we’re doubling down on that mission by joining forces with Okta.

…

Sadly, because the two systems have so much in common, we are shutting down the Stormpath API in August, and our goal is for Stormpath API users to become delighted Okta customers.

…

And thank you, thank you, thank you, to all the developers who have used Stormpath.

Cheers.

CleverAnalytics is a location intelligence cloud platform. It allows you to easily create interactive and highly responsive business-oriented maps based on internal and external data. For example, you could calculate a store catchment area from order records and relate it to demographics and purchasing power. Business users can map their businesses in context and make informed decisions.

Providing this type of platform for enterprise businesses comes with lots of mainly non-functional requirements:

User Management - advanced tools for user provisioning via LDAP or Active Directory

Authentication - support standard authentication protocols for accessing the API

Scalability - grow with our customers

Data Security - guarantee data security and strong password management

Service Availability - SLA 99%

Flexibility - allow customers to customize their projects

Integration - easily integrate CleverAnalytics into customer's business environment, for example:

Single Sign-on

Embedding maps as iFrame widget

Customer Workflow integration - data loading, scheduled exports etc.

Internally, we have added following requirements:

Performace - it's always feature number one, the most visible feature for every customer

Multi-tenancy - Host thousands of projects in one shared AWS environment

Developer effectiveness - invest our development time in developing our core business and outsource all the general functionality

Our Stack

Fortunately, we started the project from scratch in February 2014, so we could easily choose technologies optimized for our requirements. We chose the AWS stack as a primary environment and a microservice oriented architecture to meet our scalability and flexibility needs.

HATEOAS REST API architecture is also a core architecture concept for communication between the javascript client and the server backend, as well as for internal communication between microservices and for any external application or public REST APIs.

Backend

As a core framework for our microservice, we decided to use a new Spring Boot framework that comes with completely self-contained executable jar. Getting rid of shared server container and running executable jars as a competely separated system processes, is an important backend principle. Spring Boots adds a powerful APIs for health check monitoring.

We also use other Spring frameworks in our stack, such as Spring MVC for REST API, Spring Security for application authentication and authorization, Spring Data for relational database access.

For storing persistent data there is a Postgres DB with Postgis extension for spatial data. Geo-spatial data are served by GeoServer - an open source server. It publishes a standard WFS (Web Feature Service) API for serving geospatial data in vector form, so we can transform the DB data to GeoJSON, add metadata and support operations like bounding box.

Frontend

Our web client is based on AngularJS MVW Framework and loads all data and metadata through a public REST API from CleverAnaltytics backend. The interactive map uses a Leaflet library. All business mapping data are transferred as vectors (GeoJSON), only the background map is consumed as an outsourced WMS (raster) service from MapBox.com.

REST Authentication API

This section describes how CleverAnalytics authentication works and describes the whole authentication workflow.

We have chosen OAuth 2.0 as an authentication protocol, because it suits SaaS application use cases best. A REST API can be used by many different types of clients:

CleverAnalytics web client

Third party SaaS applications

Consultant tools

Some operational and management tools

OAuth 2.0 focuses on developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

The protocol uses two types of tokens: refresh and access token. Firstly, a refresh token needs to be obtained and to do this, client must send valid authorization credentials to a login resource. When obtained, this token can be exchanged for a fresh access token (Bearer) that is used for authentication all HTTP requests.

Workflow

To see an authentication workflow in more detail, this section describes the REST API for the resources that participate in the authentication workflow.

Login - Refresh Token

The login resource handles requests with user name and password. If credentials pass verification, a new refresh token is generated and the client gets detail about the authenticated account. The following example shows it from the HTTP perspective:

POST /rest/oauth/login HTTP/1.1 > User-Agent: curl/7.29.0 > Host: localhost:9010 > Accept: application/json > Content-Type: application/json > Cache-Control: no-cache > Content-Length: 60 > { "email": "john", "password": "PASSWORD", "rememberMe": true } *Response* < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < Set-Cookie: CAN-RefreshToken=R1VVS0RBSk42UTVSNTJYUFJKFHDIDJOIJlkKLJDKIEOU9BbUxpKzV5NEhTRXlR; Expires=Thu, 19-Feb-2015 13:27:19 GMT; Domain=your.domain.com; Path=/rest; Secure; HttpOnly < Content-Type: application/json;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 21 Nov 2014 13:27:19 GMT < {"id":"O3fdjikfoiSIMRej4q0","fullName":"John Testing","email":"[email protected]","status":"ENABLED"}

As you can see, this login request succeeded and the server generated a new refresh token. It is returned as HTTP response header and the web browser will store it's value as a cookie with given expiration time. The browser will completely maintain sending this refresh token with each request to our https://our.domain.com/rest url. The cookie's flag HttpOnly means that the cookie cannot be accessed through client side script - a good practice for mitigating the majority of Cross Site Scripting (XSS) attacks.

The request body is returned with some basic information about the authenticated account.

Remember Me

Allowing the user to stay logged in when working with the web application is a "must-have" functionality and requires storing authentication credentials in a browser. For security reasons, it is not a good practice to store user credentials in browser cookie. OAuth 2.0 offers a better option - store the obtained refresh token, which is a better choice because it does not contain any user data, has limited validity and can be independently invalidated. This means a user can have more than one valid refresh token at the same time - the unique token is then stored at user's laptop and tablet web browser.

When filling in the credentials in login screen, there is an option for enabling the "Remember Me" option. If enabled, the user will not be asked for credentials by current web browser for the next 90 days. Otherwise, the authentication is remembered only for the current browser session - it expires when user closes the browser application.

In both cases, the refresh token is stored in browser cookie and what differs is a setting of the max age:

// A negative value means that the cookie is not stored persistently and it is deleted when a web browser is closed cookie.setMaxAge(request.isRememberMe() ? (60 * 60 * 24 * 90) : -1);

Access Token

When REST API client gets a refresh token, it can ask for access token what is used for each request authentication. To obtain access token, REST API client only sends a GET request into /rest/oauth/token resource:

> GET /rest/oauth/token HTTP/1.1 > Host: localhost:9010 > Cookie: CAN-RefreshToken=R1VVS0RBSk42UTVSNTJYUFJKFHDIDJOIJlkKLJDKIEOU9BbUxpKzV5NEhTRXlR > Accept: application/json > Content-Type: application/json > Cache-Control: no-cache *Response* < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < Content-Type: application/json;charset=UTF-8 < Content-Length: 329 < Date: Fri, 21 Nov 2014 13:46:30 GMT < {"expires_in":900,"token_type":"Bearer","access_token":"eyJhbGciOiJIUzI1Ni...OiJIUzIKeM"}

As you can see, the request above was successfully authenticated - and the web browser correctly set a cookie HTTP request header. The server returns a new access token with expiration time 15 minutes.

Access Authenticated Resource

The majority of CleverAnalytics REST API resources require authentication. The following example shows how to use the access token to make authenticated call on a REST API resource:

> GET /rest/bootstrap HTTP/1.1 > Host: localhost:9010 > Authorization: Bearer eyJhbGciOiJIUzI1Ni...OiJIUzIKeM > Cookie: CAN-RefreshToken=R1VVS0RBSk42UTVSNTJYUFJKFHDIDJOIJlkKLJDKIEOU9BbUxpKzV5NEhTRXlR > Accept: application/json > Content-Type: application/json > Cache-Control: no-cache *Response* < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < Content-Type: application/json;charset=UTF-8 < Content-Length: 329 < Date: Fri, 21 Nov 2014 13:46:30 GMT < {"account":{"id":"O3fdjikfoiSIMRej4q0","fullName":"John testing","email":"[email protected]","status":"ENABLED"`

The authenticated request must have an Authentication header and the header value must be set to a valid access token with prefix Bearer. As you can see, the web browser sets the Cookie header too, but it is not evaluated on server side.

If the authentication fails, the response is:

< HTTP/1.1 401 Unauthorized < Server: Apache-Coyote/1.1 < WWW-Authenticate: Bearer realm="CleverAnalytics API" error="invalid_token" < Pragma: no-cache < Cache-Control: no-store, no-cache, must-revalidate, max-age=0 < Expires: Thu, 01 Jan 1970 00:00:00 GMT < Content-Type: application/json;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 21 Nov 2014 14:13:20 GMT < {"timestamp":1416579200612,"status":401,"error":"Unauthorized","message":"Unauthorized","path":"/rest/bootstrap"}

Server returns 401 Unauthorized response status and sets response WWW-Authenticate header to Bearer realm="CleverAnalytics API" error="invalid_token". In this case, the access token was expired and REST API client will ask for the new Bearer token by GET /rest/oauth/token and retry the failed request again.

Logout

The final but still very important functionality in authetication workflow is a logout operation. For OAuth 2.0, this means the user wants to invalidate the refresh token. In a REST API, it is implemented as authenticated resource with method DELETE /rest/oauth/login

> DELETE /rest/oauth/login HTTP/1.1 > User-Agent: curl/7.29.0 > Host: localhost:9010 > Accept: application/json > Authorization: Bearer eyJhbGciOiJIUzI1Ni...OiJIUzIKeM > Cache-Control: no-cache > Content-Length: 0 > Content-Type: application/x-www-form-urlencoded < HTTP/1.1 204 No Content < Server: Apache-Coyote/1.1 < Date: Tue, 25 Nov 2014 09:02:07 GMT

Server response is 204 No Content if the request was successfully processed.

Implementation

OAuth 2.0 focuses on client developer simplicity while providing specific authentication flows for web applications, tools, third party applications etc. But on the server side, implementation of OAuth 2.0 is quite a complex task. Every mistake in the implementation could cause a security vulnerability. Further to our requirement of offloading non-core functionality, we sought out a service that could handle all the hard work connected with authentication and user management for us.

Stormpath

After some research, we chose Stormpath, as it is strongly oriented to developers and offers exactly what we need. Stormpath announced support for OAuth 2.0 authentication this summer, and we successfully started to use this service in beta immediately after the launch. Visit the Stormpath web for more details about this service: http://docs.stormpath.com/guides/api-key-management/

To use Stormpath SDK in a Java Maven project, you need add following dependencies:

<dependency> <groupId>com.stormpath.sdk</groupId> <artifactId>stormpath-sdk-api</artifactId> </dependency> <dependency> <groupId>com.stormpath.sdk</groupId> <artifactId>stormpath-sdk-impl</artifactId> </dependency> <dependency> <groupId>com.stormpath.sdk</groupId> <artifactId>stormpath-sdk-httpclient</artifactId> </dependency> <dependency> <groupId>com.stormpath.sdk</groupId> <artifactId>stormpath-sdk-oauth</artifactId> </dependency>

Spring Security

Spring security is a really powerful and highly customizable authentication and access-control framework. This section describes how to integrate Stormpath authentication into Spring Boot application.

Setting Security Configuration

To enable Spring Security you need add a new Maven dependency:

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency>

The next step is to enable integration Spring Security with Spring MVC in a Configuration with the annotation @EnableWebMvcSecurity. You can see complete example of configuration of WebSecurityConfigurerAdapter for hosting stateless REST API below. Look out for more comments inside the code:

@Configuration @EnableWebMvcSecurity public class WebSecurityConfig extends WebSecurityConfigurerAdapter { @Autowired private StormpathAuthenticationFilter stormpathFilter; @Autowired private RestAuthenticationEntryPoint entryPoint; @Override protected void configure(HttpSecurity http) throws Exception { http // defines the authentication for application entrypoints .authorizeRequests() // POST to /rest/oauth/login is not authenticated .antMatchers(HttpMethod.POST, "/rest/oauth/login").permitAll() // GET /rest/oauth/token is not authenticated .antMatchers(HttpMethod.GET, "/rest/oauth/token").permitAll() // the other REST APIs are authenticated .antMatchers("/rest/**").authenticated() .and() // never use server side sessions (stateless mode) .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .anonymous() .and() .securityContext() .and() .headers().disable() .rememberMe().disable() .requestCache().disable() .x509().disable() .csrf().disable() .httpBasic().disable() .formLogin().disable() .logout().disable() // add custom authentication filter .addFilterBefore(stormpathFilter, AnonymousAuthenticationFilter.class) // register custom authentication exception handler .exceptionHandling().authenticationEntryPoint(entryPoint); } }

The configuration enforces authentication for all resources except the following, two of which are available for an anonymous user:

POST on /rest/oauth/login

GET on /rest/oauth/token

A complete authentication flow with authentication filter is vizualized in a following sequence diagram:

Stormpath Client

Stormpath Client is a SDK wrapper for Stormpath REST API. It is a primary class for communication with Stormpath from a Java application. In the Spring ecosystem, you can simply inject the Client bean anywhere you need it, but first it needs to be properly initialized. Stormpath provides a ClientBuilder for constructing the Client instance. An example below demonstrates setting up Stormpath Administrator Key and configuring cache manager:

ApiKey apiKey = ApiKeys.builder().setId(rootStormpathKeyId).setSecret(rootStormpathKeySecret).build(); client = Clients.builder() .setApiKey(apiKey) .setCacheManager( newCacheManager() .withDefaultTimeToLive(1, TimeUnit.DAYS) //general default .withDefaultTimeToIdle(2, TimeUnit.HOURS) //general default .withCache(forResource(Account.class) //Account-specific cache settings .withTimeToLive(1, TimeUnit.HOURS) .withTimeToIdle(30, TimeUnit.MINUTES)) .withCache(forResource(Group.class) //Group-specific cache settings .withTimeToLive(2, TimeUnit.HOURS)) .build() //build the CacheManager ) .build();

In following resources examples is not injected the bean Client directly but a concrete Application bean for CleverAnalytics application. You can read more about Stormpath Application here: http://docs.stormpath.com/rest/product-guide/#applications

Login Resource

The login controller verifies the given user credentials by calling the Stormpath service. If verification passes, the resource generates a new refresh token. Here is a simplified fragment of code without any exception handling, logging etc.:

import com.stormpath.sdk.account.Account; import com.stormpath.sdk.api.ApiKey; import com.stormpath.sdk.authc.AuthenticationRequest; import com.stormpath.sdk.application.Application; import com.stormpath.sdk.authc.UsernamePasswordRequest; import javax.servlet.http.Cookie; @RestController @RequestMapping("/rest/oauth/login") public class LoginController { @Autowired private Application stormpathApplication; @RequestMapping(method = {RequestMethod.POST, RequestMethod.HEAD}) public LoginResponse login(@RequestBody LoginRequest request, HttpServletResponse response) throws Exception { AuthenticationRequest authReq = new UsernamePasswordRequest(request.email, request.password); Account account = stormpathApplication.authenticateAccount(authReq).getAccount(); // create a new api key and set it store it in a cookie ApiKey apiKey = account.createApiKey(); String concat = apiKey.getId() + ":" + apiKey.getSecret(); String securityToken = Base64.encodeBase64String(concat.getBytes("UTF-8")); // set ApiKeyToken Cookie cookie = new Cookie("CAN-RefreshToken", securityToken); cookie.setPath("/rest"); cookie.setHttpOnly(true); cookie.setSecure(true); // A negative value means that the cookie is not stored persistently and will be deleted when the Web browser exits. cookie.setMaxAge(request.isRememberMe() ? (60 * 60 * 24 * 90) : -1); cookie.setDomain(SERVER_DOMAIN); response.addCookie(cookie); // return a LoginResponse DTO as a response body } }

Token Resource

The controller of the token resource reads the value of the cookie CAN-RefreshToken, verifies validity of the refresh token and generates a new access token. The Stormpath REST API generates a new access token is provided on, but the API is looking for the refresh token in Authorization header. By contrast, we get a request that has a refresh token in cookie header.

Because we do not want to manipulate with refresh token on the client side (read this cookie is forbidden by the javascript HttpOnly flag), it is necessary to do this work on server. Instead of simply resending the incoming HTTP request, the server creates a new HTTP request and sets the refresh header to the Authorization request header to fit the expectations of the Stormpath API.

The following example is again a simplified fragment of code. Lots of the logic should be definitely be part of some Service class, and proper exception handling and logging are also omitted:

@RestController @RequestMapping("/rest/oauth/token") public class TokenController { @Autowired private Application stormpathApplication; @RequestMapping(method = {RequestMethod.GET}) public String createToken(@CookieValue("CAN-RefreshToken") String apiKeyToken) { // Set up HTTP Headers Map<String, String[]> headers = new HashMap(); headers.put(HttpHeaders.AUTHORIZATION, new String[]{"Basic " + apiKeyToken}); headers.put(HttpHeaders.CONTENT_TYPE, new String[]{"application/x-www-form-urlencoded"}); headers.put(HttpHeaders.ACCEPT, new String[]{"application/json"}); String[] param = {"client_credentials"}; Map<String, String[]> params = new HashMap(); params.put("grant_type", param); // Create a new HttpRequest that Stormpath SDK understands: HttpRequest requestCustom = HttpRequests.method(HttpMethod.POST).headers(headers).parameters(params).build(); // Obtain access token from Stormpath AccessTokenResult resultToken = (AccessTokenResult) stormpathApplication.authenticateOauthRequest(request).withTtl(60 *15).execute(); return resultToken.getTokenResponse().toJson(); } }

Logout Resource

The logout operation is an invalidation of the refresh token. This could mean an invalidation of all existing refresh tokens (ie. logout user from all it's devices) or invalidating only the selected ones. In this example, all active refresh tokens are removed:

@ResponseStatus(HttpStatus.NO_CONTENT) @RequestMapping(method = {RequestMethod.DELETE}) public void logout(@AuthenticationPrincipal Principal principal) throws Exception { // get current Stormpath Account from Principal details Account account = ((Account) ((UsernamePasswordAuthenticationToken)principal).getDetails()); // remove all existing API keys for the account ApiKeyList apiKeys = account.getApiKeys(); for (ApiKey key : apiKeys) { key.delete(); } }

Authentication Filter

All incoming HTTP requests are handled by authentication filter before being dispatched to MVC Controllers. The authentication filter StormpathAuthenticationFilter is registered in the filters chain by the WebSecurityConfig configuration. The filter verifies the account token present from Authorization HTTP header. If the authentication succeeds, Stormpath API returns the ApiAuthenticationResult instance withdetails of the authenticated Stormpath account.

The Account is then set into SecurityContextHolder to be available anywhere as a ThreadLocal variable.

Here is how filter authenticates a request and sets result to SecurityContextHolder:

@Component public class StormpathAuthenticationFilter extends GenericFilterBean { @Autowired private Application stormpathApplication; @Autowired private RestAuthenticationEntryPoint entryPoint; @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { HttpServletRequest request = (HttpServletRequest) req; HttpServletResponse response = (HttpServletResponse) res; try { // authenticate by Stormpath SDK ApiAuthenticationResult result = stormpathApplication.authenticateApiRequest(request); // set authentication success into securityContextHolder Set<GrantedAuthority> authorities = new HashSet<>(); UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(result.getAccount().getEmail(), "secret_pass", authorities); auth.setDetails(result.getAccount()); SecurityContextHolder.getContext().setAuthentication(auth); } catch (ResourceException ex) { // authentication failed, log the exception and continue processing the request // Principal is set to anonymous user } // continue processing the request chain.doFilter(request, response); } }

If authentication fails, user is authenticated as anonymously and only URLs with permitAll settings in WebSecurityConfig are available.

Injecting Account into Controller

It is very useful to inject the current Account directly into Controller's method. Spring Security supports injecting the current Principal general instance, but it is a bit ugly when you want to get the Account object from it:

@RequestMapping(method = RequestMethod.GET) public SomeDTO getResource(Principal principal) { Account account = (Account)((UsernamePasswordAuthenticationToken)principal).getDetails(); ... }

Much more elegant is defining the custom annotation that directly provides the Account object:

@RequestMapping(method = RequestMethod.GET) public SomeDTO getResource(@ActiveAccount Account account) { ... }

To do this, you need define a custom annotation:

/** Custom annotation ActiveAccount for injecting Account from SecurityContextHolder detail */ @Target(ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface ActiveAccount {} implement custom `HandlerMethodArgumentResolver` for resolving method argument: /** ActiveAccount annotation resolver. */ @Component public class ActiveAccountHandlerMethodArgumentResolver implements HandlerMethodArgumentResolver { final static Logger logger = LoggerFactory.getLogger(ActiveAccountHandlerMethodArgumentResolver.class); @Override public boolean supportsParameter(MethodParameter methodParameter) { return methodParameter.getParameterAnnotation(ActiveAccount.class) != null && methodParameter.getParameterType().equals(Account.class); } @Override public Object resolveArgument(MethodParameter methodParameter, ModelAndViewContainer mavContainer, NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception { if (this.supportsParameter(methodParameter)) { Principal principal = webRequest.getUserPrincipal(); return (Account) ((Authentication) principal).getDetails(); } else { return WebArgumentResolver.UNRESOLVED; } } }

and register HandlerMethodArgumentResolver by ActiveAccountConfigurerAdapter::

/** Register custom annotation resolver */ @Configuration public class ActiveAccountConfigurerAdapter extends WebMvcConfigurerAdapter { @Bean public ActiveAccountHandlerMethodArgumentResolver activeAccountHandlerMethodArgumentResolver() { return new ActiveAccountHandlerMethodArgumentResolver(); } @Override public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) { argumentResolvers.add(activeAccountHandlerMethodArgumentResolver()); super.addArgumentResolvers(argumentResolvers); } }

Summary

This article wraps up how we have integrated Stompath OAuth 2.0 authentication into Spring Boot backend application. Thanks to outsourcing all the hard work to Stormpath, it only required configuring Spring Security and calling a few Stormpath SDK methods. The authentication logic is encapsulated into the Authentication Filter and resource access rules are configured as a standard HttpSecurity object in WebSecurityConfig.

Our talk night will be happening at Silicon Valley Pad (1370 Willow Road, 2nd Floor, Menlo Park, CA). Look for 'Menlo Science & Technology Park' and take the first left once you have turned off of Willow Road.

We'll kick things off at 7pm with food and beverages sponsored by Stormpath.  Talks will start at 7:30pm and should wrap up by 9pm.

We have an open call for talks - please submit a lightning proposal to the BayNode GitHub

Everyone is welcome to attend: newcomers to node.js, those interested to hear what the hype is about, and experienced developers looking to trade tricks.

Talks:

Synth - Jon Abrams:

Synth is a new back-end framework designed to make it as easy as possible to power front-end heavy apps powered by frameworks like AngularJS and EmberJS.

Easily create API endpoints by just declaring functions, and return promises that eventually turn into JSON responses.Auto-preloads data and templates so the browser doesn't need to make multiple round-trips before displaying your app to the user.Use Angular-style services on the back-end. The easiest way to write DRY back-end code and produce a very powerful back-end with minimal code.

Learn more at synthjs.com

Jon Abrams

Github Profile

Jon Abrams is the creator of Synth. He's also the lead platform engineer @ OUYA. In his spare time he collects pinball machines and plays them competitively.

---

Gulp.js - Ross Kukulinski