Quickstart

This quickstart demonstrates the fastest way to enable Stormpath in a Spring Boot web application. It should take about 5 minutes start to finish. Let’s get started!

Topics:

Get an API Key

All communication with Stormpath must be authenticated with an API Key.

  1. If you haven’t already, sign up for Stormpath for free. You’ll be sent a verification email.

  2. Click the link in the verification email.

  3. Log in to the Stormpath Admin Console using the email address and password you used during registration and the assigned tenant id.

  4. Click the Create API Key or Manage Existing Keys button.

  5. Under Security Credentials, click Create API Key.

    This will generate your API Key and download it to your computer as an apiKey.properties file.

  6. Save the file in your home directory in the following location:

    • ~/.stormpath/apiKey.properties on Unix, Linux and Mac OS
    • C:\Users\YOUR_USERNAME\.stormpath\apiKey.properties on Windows
  7. Change the file permissions to ensure only you can read this file and not accidentally write or modify it. For example:

    $ chmod go-rwx ~/.stormpath/apiKey.properties
    $ chmod u-w ~/.stormpath/apiKey.properties
    

On Windows, you can set file permissions similarly.

Add the Stormpath Default Spring Boot Starter

This step allows you to enable Stormpath in a Spring Boot web app with very minimal configuration. It includes Stormpath Spring Security, Stormpath Spring WebMVC and Stormpath Thymeleaf templates.

Using your favorite dependency resolution build tool like Maven or Gradle, add the stormpath-default-spring-boot-starter-1.5.4.jar to your project dependencies. For example:

Maven:

<dependency>
    <groupId>com.stormpath.spring</groupId>
    <artifactId>stormpath-default-spring-boot-starter</artifactId>
    <version>1.5.4</version>
</dependency>

Gradle:

dependencies {
    compile 'com.stormpath.spring:stormpath-default-spring-boot-starter:1.5.4'
}

Spring Security

The Stormpath Default Spring Boot Starter assumes Spring Security will be used to secure your application by default.

No programmatic configuration is needed to make use of Spring Security. The Stormpath Default Spring Boot Starter handles enabling Stormpath’s Spring Security integration automatically.

By default, all paths are locked down with Spring Security. Stormpath’s Spring Security integration follows this idiomatic behavior.

Disabling Spring Security

If you do not want to use our Spring Security integration, set the following config property:

# disable Stormpath's Spring Security support:
stormpath:
  spring:
    security:
      enabled: false

Note

Alternatively you can disable Spring Security for good by having the following property in your configuration file:

# disable Spring Security altogether:
security:
  basic:
    enabled: false

This will disable Spring Security along with the Stormpath Spring Security integration.

That’s it! You’re ready to start using Stormpath in your Spring Boot web application!

Try it!

If you followed the steps above you will now have fully functional registration, login, logout, forgot password workflows, api authentication and more active on your site!

Don’t believe it? Try it! Start up your web application, and we’ll walk you through the basics:

  • Navigate to /register. You will see a registration page. Go ahead and enter some information. You should be able to create a user account. Once you’ve created a user account, you’ll be automatically logged in, then redirected back to the root URL (/ by default).
  • Submit a POST (not a GET) to /logout. You will be logged out of your account and then redirected back to /login by default. You can learn more about POST for logout on the Logout page.
  • After logging out, navigate to /login. On the lower-right, click the Forgot Password? link, and you’ll be shown a form to enter your email. Enter in your email address and it will send you an email. Wait for the email and click the link and you’ll be able to set a new password!

Wasn’t that easy?!

Note

You probably noticed that you couldn’t register a user account without specifying a sufficiently strong password. This is because, by default, Stormpath enforces certain password strength rules.

If you’d like to change these password strength rules, you can do so easily. Visit the Stormpath Admin Console, navigate to your your application’s user Directory, and then choose the Password Policy tab on the Policies page.

Any Problems?

Did you experience any problems with this quickstart? It might not have worked perfectly for you if:

  • There might be some cases in which you want to completely turn Stormpath off. For example, if you do not have an ApiKey in your machine then Stormpath will simply not boot. In those scenarios you can add the following property in the configuration file:

    stormpath.enabled = false
    
  • you have more than one Application registered with Stormpath. If this is the case, you’ll need to configure your application’s Stormpath href, found in the admin console. Once you get the href, add the following to your application’s Spring Boot application properties or yaml file (where YOUR_APPLICATION_ID is your application’s actual Stormpath Application ID):

    stormpath:
      application:
        href: 'https://api.stormpath.com/v1/applications/YOUR_APPLICATION_ID'
    
  • your application already uses web frameworks that make heavy use of servlet filters, like Spring Security or Apache Shiro. These could cause filter ordering conflicts, but the fix is easy - you just need to specify the specific order where you want the Stormpath filter relative to other filters. You do this by adding the following to your application’s Spring Boot application properties (where preferred_value is your preferred integer value):

    stormpath:
      web:
        stormpathFilter:
          order: preferred_value #must be an integer
    

    Spring Security is ordered as 0 (which is its default) and the StormpathFilter is ordered as 10 by default. If you have multiple filters with that same order value, you might have to change the order of the other filters as well.

  • you’re using the spring-boot-starter-parent as a parent and you are getting errors related to Spring Security. The Stormpath starter relies on Spring Security 4.2.x. The current release at the time of this writing of the spring-boot-starter-parent is 1.4.3 and it also relies on Spring Security 4.1.x. Prior versions of the spring-boot-starter-parent rely on Spring Security 3.2.x. Our first recommendation is to use the latest version of the spring-boot-starter-parent. However, if you must use earlier versions, there is a simple solution to this, which is to override the Spring Security version in your pom.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                                 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>1.4.3.RELEASE</version>
            <relativePath/> <!-- lookup parent from repository -->
        </parent>
    
        <properties>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <java.version>1.8</java.version>
            <spring-security.version>4.2.0.RELEASE</spring-security.version>
        </properties>
    
        <dependencies>
    
            <dependency>
                <groupId>com.stormpath.spring</groupId>
                <artifactId>stormpath-default-spring-boot-starter</artifactId>
                <version>1.5.4</version>
            </dependency>
    
            <!-- Other dependencies... -->
    
        </dependencies>
    
    </project>
    

If there is anything else, please let us know! Our Support Team is always happy to help!

Next Steps

That was just a little example of how much functionality is ready right out of the box. You get so much more, like:

  • View customization with your own look and feel
  • Internationalization (i18n) for all views
  • Token authentication for Javascript Single Page Applications (SPAs) and mobile clients like those on iOS and Android.
  • Account email verification (verify an email address is valid before enabling a user account)
  • Secure CSRF protection on views with forms
  • Events to react to registration, login, logout, etc.
  • Session-free (stateless) secure user account identification
  • HTTP Basic and OAuth2 authentication
  • and more!

Dig in to our examples to see more Stormpath Default Spring Boot Starter in action.

Continue on to find out how to leverage this functionality and customize it for your own needs.