DOCSEARCHbyAlgolia
Submit Docs

ShiroJwt Documentation

repository·master·Indexed 20 days ago

https://github.com/dolyw/shirojwt

A Spring Boot starter and template integrating Apache Shiro with Java-JWT for stateless, RESTful authentication. It utilizes Redis (Jedis) to manage RefreshTokens, enabling session revocation and automatic token renewal to address the uncontrollable nature of standard JWTs. Features include AES-128 + Base64 password encryption, a custom JWTFilter for request interception, and Mybatis Generator for base code generation.

Tokens
1.1K
Snippets
1
Records
6
Agent score
22%

What's inside ShiroJwt

  1. Overview of ShiroJwt

    master

    ShiroJwt is a Spring Boot-based framework that implements a stateless authentication mechanism using Apache Shiro and Java-JWT. It provides a RESTful API architecture with integrated Redis (Jedis) for caching and token control.

    Key features include:

    • Stateless Authentication: Uses JWT (JSON Web Tokens) for user identity.
    • Token Control: Uses a RefreshToken stored in Redis to maintain control over JWTs (e.g., allowing for user logout/revocation).
    • Automatic Token Refresh: Automatically issues a new AccessToken via the Authorization header when the current one expires, provided the RefreshToken is still valid.
    • Secure Password Storage: Uses AES-128 + Base64 encryption combined with the account name to ensure unique ciphertexts even for identical passwords.
    • Redis Integration: Overwrites Shiro's default cache mechanism to use Redis for improved scalability.

  2. How RefreshTokens provide JWT control

    master

    While standard JWTs are stateless, ShiroJwt achieves 'controllability' by using Redis to store RefreshToken information:

    1. Storage: Upon login, an AccessToken is returned containing a timestamp and account name. Simultaneously, a RefreshToken is stored in Redis with the account name as the key and the login timestamp as the value.
    2. Validation: For a request to be authenticated, the AccessToken must be valid, the corresponding RefreshToken must exist in Redis, and the timestamp in the AccessToken must match the timestamp stored in Redis.
    3. Revocation: To force a user to log out or revoke their access, simply delete their RefreshToken from Redis. The existing AccessToken will no longer pass authentication because its timestamp will no longer match the (now missing) Redis entry.

  3. How the JWT Authentication Flow Works

    master

    The authentication mechanism follows these steps:

    1. Login: Send a POST request with the username and password to the user/login endpoint. On success, the server returns an encrypted AccessToken.
    2. Subsequent Requests: Include the AccessToken in the Authorization field of the HTTP request header for all protected resource access.
    3. Filter Logic: The JWTFilter (extending BasicHttpAuthenticationFilter) intercepts requests to check for the Authorization header. If present, it performs Shiro token authentication; if absent, the user is treated as a guest (and may be blocked by permission controls).
    4. Token Expiration & Refresh:
      • AccessToken expiration is configurable (default: 5 minutes).
      • RefreshToken expiration is configurable (default: 30 minutes).
      • When an AccessToken expires, the server throws a TokenExpiredException.
      • If the RefreshToken exists in Redis and its timestamp matches the expired AccessToken, the server generates a new AccessToken and RefreshToken and returns the new AccessToken in the Authorization header of the response.

  4. Install and Setup ShiroJwt

    master

    To set up a local instance of ShiroJwt, follow these steps:

    1. Database Setup:
      • The default database credentials are root (check application.yml for modifications).
      • Execute the SQL script located at src/main/resources/sql/MySQL.sql to create the necessary database and tables.
    2. Redis Setup:
      • Install and run a Redis service. The default port and password settings are used by the application.
    3. Application Startup:
      • Run the Spring Boot application directly.
    4. Testing:
      • Use Postman to test the RESTful endpoints.

  5. Use Mybatis Generator to generate code

    master

    ShiroJwt uses Mybatis Generator for reverse engineering to quickly generate base code.

    1. Configure the src/main/resources/generator/generatorConfig.xml file.
    2. Run the generation command from the project root directory (where pom.xml is located) using Maven:
    mvn mybatis-generator:generate

  6. Test Authentication with Postman

    master

    To test the token lifecycle using Postman:

    1. Obtain Token:

      • Set Content-Type to application/json.
      • Send a POST request to the login endpoint with the username and password in the JSON body.
      • Locate the AccessToken in the Authorization field of the response Headers.

    2. Access Protected Resources:

      • Copy the token value.
      • For subsequent requests, add a header named Authorization and paste the token as the value.

    3. Handle Token Refresh:

      • When the token expires, the server will return a new token in the Authorization header of the response. The client must capture this new token and use it for all future requests.