{"id":25684708,"url":"https://github.com/kudzaiprichard/springboot-jwt-auth","last_synced_at":"2025-07-11T15:17:12.225Z","repository":{"id":178178731,"uuid":"661453383","full_name":"kudzaiprichard/springboot-jwt-auth","owner":"kudzaiprichard","description":"Role based authentication with java spring boot JSON WEB TOKEN","archived":false,"fork":false,"pushed_at":"2023-10-12T19:51:10.000Z","size":518,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-24T17:41:22.053Z","etag":null,"topics":["intelij","java","jsonwebtoken","jwt","jwt-authentication","mvc","mvc-architecture","rest-api","restful-api","role-based-access-control","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kudzaiprichard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-02T22:23:14.000Z","updated_at":"2024-11-01T19:22:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"8f5df2be-5582-40d2-951a-5909489df707","html_url":"https://github.com/kudzaiprichard/springboot-jwt-auth","commit_stats":null,"previous_names":["kudzaiprichard/springboot-jwt-auth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kudzaiprichard/springboot-jwt-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kudzaiprichard%2Fspringboot-jwt-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kudzaiprichard%2Fspringboot-jwt-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kudzaiprichard%2Fspringboot-jwt-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kudzaiprichard%2Fspringboot-jwt-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kudzaiprichard","download_url":"https://codeload.github.com/kudzaiprichard/springboot-jwt-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kudzaiprichard%2Fspringboot-jwt-auth/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264837928,"owners_count":23671119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intelij","java","jsonwebtoken","jwt","jwt-authentication","mvc","mvc-architecture","rest-api","restful-api","role-based-access-control","spring-boot"],"created_at":"2025-02-24T17:32:31.754Z","updated_at":"2025-07-11T15:17:12.174Z","avatar_url":"https://github.com/kudzaiprichard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kudzaiprichard/springboot-jwt-auth\"\u003e\n    \u003cimg src=\"images/jwt-banner-2.png\" alt=\"Logo\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eJWT Auth\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    A simple implementation of spring security using jason web tokens\n    \u003cbr /\u003e\n  \u003c/p\u003e\n  \u003cbr/\u003e\n\u003c/div\u003e\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#what-is-jwt-authentication\"\u003eWhat is JWT Authentication?\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#defining-terminology\"\u003eDefining Terminology\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#project-design\"\u003eProject Design\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n# About The Project\n## What is JWT Authentication?\n`JSON Web Tokens` are an open, industry `standard RFC 7519` method for representing claims securely between two parties. When we create `REST APIs`, then we don't want that any one can access those apis. `REST APIs`, will only be accessed by the authenticated user. We `authenticate` our user with the help of `jwt`.\n\n## Defining Terminology\nThese are the terms we need to address:\n\n* `Authentication` refers to the process of verifying the identity of a user, based on provided credentials. A common example is entering a username and a password when you log in to a website. You can think of it as an answer to the question Who are you?.\n* `Authorization` refers to the process of determining if a user has proper permission to perform a particular action or read particular data, assuming that the user is successfully authenticated. You can think of it as an answer to the question Can a user do/read this?.\n* `Principle` refers to the currently authenticated user.\n* `Granted authority` refers to the permission of the authenticated user.\n* `Role` refers to a group of permissions of the authenticated user.\n\n## Project Design\n### Architecture\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"images/spring-boot-security-auth-architecture.png\" alt=\"architecture Diagram\" \u003e\n\u003c/div\u003e\n\n* `WebSecurityConfig` is the crux of our security implementation. It configures cors, csrf, session management, rules for protected resources. \n* `UserDetailsService` interface has a method to load User by username and returns a `UserDetails` object that Spring Security can use for authentication and validation.\n* `UserDetails` contains necessary information (such as: username, password, authorities) to build an `Authentication` object.\n* `UsernamePasswordAuthenticationToken` gets {username, password} from login Request, `AuthenticationManager` will use it to authenticate a login account.\n* `AuthenticationManager` has a `DaoAuthenticationProvider` (with help of `UserDetailsService` \u0026 `PasswordEncoder`) to validate `UsernamePasswordAuthenticationToken` object. If successful, `AuthenticationManager` returns a fully populated `Authentication` object (including granted authorities).\n* `OncePerRequestFilter` makes a single execution for each request to our API. It provides a doFilterInternal() method that we will implement parsing \u0026 validating JWT, loading User details (using UserDetailsService), checking `Authorization` (using `UsernamePasswordAuthenticationToken`).\n* `AuthenticationEntryPoint` will catch authentication error. Repository contains `UserRepository` \u0026 `RoleRepository` to work with Database, will be imported into `Controller`.Controller receives and handles request after it was filtered by `OncePerRequestFilter`.\n* `AuthController` handles signup/login requests\n* `TestController` has accessing protected resource methods with role based validations.\n\n### Security filter chain\nSpring Security maintains a filter chain internally where each of the filters has a particular responsibility and \nfilters are added or removed from the configuration depending on which services are required. The ordering of the \nfilters is important as there are dependencies between them.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"images/filterchain.png\" alt=\"endpoints\" \u003e\n\u003c/div\u003e\n\nThe client sends a request to the application, and the container creates a `FilterChain`, \nwhich contains the `Filter` instances and `Servlet` that should process the `HttpServletRequest`, \nbased on the path of the request URI. In a Spring MVC application, the `Servlet` is an instance of `DispatcherServlet`.\nAt most, one `Servlet` can handle a single `HttpServletRequest` and `HttpServletResponse`. However, more than one `Filter` can be used to:\n\n* Prevent downstream `Filter` instances or the `Servlet` from being invoked. In this case, the `Filter` typically writes the `HttpServletResponse`.\n\n* Modify the `HttpServletRequest` or `HttpServletResponse` used by the downstream `Filter` instances and the `Servlet`.\n\nThe power of the `Filter` comes from the `FilterChain` that is passed into it.\n\n\u003cimg src=\"images/filter_diagram.png\" alt=\"filter diagram\"\u003e\n\nWhen you add the Spring Security framework to your application, it automatically registers a filters chain that intercepts \nall incoming requests. This chain consists of various filters, and each of them handles a particular use case.\n\nFor example:\n\n* Check if the requested URL is publicly accessible, based on configuration.\n* In case of session-based authentication, check if the user is already authenticated in the current session.\n* Check if the user is authorized to perform the requested action, and so on.\n\n### Endpoit Design\nBelow is a screenshot of the project user creation and authentication restful api endpoints and the HTTP Method supported by each endpoint\n\n\u003cimg src=\"images/auth_jwt_endpoints.png\" alt=\"endpoints\" \u003e\n\n### UML Diagram\nSystem uses a single user table for user creation and authentication\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"images/jwt_auth.png\" alt=\"UML Diagram\" \u003e\n\u003c/div\u003e\n\n### Sequence Diagram\nSequence diagram showing how you can create an account, login and access a `secured \nrestfull endpoint/resource` using a `jwt token` you get when you `authenticate` your account.\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"images/sequence-diagram.png\" alt=\"Sequence Diagram\" \u003e\n\u003c/div\u003e\u003e\n\n### Built With\nUsed `Java` `spring boot` , `MySQL` and `Jason Web Token` to build the rest api, including postman for testing.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"images/logo/java.png\" alt=\"spring\" width=\"100\" height=\"80\" style=\"margin-right: 20px;\"\u003e \n    \u003cimg src=\"images/logo/spring.png\" alt=\"spring\" width=\"160\" height=\"82\" style=\"margin-right: 20px;\"\u003e \n    \u003cimg src=\"images/logo/mysql.webp\" alt=\"mysql\" width=\"110\" height=\"80\" style=\"margin-right: 20px;\"\u003e\n    \u003cimg src=\"images/logo/jwt.png\" alt=\"jwt\" width=\"85\" height=\"80\"\u003e\n\u003c/div\u003e\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\n### Prerequisites\n\nYou should have the below software installed in your pc :\n* JDK 20 and JRE\n* MySQL\n* and your preferred IDE or text editor\n\n  \n\n### Installation\n\n1. Get a free API Key at [https://github.com/settings/tokens](https://github.com/settings/tokens)\n2. Clone the repo\n\n   ```sh\n   git clone https://github.com/kudzaiprichard/springboot-jwt-auth\n   ```\n\n3. Open project in IDE or text editor\n4. Let maven download all necessary dependency for the project to run\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!--CONTRIBUTING--\u003e\n## Contributing\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/ExampleFeature`)\n3. Commit your Changes (`git commit -m 'Add some ExampleFeature'`)\n4. Push to the Branch (`git push origin feature/ExampleFeature`)\n5. Open a Pull Request\n\n### :fire: Contribution\n\n Your contributions are always welcome and appreciated. Following are the things you can do to contribute to this project.\n\n 1. **Report a bug** \u003cbr\u003e\n If you think you have encountered a bug, and I should know about it, feel free to report it [here]() and I will take care of it.\n\n 2. **Request a feature** \u003cbr\u003e\n You can also request for a feature [here](), and if it will viable, it will be picked for development.  \n\n 3. **Create a pull request** \u003cbr\u003e\n It can't get better than this, your pull request will be appreciated by the community. You can get started by picking up any open issues from [here]() and make a pull request.\n\n \u003e If you are new to open-source, make sure to check read more about it [here](https://www.digitalocean.com/community/tutorial_series/an-introduction-to-open-source) and learn more about creating a pull request [here](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github).\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\n\u003e Distributed under the MIT License. See `LICENSE.txt` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\n\u003eKudzai P Matizirofa - [linkedin.com/in/kudzai-prichard](www.linkedin.com/in/kudzai-prichard) - \u003ckudzaiprichard@gmail.com\u003e\n\nProject Link: [https://github.com/kudzaiprichard/springboot-jwt-auth](https://github.com/kudzaiprichard/springboot-jwt-auth)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n## Acknowledgments\n\nlist of resources I found helpful and would like to give credit to.\n* [Spring Security with JWT for REST API](https://www.toptal.com/spring/spring-security-tutorial#:~:text=Spring%20Security%20Filters%20Chain\u0026text=This%20chain%20consists%20of%20various,authenticated%20in%20the%20current%20session.)\n* [Choose an Open Source License](https://choosealicense.com)\n* [Restful Api Explained](https://aws.amazon.com/what-is/restful-api/)\n* [Jason Web Tokens](https://jwt.io/)\n* [Spring Boot docs](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/)\n* [GitHub Pages](https://pages.github.com) \n* [MySql docs](https://dev.mysql.com/doc/)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkudzaiprichard%2Fspringboot-jwt-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkudzaiprichard%2Fspringboot-jwt-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkudzaiprichard%2Fspringboot-jwt-auth/lists"}