shiro-oauth2-extension

English | 简体中文

OAuth 1.0a / OAuth 2.0 authentication extension for Apache Shiro, built on ScribeJava 8.3.3. It provides OAuth tokens, form/user filters, abstract realms and a UserProfile model for third-party login scenarios.

Table of Contents

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage / API
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

1. Project Overview

What it is

shiro-oauth2-extension integrates OAuth-based third-party login into Shiro:

• OAuth 1.0a: OAuthToken (host + OAuth1AccessToken), OAuthFormAuthenticationFilter / OAuthUserFilter, AbstractOAuthRealm (implement getUserProfile(OAuth1AccessToken)).
• OAuth 2.0: OAuth2Token (host + OAuth2AccessToken), OAuth2FormAuthenticationFilter / OAuth2UserFilter, AbstractOAuth2Realm (implement getUserProfile(OAuth2AccessToken)).
• UserProfile — a serializable profile model (id, attributes, authentication attributes) returned by realms and used to build the Shiro principal.

What it is not

• It is not an OAuth provider implementation — the protocol work is delegated to ScribeJava (OAuth1AccessToken, OAuth2AccessToken).
• It is not a Spring Boot starter; no auto-configuration is shipped.

Typical scenarios

Scenario	Description
OAuth 2.0 third-party login	Extend AbstractOAuth2Realm, return a UserProfile built from the provider's user info endpoint.
OAuth 1.0a login (legacy providers)	Extend AbstractOAuthRealm for OAuth 1.0a providers.
Web filter integration	OAuth2FormAuthenticationFilter / OAuth2UserFilter behave like Shiro's form/user filters but with OAuth login URLs.

2. Features & Status

Capability	Status	Notes
OAuth 1.0a support	Available	OAuthToken, AbstractOAuthRealm, OAuthFormAuthenticationFilter, OAuthUserFilter, OAuthAuthenticationException.
OAuth 2.0 support	Available	OAuth2Token, AbstractOAuth2Realm, OAuth2FormAuthenticationFilter, OAuth2UserFilter, OAuth2AuthenticationException.
User profile model	Available	UserProfile (Serializable/Externalizable): id, attributes, authentication attributes.
Default roles / permissions	Available	setDefaultRoles(String) / setDefaultPermissions(String) on both abstract realms.

Status is reported as of 2.0.x.x.20260630-SNAPSHOT on the feature/2.0.x branch.

3. Requirements & Compatibility

Item	Version
JDK	17+
Maven	3.0+ (Maven Wrapper 3.5.0 bundled)
Apache Shiro	1.13.0 (shiro-web)
ScribeJava	8.3.3 (scribejava-core)
Servlet	javax.servlet-api 4.0.1

Version lines

Branch	JDK baseline	Version pattern
feature/1.0.x	JDK 8	1.0.x.*
feature/2.0.x	JDK 17	2.0.x.*
feature/3.0.x	JDK 21	3.0.x.*

4. Architecture & Modules

 Client (OAuth 1.0a / OAuth 2.0 login redirect)
        |
        v
 OAuth(2)FormAuthenticationFilter / OAuth(2)UserFilter
        |
        v
 OAuthToken / OAuth2Token (host + ScribeJava access token)
        |
        v
 AbstractOAuthRealm / AbstractOAuth2Realm
        |  getUserProfile(OAuth1AccessToken / OAuth2AccessToken)
        |  defaultRoles / defaultPermissions
        v
 UserProfile (id + attributes) --> Shiro principal

This is a single-module project (packaging jar), classes under org.apache.shiro.spring.boot.oauth1 and org.apache.shiro.spring.boot.oauth2:

Package	Role
oauth1 (authc, realm, token, exception)	OAuth 1.0a filters, realm, token and exception
oauth2 (authc, realm, token, exception)	OAuth 2.0 filters, realm, token and exception; UserProfile model

5. Installation

The artifact is not yet published to Maven Central. Resolve it from the project's configured artifact repository (Aliyun Packages) or install it locally from source; the snapshot version currently used on the feature/2.0.x branch is 2.0.x.x.20260630-SNAPSHOT.

Maven

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>shiro-oauth2-extension</artifactId>
    <version>2.0.x.x.20260630-SNAPSHOT</version>
</dependency>

Gradle

implementation 'io.github.easy4j:shiro-oauth2-extension:2.0.x.x.20260630-SNAPSHOT'

6. Quick Start

OAuth 2.0 realm with a UserProfile:

import com.github.scribejava.core.model.OAuth2AccessToken;
import org.apache.shiro.spring.boot.oauth2.UserProfile;
import org.apache.shiro.spring.boot.oauth2.realm.AbstractOAuth2Realm;

AbstractOAuth2Realm realm = new AbstractOAuth2Realm() {
    @Override
    public UserProfile getUserProfile(OAuth2AccessToken credential) {
        // fetch the provider's user info with the access token
        UserProfile profile = new UserProfile() {};
        profile.build("user-10001", userInfoAttributes);
        profile.addAttribute("avatar", "https://.../avatar.png");
        return profile;
    }
};
realm.setDefaultRoles("user");
realm.setDefaultPermissions("read:profile");

Expected result: when a OAuth2Token (host + OAuth2AccessToken) is submitted for login, the realm calls getUserProfile(...); the returned UserProfile's id/attributes back the Shiro principal, and the configured default roles/permissions are applied.

7. Configuration

This library has no configuration properties or prefix. The abstract realms expose setDefaultRoles(String) and setDefaultPermissions(String) (comma/space-separated values) plus the standard Shiro realm setters (credentials matcher, cache manager, ...).

8. Core Usage / API

Class	Package	Role
AbstractOAuth2Realm	org.apache.shiro.spring.boot.oauth2.realm	Extend and implement getUserProfile(OAuth2AccessToken).
AbstractOAuthRealm	org.apache.shiro.spring.boot.oauth1.realm	Extend and implement getUserProfile(OAuth1AccessToken).
OAuth2Token / OAuthToken	...oauth2.token / ...oauth1.token	HostAuthenticationToken holding the host and the ScribeJava access token.
UserProfile	org.apache.shiro.spring.boot.oauth2	Serializable/Externalizable profile model: build(id, attributes[, authAttributes]), addAttribute(key, value), getId(), getTypedId(), getAttributes().
OAuth2FormAuthenticationFilter / OAuth2UserFilter	...oauth2.authc	Form-style and user-style Shiro filters with OAuth login URLs.
OAuth2AuthenticationException / OAuthAuthenticationException	...oauth2.exception / ...oauth1.exception	OAuth authentication exceptions.

9. Testing & Build

# Full build with JaCoCo coverage report/check
./mvnw clean verify

# Install into the local repository
./mvnw install

Test & gate facts (as configured in the pom):

• No unit tests exist in this module yet.
• JaCoCo is bound to prepare-agent / report / check; the check rule requires a 90% line coverage ratio (configured with haltOnFailure=false).

10. Versioning & Branches

Branch	JDK baseline	Version pattern	Status
feature/1.0.x	JDK 8	1.0.x.*	Active; current snapshot 1.0.x.20260630-SNAPSHOT
feature/2.0.x	JDK 17	2.0.x.*	Maintained
feature/3.0.x	JDK 21	3.0.x.*	Maintained

Maintenance strategy: the 1.0.x line keeps JDK 8 compatibility for legacy deployments; the 2.0.x and 3.0.x lines are the modern JDK baselines. Release artifacts are published to the project's configured artifact repository (Aliyun Packages) and GitHub Releases; the project has not yet published to Maven Central.

11. Contributing & License

Contributions are welcome — please open an issue or a pull request on the GitHub repository.

This project is licensed under the Apache License 2.0. See LICENSE for details.