- Project Overview
- Features
- Prerequisites
- Maven Dependencies
- Project Structure and Key Directories
- Setup and Installation
- Running the Application
- Contributions
- License
The SAS Spring Security Web Application is a Java-based account management and authentication web application.
It employs Spring Framework technologies, including Spring MVC and Spring Security, and is deployed as a JAR file suitable for any Java EE web container.
- User Authentication: Log in and session management using Spring Security.
- Account Management: Add and manage user accounts.
- Database Support: Store user information in the MySQL database.
- Password encryption: Password hash encoded before persistence.
- Error Handling: Custom error responses for various scenarios.
- Eclipse IDE for Enterprise Java and Web Developers 2024-03 (4.31.0)
- Java 17 or newer
- Maven 3.6 or newer
- Servlet container (e.g., Tomcat 10 or newer)
- Implementation dependencies:
- Test dependencies:
src
├── main
│ ├── java => Contains Java source files, including controllers, services, and configuration.
│ │ └── me
│ │ └── scriptori
│ │ └── saswebapp => The Root Package of the Java Sprint and Spring Security Java Code.
│ │ ├── config => Package for the Configuration files for Spring.
│ │ ├── controller => Package for the Controllers of the Web application.
│ │ ├── dto => Package for the Data Transfer Objects (DTO).
│ │ ├── handler => Package for Spring MVC handles,
│ │ └── initializer => Package with web application and servlet initializers.
│ └── webapp
│ └── WEB-INF => Contains JSP views, web.xml, and other web resources like CSS and assets.
│ ├── resources
│ │ └── css => Directory with CSS files for styling.
│ ├── views => Directory with the JSP files for the user interface.
│ └── web.xml => Configuration file used in Java web applications to define deployment settings and servlet mappings.
└── test
└── java
└── me
└── scriptori
└── saswebapp
├── config => Package for the Configurations test cases.
├── controller => Package for the Controller's test cases.
├── handler => Package for the Handler's test cases.
└── initializer => Package for the Initializer's test cases.
Below are the steps for the setup and the installation.
- Clone the repository:
> git clone https://github.com/scriptori/sas-spring-security.git > cd sas-spring-security
- Build the project:
> mvn clean install - Deploy the JAR file to your Servlet container: Place the generated JAR file from target/ directory into your servlet container's webapps/ directory.
Download and install MySQL Community Server from the official website directly on your local machine, following the installation instructions for your operating system. It is suitable for development purposes or if you only need a database server for personal projects. For Mac using ARM 64-bit, by the time I am writing this instruction (05/13/2024), I recommend using version 8.0.37.
- Configure MySQL: After the installation, configure MySQL by running the MySQL Server instance.
You may need to start the MySQL Server manually. Using the Terminal application and running commands like,
> sudo /usr/local/mysql/support-files/mysql.server start - Verify Installation:
It's crucial to verify that MySQL Server is installed and running correctly. To do this, open a command prompt (on Windows) and type the following command:
When prompted, Enter the root password you set during installation. If MySQL Server runs correctly, you'll log in to the command-line client.
> mysql -u root -p - Reinstall MySQL (if necessary): If MySQL was not installed correctly or if you continue to encounter issues, consider reinstalling MySQL following the installation instructions provided by MySQL.
That's it! You've successfully installed MySQL Server locally on your machine. You can now use MySQL to create databases, tables, and other operations.
Download and install MySQL Workbench directly on your local machine. For Mac using ARM 64-bit, by the time I am writing this instruction (05/13/2024), I recommend using version 8.0.33, available on the archived version page.
- Creation of the Screma (database) sas-security:
A database schema organizes and defines the relationships between tables, views, stored procedures, and other elements within a specific database.
To create the two tables (users and authority) required by the default configuration, a schema called sas-security must be created. - Creation of the Tables (users and authority):
The default Spring Security configuration used in this project requires the creation of two tables:
-
The users table:
Steps to create a table called users with the username, password, and enabled columns:- Open MySQL Workbench: Start MySQL Workbench and connect to your database.
- Select Database: Choose the sas-security schema from the Schemas section on the left side where you want to create your table.
- Open SQL Editor: Click the "File" menu and select "New Query Tab" to open a new SQL editor.
- Write the SQL Query: In the SQL editor, type the following SQL statement to create the users table:
CREATE TABLE users ( username VARCHAR(45) NOT NULL, password VARCHAR(256) NOT NULL, enabled VARCHAR(5), PRIMARY KEY (username) );
Notice the password column must be sized enough to store an encoded password. In this case, 256 characters are being used.
- Execute the Query: Click the lightning bolt icon ("Execute the selected portion of the script" or "Execute the entire script") to run your SQL command.
- Verify the Table Creation: You can verify that the table was created by expanding your schema in the Schemas section and checking under the "Tables" directory to see if the users table appears.
These steps above will create a table named users with three columns: code>username, password, and enabled. The username column is also set as the primary key to ensure that each username is unique in the table.
-
The authority table:
Steps to create a table called authority with the username and authority columns:- Repeat steps *a* to *c* above.
- Repeat step *d*, using the following SQL statement to create the authority table:
SQL statement to create the authority table:CREATE TABLE authority ( username VARCHAR(45) NOT NULL, authority VARCHAR(45) NOT NULL, PRIMARY KEY (username) );
- Repeat steps *e* and *f* above, checking under the "Tables" directory to see if the authority table appears.
These steps above will create a table named authority with two columns: username and authority. The username column is also the primary key to ensure that each username is unique in the table.
-
- Configuration of the dataSource in the SASDataSourceConfig class:
The following information is needed to set the dataSource properties in the SASDataSourceConfig class: username, password, URL, and driver class name for the MySQL database (schema) you created. Here's how to find each piece of information in MySQL Workbench:
- Username:
The username is often set up when the database is created. MySQL has a superuser named root by default, but other users can be created and used.
In this project, the default superuser is used.
Use the superuser in the dataSource.setUsername(). - Password:
The "Users and Privileges" section manages the user's password.
If you need to set or change a user's password:
- Select the user in the "Users and Privileges" window.
- Click the "Change Password" button.
- Use this password in the dataSource.setPassword().
- URL:
The URL for your MySQL connection typically includes the host (e.g., localhost or a specific IP address), port number (the default is 3306 for MySQL), and database name.- To find the database name:
- In MySQL Workbench, look at the schemas listed in the "Schemas" section on the left sidebar.
- Select or create the database you want to connect to. This project is called sas-security.
- Construct the URL using the following format: jdbc:mysql://[host]:[port]/[database-name]. The local database looks like this for this project: jdbc:mysql://localhost:3306/sas-security.
- To find the database name:
- Driver Class Name:
- When using Connector/J (the official JDBC driver for MySQL), the driver class name for MySQL is com.mysql.cj.jdbc.Driver.
- Ensure you have the MySQL Connector/J jar file in your project dependencies to use this driver class.
- Username:
- Confirming the Connection to the Database
Once all these properties have been set in SASDataSourceConfig, the connection can be tested directly from the code or using tools like MySQL Workbench to ensure the settings are correct and the database is accessible:
- Testing from Code:
When you start the project application, the SASDataSourceConfig attempts to connect to the database using the configured DriverManagerDataSource. The application's initial page (index.xml) should be displayed with no error (typically the 404 error). - MySQL Workbench:
Use the connection details to connect to the database directly through the Workbench's home screen by setting up a new connection with the exact details.
- Testing from Code:
- Start your servlet container.
- Access the Web Application at http://localhost:8080/sas-spring-security/.
Contributions are welcome! Please submit pull requests or open issues to discuss proposed changes or enhancements.
Copyright 2024 Scriptori - Claudio de Souza
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.