Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Multi protocols (OAuth, OpenID, CAS, SAML, HTTP, GAE) security library for Shiro
Java

README.md

What is the buji-pac4j library ? Build Status

The buji-pac4j library is a web multi-protocols client for Apache Shiro.

It supports these 7 authentication mechanisms on client side:

  1. OAuth (1.0 & 2.0)
  2. CAS (1.0, 2.0, SAML, logout & proxy)
  3. HTTP (form & basic auth authentications)
  4. OpenID
  5. SAML (2.0)
  6. GAE UserService
  7. OpenID Connect (1.0).

It's available under the Apache 2 license and based on my pac4j library.

Libraries

As of 1.3.0, this project exports two libraries: buji-pac4j-core and buji-pac4j-servlet. Both are intended to be used in web-based environments. buji-pac4j-servlet is to be used in servlet environments and depends on buji-pac4j-core. It is the library to be used for most Java web projects (e.g. anything running on Tomcat, Glassfish, Jetty, etc.) buji-pac4j-core is a library without any servlet dependencies and thus is meant to be used with some newer Java web frameworks which do not support servlets such as Play Framework or Vert.x.

In versions previous to 1.3.0, there was a single library buji-pac4j, which was the combination of buji-pac4j-core and buji-pac4j-servlet.

Providers supported

Provider Protocol Maven dependency Client class Profile class
CAS server CAS pac4j-cas CasClient & CasProxyReceptor CasProfile
CAS server using OAuth Wrapper OAuth 2.0 pac4j-oauth CasOAuthWrapperClient CasOAuthWrapperProfile
DropBox OAuth 1.0 pac4j-oauth DropBoxClient DropBoxProfile
Facebook OAuth 2.0 pac4j-oauth FacebookClient FacebookProfile
GitHub OAuth 2.0 pac4j-oauth GitHubClient GitHubProfile
Google OAuth 2.0 pac4j-oauth Google2Client Google2Profile
LinkedIn OAuth 1.0 & 2.0 pac4j-oauth LinkedInClient & LinkedIn2Client LinkedInProfile & LinkedIn2Profile
Twitter OAuth 1.0 pac4j-oauth TwitterClient TwitterProfile
Windows Live OAuth 2.0 pac4j-oauth WindowsLiveClient WindowsLiveProfile
WordPress OAuth 2.0 pac4j-oauth WordPressClient WordPressProfile
Yahoo OAuth 1.0 pac4j-oauth YahooClient YahooProfile
PayPal OAuth 2.0 pac4j-oauth PayPalClient PayPalProfile
Vk OAuth 2.0 pac4j-oauth VkClient VkProfile
Foursquare OAuth 2.0 pac4j-oauth FoursquareClient FoursquareProfile
Bitbucket OAuth 1.0 pac4j-oauth BitbucketClient BitbucketProfile
ORCiD OAuth 2.0 pac4j-oauth OrcidClient OrcidProfile
Strava OAuth 2.0 pac4j-oauth StravaClient StravaProfile
Web sites with basic auth authentication HTTP pac4j-http BasicAuthClient HttpProfile
Web sites with form authentication HTTP pac4j-http FormClient HttpProfile
Yahoo OpenID pac4j-openid YahooOpenIdClient YahooOpenIdProfile
SAML Identity Provider SAML 2.0 pac4j-saml Saml2Client Saml2Profile
Google App Engine User Service Gae User Service Mechanism pac4j-gae GaeUserServiceClient GaeUserServiceProfile
OpenID Identity Provider OpenID Connect 1.0 pac4j-oidc OidcClient OidcProfile

Technical description

This library has just 9 classes:

  1. the ClientFilter class is called after the authentication at the provider: it creates the ClientToken to be used by the ClientRealm
  2. the ClientToken class is the token representing the credentials and the profile of the user
  3. the ClientRealm class is the realm responsible for authenticating a ClientToken: it finishes the authentication process by retrieving the profile of the authenticated user and computing its default roles and permissions
  4. the ClientSubjectFactory class is the factory responsible for creating a Subject based on the authentication information (isRemembered...).
  5. the ShiroWebContext class is a Shiro wrapper for the user request, response and session
  6. the ClientPermissionsAuthorizationFilter class is a filter to protect the application if the user has not the right permissions
  7. the ClientRolesAuthorizationFilter class is a filter to protect the application if the user has not the right roles
  8. the ClientUserFilter class is a filter to protect the application if the user is not authenticated
  9. the NoAuthenticationException class is an exception when no user profile is returned.

and is based on the pac4j-* libraries.

Learn more by browsing the buji-pac4j Javadoc and the pac4j Javadoc.

How to use it ?

Add the required dependencies

If you want to use a specific client support, you need to add the appropriate Maven dependency in the pom.xml file:

  1. for OAuth support, the pac4j-oauth dependency is required
  2. for CAS support, the pac4j-cas dependency is required
  3. for HTTP support, the pac4j-http dependency is required
  4. for OpenID support, the pac4j-openid dependency is required
  5. for SAML support, the pac4j-saml dependency is required
  6. for Google App Engine support, the pac4j-gae dependency is required
  7. for OpenID Connect support, the pac4j-oidc dependency is required.

For example, to add OAuth support, add the following XML snippet:

<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-oauth</artifactId>
  <version>1.7.0</version>
</dependency>

As these snapshot dependencies are only available in the Sonatype snapshots repository, the appropriate repository may need be added in the pom.xml file also:

<repositories>
  <repository>
    <id>sonatype-nexus-snapshots</id>
    <name>Sonatype Nexus Snapshots</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Define the clients

If you want to authenticate at an OAuth or OpenID provider, at a CAS server or through HTTP, you have to define all the clients in the shiro.ini file:

[main]
facebookClient = org.pac4j.oauth.client.FacebookClient
facebookClient.key = fbkey
facebookClient.secret = fbsecret

twitterClient = org.pac4j.oauth.client.TwitterClient
twitterClient.key = twkey
twitterClient.secret = twsecret

simpleAuthenticator = org.pac4j.http.credentials.SimpleTestUsernamePasswordAuthenticator
formClient = org.pac4j.http.client.FormClient
formClient.loginUrl = http://localhost:8080/theForm.jsp
formClient.usernamePasswordAuthenticator = $simpleAuthenticator

basicAuthClient = org.pac4j.http.client.BasicAuthClient
basicAuthClient.usernamePasswordAuthenticator = $simpleAuthenticator

# the CAS server is started on localhost:8888/cas
casClient = org.pac4j.cas.client.CasClient
casClient.casLoginUrl = http://localhost:8888/cas/login

# application is started on localhost:8080
clients = org.pac4j.core.client.Clients
clients.callbackUrl = http://localhost:8080/callback
clients.clientsList = $facebookClient,$twitterClient,$formClient,$basicAuthClient,$casClient

Customize the SecurityManager

To have a correct subject populated, you need to define the subject factory:

[main]
subjectFactory = io.buji.pac4j.ClientSubjectFactory
securityManager.subjectFactory = $subjectFactory

Define the filter and realm

To handle callback from providers, you need to define the appropriate filter:

[main]
clientsFilter = io.buji.pac4j.ClientFilter
clientsFilter.clients = $clients
clientsFilter.failureUrl = /error500.jsp

[urls]
/callback = clientsFilter

To finish the authentication process after being callbacked by the provider, a specific realm must be declared:

[main]
clientsRealm = io.buji.pac4j.ClientRealm
clientsRealm.defaultRoles = ROLE_USER
clientsRealm.clients = $clients</code></pre>

Protect the urls

You can protect your urls and force the user to be authenticated by a client by using one of the following filter: ClientPermissionsAuthorizationFilter, ClientRolesAuthorizationFilter or ClientUserFilter. For example:

[main]
facebookRoles = io.buji.pac4j.filter.ClientRolesAuthorizationFilter
facebookRoles.client = $facebookClient
formRoles = io.buji.pac4j.filter.ClientRolesAuthorizationFilter
formRoles.client = $formClient
casRoles = io.buji.pac4j.filter.ClientRolesAuthorizationFilter
casRoles.client = $casClient

[urls] 
/facebook/** = facebookRoles[ROLE_USER]
/form/** = formRoles[ROLE_USER]
/cas/** = casRoles[ROLE_USER]
/callback = clientsFilter
/logout = logout
/** = anon

Get redirection urls

You can also explicitely compute a redirection url to a provider for authentication by using the getRedirectionUrl method. For example:

<%
ShiroWebContext context = new ShiroWebContext(request, response);
%>
<a href="<%=facebookClient.getRedirectionUrl(context,false,false)%>">Authenticate with Facebook</a>

Use the appropriate profile

After successful authentication, the first principal is the typedId (a unique id accross providers and users) and the second principal is the user profile:

String typedId = (String) SecurityUtils.getSubject().getPrincipal();
// common profile to all providers
CommonProfile commonProfile = (CommonProfile) SecurityUtils.getSubject().getPrincipals().asList().get(1);

From the CommonProfile, you can retrieve the most common properties that all profiles share. But you can also cast the user profile to the appropriate profile according to the provider used for authentication. For example, after a Facebook authentication:

// facebook profile
FacebookProfile facebookProfile = (FacebookProfile) commonProfile;

Or for all the OAuth profiles, to get the access token:

OAuthProfile oauthProfile = (OAuthProfile) commonProfile
String accessToken = oauthProfile.getAccessToken();
// or
String accessToken = facebookProfile.getAccessToken();

Demo

A demo with Facebook, Twitter, CAS, form authentication and basic auth authentication providers is available with buji-pac4j-demo.

Versions

The current version 1.3.2-SNAPSHOT is under development. It's available on the Sonatype snapshots repository as a Maven dependency:

The last released version is the 1.3.1:

<dependency>
    <groupId>io.buji</groupId>
    <artifactId>buji-pac4j-servlet</artifactId>
    <version>1.3.1</version>
</dependency>

See the release notes.

Contact

For any question or problem, don't hesitate to post it on the Shiro user mailing list or on the Shiro developer mailing list.

Or please use the dedicated mailing lists:

Something went wrong with that request. Please try again.