This site is the archived OWASP Foundation Wiki and is no longer accepting Account Requests.
To view the new OWASP Foundation website, please visit https://owasp.org
ESAPI Getting Started Guide
Getting Started with OWASP ESAPI
ESAPI is very easy to use. This tutorial shows how to get a simple application working with the reference implementation of ESAPI. Please remember that the reference implementation is a simple example. The Authenticator uses a text-based password file. This is to make it easy to test ESAPI without installing a database or directory. Enterprises will want to create their own implementation of the API that works with their identity management solution.
Step 1: Setting up a resources directory
Create a directory to hold ESAPI resources. This should be a secure location as it will contain a significant amount of security information. For example, you might create a directory called "C:\resources" and use the operating system access control mechanisms to restrict access.
Step 2: Setting ESAPI configuration properties
Download the default ESAPI.properties file. Edit the MasterPassword property and choose a long, difficult-to-guess string as the security of your application depends on it.
- MasterPassword=xxxxx
Step 3: Configuring user accounts
The simplest way to get started is to create an "admin" account to work with. ESAPI has a command line tool that will create your users.txt file and
java -D org.owasp.esapi.resources="C:\resources" -classpath owasp-esapi-java-1.1.1.jar org.owasp.esapi.Authenticator Alice test admin
Step 4: Hello, ESAPI!
You should be able to use any application container. The instructions below are for Tomcat.
- Clean Tomcat 5.5/6.0 install
- Create a new folder named “test” in the webapps folder
- add test.jsp to that folder
- add a “WEB-INF/lib” folder and put esapi-1.1.1.jar in it
- edit catalina.bat
- add the following line right under the line that contains “set JPDA=”
- set JAVA_OPTS=-Dorg.owasp.esapi.resources="C:\resources" (use your directory from step 2)
- run startup.bat
- browse to http://localhost:8080/test/test.jsp?username=abc&password=def
<html> <body> <%@page import="org.owasp.esapi.*"%> <%@page import="org.owasp.esapi.errors.*"%> <%@page import="org.owasp.esapi.interfaces.*"%> <%@page import="java.util.*"%> <%@page import="java.io.*"%>
<%
try {
// use this in ESAPI 1.2 instead of -Dorg.owasp.esapi.resources="C:\resources" // ((SecurityConfiguration)ESAPI.securityConfiguration()).setResourceDirectory( "C:/resources" ); User user = ESAPI.authenticator().login(request, response); String[] ignore = { "password" }; Logger logger = Logger.getLogger("Hello ESAPI", getClass().getName()); logger.logHTTPRequest(Logger.SECURITY, request, Arrays.asList(ignore));
%>
Hello, <%=user.getAccountName()%>
Last Successful Login: <%=user.getLastLoginTime() %>
Last Failed Login: <%=user.getLastFailedLoginTime() %>
Failed Login Count: <%=user.getFailedLoginCount() %>
Current Roles: <%=user.getRoles() %>
Last Host Name: <%=user.getLastHostAddress() %>
Current Cookie: <script>document.write(document.cookie)</script>
<%
ESAPI.httpUtilities().changeSessionIdentifier(); // user.logout();
} catch( EnterpriseSecurityException e ) {
%>
Error occurred
User message: <%=e.getUserMessage()%>
Log message: <%=e.getLogMessage()%>
<% } %>
</body> </html>
