stormpath.github.io/java/servlet-plugin/quickstart.html at master · stormpath/stormpath.github.io

This repository was archived by the owner on Jun 28, 2023. It is now read-only.
646 lines (533 loc) · 37.7 KB
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Quickstart &mdash; Stormpath Java Servlet Plugin 1.5.4 documentation</title>
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
    <link rel="stylesheet" href="_static/theme_overrides.css" type="text/css" />
        <link rel="author" title="About these documents"
              href="about.html"/>
        <link rel="index" title="Index"
              href="genindex.html"/>
        <link rel="search" title="Search" href="search.html"/>
    <link rel="top" title="Stormpath Java Servlet Plugin 1.5.4 documentation" href="index.html"/>
        <link rel="next" title="Configuration" href="config.html"/>
        <link rel="prev" title="About" href="about.html"/> 
  <script src="_static/js/modernizr.min.js"></script>
  <script src="https://cdn.optimizely.com/js/225847041.js"></script>
  !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
  n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
  document,'script','https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '986262161469311');
  fbq('track', 'PageView');
  </script>
  <noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id=986262161469311&ev=PageView&noscript=1"
  /></noscript>
<body class="wy-body-for-nav" role="document">
  <noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-NQZZFW"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
  '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
  })(window,document,'script','dataLayer','GTM-NQZZFW');</script>
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
            <a href="index.html" class="icon icon-home"> Stormpath Java Servlet Plugin
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
        </div>
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
                <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="about.html">About</a><ul>
<li class="toctree-l2"><a class="reference internal" href="about.html#what-is-stormpath">What is Stormpath?</a></li>
<li class="toctree-l2"><a class="reference internal" href="about.html#what-is-the-project">What is the Stormpath Java Servlet Plugin?</a></li>
<li class="toctree-l2"><a class="reference internal" href="about.html#who-should-use-stormpath">Who should use Stormpath?</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Quickstart</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#get-an-api-key">Get an API Key</a></li>
<li class="toctree-l2"><a class="reference internal" href="#add-the-project">Add the Stormpath Java Servlet Plugin</a></li>
<li class="toctree-l2"><a class="reference internal" href="#try-it">Try it!</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#any-problems">Any Problems?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next Steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="config.html#no-config">No Config?</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#web-xml">web.xml</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#stormpath-properties">stormpath.properties</a><ul>
<li class="toctree-l3"><a class="reference internal" href="config.html#property-locations">Property Locations</a><ul>
<li class="toctree-l4"><a class="reference internal" href="config.html#plugin-web-stormpath-properties">1. Plugin web.stormpath.properties</a></li>
<li class="toctree-l4"><a class="reference internal" href="config.html#classpath-stormpath-properties">2. classpath:stormpath.properties</a></li>
<li class="toctree-l4"><a class="reference internal" href="config.html#web-inf-stormpath-properties">3. /WEB-INF/stormpath.properties</a></li>
<li class="toctree-l4"><a class="reference internal" href="config.html#servlet-context-parameters">4. Servlet Context Parameters</a></li>
<li class="toctree-l4"><a class="reference internal" href="config.html#environment-variables">5. Environment Variables</a></li>
<li class="toctree-l4"><a class="reference internal" href="config.html#jvm-system-properties">6. JVM System Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html#security-considerations-passwords-and-secret-values">Security Considerations: Passwords and secret values</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#stormpath-client">Stormpath Client</a><ul>
<li class="toctree-l3"><a class="reference internal" href="config.html#api-key">API Key</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html#http-proxy">HTTP Proxy</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html#authentication-scheme">Authentication Scheme</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html#usage">Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#stormpath-application">Stormpath Application</a><ul>
<li class="toctree-l3"><a class="reference internal" href="config.html#id2">Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#filters">Filters</a><ul>
<li class="toctree-l3"><a class="reference internal" href="config.html#default-filters">Default Filters</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html#uris">URIs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="config.html#uri-evaluation-priority">URI Evaluation Priority</a></li>
<li class="toctree-l1"><a class="reference internal" href="registration.html">Registration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="registration.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#configuration">Configuration</a><ul>
<li class="toctree-l3"><a class="reference internal" href="registration.html#enabled">Enabled</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#uri">URI</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#next-uri">Next URI</a><ul>
<li class="toctree-l4"><a class="reference internal" href="registration.html#next-query-parameter">Next Query Parameter</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#autologin">AutoLogin</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#form-fields">Form Fields</a><ul>
<li class="toctree-l4"><a class="reference internal" href="registration.html#form-field-definitions">Form Field Definitions</a></li>
<li class="toctree-l4"><a class="reference internal" href="registration.html#standard-form-fields">Standard Form Fields</a></li>
<li class="toctree-l4"><a class="reference internal" href="registration.html#custom-form-fields">Custom Form Fields</a></li>
<li class="toctree-l4"><a class="reference internal" href="registration.html#optional-form-fields">Optional Form Fields</a></li>
<li class="toctree-l4"><a class="reference internal" href="registration.html#disabling-form-fields">Disabling Form Fields</a></li>
<li class="toctree-l4"><a class="reference internal" href="registration.html#form-field-order">Form Field Order</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#password-strength">Password Strength</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#email-verification">Email Verification</a><ul>
<li class="toctree-l3"><a class="reference internal" href="registration.html#try-it">Try it!</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#verify-link-base-url">Verify Link Base URL</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#verify-next-uri">Verify Next URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#internationalization-i18n">Internationalization (i18n)</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#pre-register-handler">Pre Register Handler</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#post-register-handler">Post Register Handler</a></li>
<li class="toctree-l2"><a class="reference internal" href="registration.html#events">Events</a><ul>
<li class="toctree-l3"><a class="reference internal" href="registration.html#registered-account">Registered Account</a></li>
<li class="toctree-l3"><a class="reference internal" href="registration.html#verified-account">Verified Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="login.html">Login</a><ul>
<li class="toctree-l2"><a class="reference internal" href="login.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#security-notice">Security Notice</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#uri">URI</a><ul>
<li class="toctree-l3"><a class="reference internal" href="login.html#next-query-parameter">Next Query Parameter</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#next-uri">Next URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#internationalization-i18n">Internationalization (i18n)</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#pre-login-handler">Pre Login Handler</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#post-login-handler">Post Login Handler</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#events">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="login.html#authentication-state">Authentication State</a><ul>
<li class="toctree-l3"><a class="reference internal" href="login.html#saving-authentication-state">Saving Authentication State</a></li>
<li class="toctree-l3"><a class="reference internal" href="login.html#cookie-storage">Cookie Storage</a><ul>
<li class="toctree-l4"><a class="reference internal" href="login.html#cookie-config">Cookie Config</a></li>
<li class="toctree-l4"><a class="reference internal" href="login.html#jwt-creation">JWT Creation</a></li>
<li class="toctree-l4"><a class="reference internal" href="login.html#disabling-cookie-storage">Disabling Cookie Storage</a></li>
<li class="toctree-l3"><a class="reference internal" href="login.html#custom-savers">Custom Savers</a></li>
<li class="toctree-l1"><a class="reference internal" href="social.html">Social Login</a><ul>
<li class="toctree-l2"><a class="reference internal" href="social.html#facebook-login">Facebook Login</a><ul>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-facebook-app">Create a Facebook App</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#specify-allowed-urls">Specify Allowed URLs</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-facebook-directory">Create a Facebook Directory</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#test-it-out">Test it Out</a></li>
<li class="toctree-l2"><a class="reference internal" href="social.html#google-login">Google Login</a><ul>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-google-project">Create a Google Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#enable-google-login">Enable Google Login</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-oauth-credentials">Create OAuth Credentials</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-google-directory">Create a Google Directory</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#id1">Test it Out</a></li>
<li class="toctree-l2"><a class="reference internal" href="social.html#linkedin-login">LinkedIn Login</a><ul>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-linkedin-application">Create a LinkedIn Application</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#enable-linkedin-permissions">Enable LinkedIn Permissions</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#create-a-linkedin-directory">Create a LinkedIn Directory</a></li>
<li class="toctree-l3"><a class="reference internal" href="social.html#id2">Test it Out</a></li>
<li class="toctree-l2"><a class="reference internal" href="social.html#json-api">JSON API</a></li>
<li class="toctree-l1"><a class="reference internal" href="forgot-password.html">Forgot Password</a><ul>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#configure-the-workflow">Configure the Workflow</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#try-it">Try it!</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#forgot-uri">Forgot URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#forgot-next-uri">Forgot Next URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#change-password-uri">Change Password URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#change-password-next-uri">Change Password Next URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="forgot-password.html#i18n">i18n</a></li>
<li class="toctree-l1"><a class="reference internal" href="logout.html">Logout</a><ul>
<li class="toctree-l2"><a class="reference internal" href="logout.html#uri">URI</a><ul>
<li class="toctree-l3"><a class="reference internal" href="logout.html#next-query-parameter">Next Query Parameter</a></li>
<li class="toctree-l2"><a class="reference internal" href="logout.html#next-uri">Next URI</a></li>
<li class="toctree-l2"><a class="reference internal" href="logout.html#events">Events</a></li>
<li class="toctree-l1"><a class="reference internal" href="request-authentication.html">HTTP Request Authentication</a><ul>
<li class="toctree-l2"><a class="reference internal" href="request-authentication.html#http-basic-authentication">HTTP Basic Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="request-authentication.html#token-authentication">Token Authentication</a><ul>
<li class="toctree-l3"><a class="reference internal" href="request-authentication.html#get-a-token">Get a Token</a><ul>
<li class="toctree-l4"><a class="reference internal" href="request-authentication.html#curl">cURL</a></li>
<li class="toctree-l4"><a class="reference internal" href="request-authentication.html#html-form-and-ajax">HTML Form and AJAX</a></li>
<li class="toctree-l4"><a class="reference internal" href="request-authentication.html#origin-or-referer-required">Origin or Referer Required</a></li>
<li class="toctree-l4"><a class="reference internal" href="request-authentication.html#https-required">HTTPS Required</a></li>
<li class="toctree-l2"><a class="reference internal" href="request-authentication.html#api-key-authentication">API Key Authentication</a><ul>
<li class="toctree-l3"><a class="reference internal" href="request-authentication.html#determining-api-key-authentication">Determining API Key Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="request.html">Request Context</a><ul>
<li class="toctree-l2"><a class="reference internal" href="request.html#current-user-account">Current User Account</a><ul>
<li class="toctree-l3"><a class="reference internal" href="request.html#account-resolver">Account Resolver</a></li>
<li class="toctree-l3"><a class="reference internal" href="request.html#request-attributes">Request Attributes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="request.html#request-attribute-names">Request Attribute Names</a></li>
<li class="toctree-l3"><a class="reference internal" href="request.html#http-servlet-request-api">HTTP Servlet Request API</a><ul>
<li class="toctree-l4"><a class="reference internal" href="request.html#httpservletrequest-getremoteuser">HttpServletRequest getRemoteUser()</a></li>
<li class="toctree-l4"><a class="reference internal" href="request.html#httpservletrequest-getuserprincipal">HttpServletRequest getUserPrincipal()</a></li>
<li class="toctree-l2"><a class="reference internal" href="request.html#stormpath-application">Stormpath Application</a><ul>
<li class="toctree-l3"><a class="reference internal" href="request.html#application-resolver">Application Resolver</a></li>
<li class="toctree-l3"><a class="reference internal" href="request.html#id2">Request Attributes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="request.html#default-request-attribute-name">Default Request Attribute Name</a></li>
<li class="toctree-l4"><a class="reference internal" href="request.html#custom-request-attribute-names">Custom Request Attribute Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="request.html#stormpath-client">Stormpath Client</a><ul>
<li class="toctree-l3"><a class="reference internal" href="request.html#client-resolver">Client Resolver</a></li>
<li class="toctree-l3"><a class="reference internal" href="request.html#id3">Request Attributes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="request.html#id4">Default Request Attribute Name</a></li>
<li class="toctree-l4"><a class="reference internal" href="request.html#id5">Custom Request Attribute Names</a></li>
<li class="toctree-l1"><a class="reference internal" href="access-control.html">Access Control</a><ul>
<li class="toctree-l2"><a class="reference internal" href="access-control.html#authentication">Authentication</a><ul>
<li class="toctree-l3"><a class="reference internal" href="access-control.html#unauthenticatedhandler">UnauthenticatedHandler</a></li>
<li class="toctree-l2"><a class="reference internal" href="access-control.html#exclusions">Exclusions</a></li>
<li class="toctree-l1"><a class="reference internal" href="i18n.html">Internationalization (i18n)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="i18n.html#languages">Languages</a></li>
<li class="toctree-l2"><a class="reference internal" href="i18n.html#request-locale">Request Locale</a></li>
<li class="toctree-l2"><a class="reference internal" href="i18n.html#jsp-tag-library">JSP Tag Library</a></li>
<li class="toctree-l2"><a class="reference internal" href="i18n.html#i18n-properties">i18n.properties</a></li>
<li class="toctree-l1"><a class="reference internal" href="events.html">Events</a><ul>
<li class="toctree-l2"><a class="reference internal" href="events.html#requesteventlistener">RequestEventListener</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html#id2">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html#listener-best-practices">Listener Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="caching.html">Caching</a><ul>
<li class="toctree-l2"><a class="reference internal" href="caching.html#in-process-cache">In-Process Cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="caching.html#disable-caching">Disable Caching</a><ul>
<li class="toctree-l3"><a class="reference internal" href="caching.html#default-ttl">Default TTL</a></li>
<li class="toctree-l3"><a class="reference internal" href="caching.html#default-tti">Default TTI</a></li>
<li class="toctree-l3"><a class="reference internal" href="caching.html#cache-regions">Cache Regions</a></li>
<li class="toctree-l3"><a class="reference internal" href="caching.html#client-cache-regions">Client Cache Regions</a></li>
<li class="toctree-l2"><a class="reference internal" href="caching.html#shared-cache">Shared Cache</a><ul>
<li class="toctree-l3"><a class="reference internal" href="caching.html#nonce-cache-region">Nonce Cache Region</a></li>
<li class="toctree-l1"><a class="reference internal" href="idsite.html">ID Site</a><ul>
<li class="toctree-l2"><a class="reference internal" href="idsite.html#how-does-it-work">How Does It Work?</a></li>
<li class="toctree-l2"><a class="reference internal" href="idsite.html#enable-id-site">Enable ID Site</a></li>
<li class="toctree-l2"><a class="reference internal" href="idsite.html#configure-your-application">Configure Your Application</a></li>
<li class="toctree-l2"><a class="reference internal" href="idsite.html#try-it">Try It!</a></li>
<li class="toctree-l1"><a class="reference internal" href="views.html">Custom Views</a><ul>
<li class="toctree-l2"><a class="reference internal" href="views.html#jsp-views">JSP Views</a></li>
<li class="toctree-l2"><a class="reference internal" href="views.html#css">CSS</a></li>
<li class="toctree-l2"><a class="reference internal" href="views.html#internationalization-i18n">Internationalization (i18n)</a></li>
<li class="toctree-l2"><a class="reference internal" href="views.html#change-a-default-view">Change a Default View</a></li>
<li class="toctree-l2"><a class="reference internal" href="views.html#view-template">View Template</a></li>
<li class="toctree-l1"><a class="reference internal" href="appendix.html">Appendix</a><ul>
<li class="toctree-l2"><a class="reference internal" href="appendix/web-stormpath-properties.html">web.stormpath.properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/i18n-properties.html">i18n.properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/stormpath-css.html">stormpath.css</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/change-password.html">/WEB-INF/jsp/stormpath/change-password.jsp</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/forgot-password.html">/WEB-INF/jsp/stormpath/forgot-password.jsp</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/login.html">/WEB-INF/jsp/stormpath/login.jsp</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/register.html">/WEB-INF/jsp/stormpath/register.jsp</a></li>
<li class="toctree-l2"><a class="reference internal" href="appendix/verify.html">/WEB-INF/jsp/stormpath/verify.jsp</a></li>
        </div>
      </div>
    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">Stormpath Java Servlet Plugin</a>
      </nav>
      <div class="wy-nav-content">
        <div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="index.html">Docs</a> &raquo;</li>
    <li>Quickstart</li>
    <li class="wy-breadcrumbs-aside">
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
  <blockquote>
<div></div></blockquote>
<div class="section" id="quickstart">
<span id="setup"></span><h1>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h1>
<p>This quickstart demonstrates the fastest way to enable Stormpath in a Servlet 3.0 (or later) Java web application.
It should take about 5 minutes start to finish.  Let&#8217;s get started!</p>
<p>Topics:</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#get-an-api-key" id="id5">Get an API Key</a></li>
<li><a class="reference internal" href="#add-the-project" id="id6">Add the Stormpath Java Servlet Plugin</a></li>
<li><a class="reference internal" href="#try-it" id="id7">Try it!</a><ul>
<li><a class="reference internal" href="#any-problems" id="id8">Any Problems?</a></li>
<li><a class="reference internal" href="#next-steps" id="id9">Next Steps</a></li>
<div class="section" id="get-an-api-key">
<span id="get-api-key"></span><h2><a class="toc-backref" href="#id5">Get an API Key</a><a class="headerlink" href="#get-an-api-key" title="Permalink to this headline">¶</a></h2>
<p>All communication with Stormpath must be authenticated with an API Key.</p>
<ol class="arabic">
<li><p class="first">If you haven’t already, <a class="reference external" href="https://api.stormpath.com/register">sign up for Stormpath for free</a>.  You’ll be sent a verification email.</p>
<li><p class="first">Click the link in the verification email.</p>
<li><p class="first">Log in to the <a class="reference external" href="https://api.stormpath.com">Stormpath Admin Console</a> using the email address and password you used during registration and the assigned tenant id.</p>
<li><p class="first">Click the <strong>Create API Key</strong> or <strong>Manage Existing Keys</strong> button.</p>
<li><p class="first">Under <strong>Security Credentials</strong>, click <strong>Create API Key</strong>.</p>
<p>This will generate your API Key and download it to your computer as an <code class="docutils literal"><span class="pre">apiKey.properties</span></code> file.</p>
<li><p class="first">Save the file in your home directory in the following location:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">~/.stormpath/apiKey.properties</span></code> on Unix, Linux and Mac OS</li>
<li><code class="docutils literal"><span class="pre">C:\Users\YOUR_USERNAME\.stormpath\apiKey.properties</span></code> on Windows</li>
<li><p class="first">Change the file permissions to ensure only you can read this file and not accidentally write or modify it. For example:</p>
<blockquote>
<div><div class="highlight-bash"><div class="highlight"><pre><span></span>$ chmod go-rwx ~/.stormpath/apiKey.properties
$ chmod u-w ~/.stormpath/apiKey.properties
</pre></div>
</div></blockquote>
<p>On Windows, you can <a class="reference external" href="http://msdn.microsoft.com/en-us/library/bb727008.aspx">set file permissions similarly</a>.</p>
<div class="section" id="add-the-project">
<h2><a class="toc-backref" href="#id6">Add the Stormpath Java Servlet Plugin</a><a class="headerlink" href="#add-the-project" title="Permalink to this headline">¶</a></h2>
<p id="dependency-jar">This step allows you to use Stormpath <em>without a single line of code or configuration</em>.  How amazing is that?</p>
<p>Using your favorite dependency resolution build tool like Maven or Gradle, ensure your web (.war) project/module depends on <code class="docutils literal"><span class="pre">stormpath-servlet-plugin-1.5.4.jar</span></code>. For example:</p>
<p><strong>Maven</strong>:</p>
<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;dependency&gt;</span>
    <span class="nt">&lt;groupId&gt;</span>com.stormpath.sdk<span class="nt">&lt;/groupId&gt;</span>
    <span class="nt">&lt;artifactId&gt;</span>stormpath-servlet-plugin<span class="nt">&lt;/artifactId&gt;</span>
    <span class="nt">&lt;version&gt;</span>1.5.4<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</pre></div>
<p><strong>Gradle</strong>:</p>
<div class="highlight-groovy"><div class="highlight"><pre><span></span><span class="n">dependencies</span> <span class="o">{</span>
    <span class="n">compile</span> <span class="s1">&#39;com.stormpath.sdk:stormpath-servlet-plugin:1.5.4&#39;</span>
<span class="o">}</span>
</pre></div>
<p>Ensure that all resolved dependencies are in your web application&#8217;s <code class="docutils literal"><span class="pre">/WEB-INF/lib</span></code> directory.</p>
<p>That&#8217;s it!  You&#8217;re ready to start using Stormpath in your web application!  Can you believe how easy that was?</p>
<div class="section" id="try-it">
<h2><a class="toc-backref" href="#id7">Try it!</a><a class="headerlink" href="#try-it" title="Permalink to this headline">¶</a></h2>
<p>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!</p>
<p>Don’t believe it? Try it! Start up your web application, and we&#8217;ll walk you through the basics:</p>
<ul class="simple">
<li>Navigate to <code class="docutils literal"><span class="pre">/register</span></code>. 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 (<code class="docutils literal"><span class="pre">/</span></code> by default).</li>
<li>Submit a <code class="docutils literal"><span class="pre">POST</span></code> (not a <code class="docutils literal"><span class="pre">GET</span></code>) to <code class="docutils literal"><span class="pre">/logout</span></code>. You will be logged out of your account and then redirected back to <code class="docutils literal"><span class="pre">/login</span></code> by default.  You can learn more about <code class="docutils literal"><span class="pre">POST</span></code> for logout on the <a class="reference internal" href="logout.html#logout"><span class="std std-ref">Logout</span></a> page.</li>
<li>After logging out, navigate to <code class="docutils literal"><span class="pre">/login</span></code>. On the lower-right, click the <strong>Forgot Password?</strong> link, and you&#8217;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&#8217;ll be able to set a new password!</li>
<p>Wasn&#8217;t that easy?!</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>You probably noticed that you couldn&#8217;t register a user account without specifying a sufficiently strong password.
This is because, by default, Stormpath enforces certain password strength rules.</p>
<p class="last">If you&#8217;d like to change these password strength rules, you can do so easily. Visit the <a class="reference external" href="https://api.stormpath.com">Stormpath Admin Console</a>,
navigate to your your application&#8217;s user <code class="docutils literal"><span class="pre">Directory</span></code>, and then choose the <code class="docutils literal"><span class="pre">Password</span> <span class="pre">Policy</span></code> tab on the <code class="docutils literal"><span class="pre">Policies</span></code> page.</p>
<div class="section" id="any-problems">
<h3><a class="toc-backref" href="#id8">Any Problems?</a><a class="headerlink" href="#any-problems" title="Permalink to this headline">¶</a></h3>
<p>Did you experience any problems with this quickstart?  It might not have worked perfectly for you if:</p>
<li><p class="first">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:</p>
<div class="highlight-properties"><div class="highlight"><pre><span></span><span class="na">stormpath.enabled</span> <span class="o">=</span> <span class="s">false</span>
</pre></div>
<li><p class="first">you have more than one Application registered with Stormpath.  If this is the case, you&#8217;ll need to configure your
web application&#8217;s Stormpath <code class="docutils literal"><span class="pre">href</span></code>, found in the admin console. Once you get the <code class="docutils literal"><span class="pre">href</span></code>, add the following to
your <code class="docutils literal"><span class="pre">stormpath.properties</span></code> file (where <code class="docutils literal"><span class="pre">YOUR_APPLICATION_ID</span></code> is your web app&#8217;s actual Stormpath
Application ID):</p>
<div class="highlight-properties"><div class="highlight"><pre><span></span><span class="na">stormpath.application.href</span> <span class="o">=</span> <span class="s">https://api.stormpath.com/v1/applications/YOUR_APPLICATION_ID</span>
</pre></div>
<li><p class="first">your web app already uses web frameworks that make heavy use of servlet filters, like Spring or Apache Shiro.
These could cause filter ordering conflicts, but the fix is easy - you&#8217;ll need to manually add a few lines to your
web app&#8217;s <code class="docutils literal"><span class="pre">/WEB-INF/web.xml</span></code> file.  Ensure the following chunk is at or near the top of your filter mapping
definitions:</p>
<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;filter-mapping&gt;</span>
    <span class="nt">&lt;filter-name&gt;</span>StormpathFilter<span class="nt">&lt;/filter-name&gt;</span>
    <span class="nt">&lt;url-pattern&gt;</span>/*<span class="nt">&lt;/url-pattern&gt;</span>
<span class="nt">&lt;/filter-mapping&gt;</span>
</pre></div>
<p>If there is anything else, please let us know!  Our <a class="reference external" href="https://support.stormpath.com">Support Team</a> is always happy to help!</p>
<div class="section" id="next-steps">
<h2><a class="toc-backref" href="#id9">Next Steps</a><a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
<p>That was just a little example of how much functionality is ready right out of the box.  You get so much more, like:</p>
<ul class="simple">
<li>View customization with your own look and feel</li>
<li>Internationalization (i18n) for all views</li>
<li>Token authentication for Javascript Single Page Applications (SPAs) and mobile clients like those on iOS and Android.</li>
<li>Account email verification (verify an email address is valid before enabling a user account)</li>
<li>Secure CSRF protection on views with forms</li>
<li>A simple security assertion/authorization framework</li>
<li>Events to react to registration, login, logout, etc.</li>
<li>Session-free (stateless) secure user account identification</li>
<li>HTTP Basic and OAuth2 authentication</li>
<li>and more!</li>
<p>Dig in to our <a class="reference external" href="https://github.com/stormpath/stormpath-sdk-java/tree/master/examples">examples</a> to see more Stormpath Java Servlet Plugin in action.</p>
<p>Continue on to find out how to leverage this functionality and customize it for your own needs.</p>
           </div>
          </div>
          <footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
        <a href="config.html" class="btn btn-neutral float-right" title="Configuration" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
        <a href="about.html" class="btn btn-neutral" title="About" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
  <div role="contentinfo">
        &copy; Copyright 2017, Stormpath, Inc.
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 
        </div>
      </div>
    </section>
    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'1.5.4',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/js/theme.js"></script>
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
  </script>
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

quickstart.html

Latest commit

History

quickstart.html

File metadata and controls
