1. Pac4j

Pac4j security engine for Jooby.

1.1. Usage

1) Add the dependency:

Maven
Gradle
<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-pac4j</artifactId>
  <version>3.5.5</version>
</dependency>

2) Install Pac4j

Simple login form
Java
Kotlin
import io.jooby.pac4j.Pac4jModule;

{
  install(new Pac4jModule());           (1)

  get("/", ctx -> {
    UserProfile user = ctx.getUser();   (2)
    return "Hello " + user.getId();
  });
}
1 Install Pac4j with a simple login form
2 Access to authenticated user

Once installed all routes defined below requires authentication.

1.2. Clients

A Client represents an authentication mechanism. It performs the login process and returns (if successful) a user profile. Clients are configured at bootstrap time using the Pac4j DSL:

1.2.1. Google

This example shows how to use Google.

1) Add the dependency:

Maven
Gradle
<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-oidc</artifactId>
  <version>6.1.0</version>
</dependency>

2) Generates clientId and secret keys or use the one provided by pac4j (development only):

application.conf
oidc.clientId = 167480702619-8e1lo80dnu8bpk3k0lvvj27noin97vu9.apps.googleusercontent.com
oidc.secret = MhMme_Ik6IH2JMnAT6MFIfee

2) Configure client

Google
Java
Kotlin
import io.jooby.pac4j.Pac4jModule;

{
  install(new Pac4jModule()
    .client(conf -> {
      OidcConfiguration oidc = new OidcConfiguration();
      oidc.setClientId(conf.getString("oidc.clientId"));
      oidc.setSecret(conf.getString("oidc.secret"));
      oidc.addCustomParam("prompt", "consent");
      oidc.setUseNonce(true);
      return new GoogleOidcClient(oidc);
    })
  );

  get("/", ctx -> {
    UserProfile user = ctx.getUser();
    return "Hello " + user.getId();
  });
}

1.2.2. Twitter

This example shows how to use Twitter.

1) Add the dependency:

Maven
Gradle
<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-oauth</artifactId>
  <version>6.1.0</version>
</dependency>

2) Generates key and secret tokens or use the one provided by pac4j (development only):

application.conf
twitter.key = CoxUiYwQOSFDReZYdjigBA
twitter.secret = 2kAzunH5Btc4gRSaMr7D7MkyoJ5u1VzbOOzE8rBofs

2) Configure client

Twitter
Java
Kotlin
import io.jooby.pac4j.Pac4jModule;

{
  install(new Pac4jModule()
    .client(conf -> {
      return new TwitterClient(conf.getString("twitter.key"), conf.getString("twitter.secret"));
    })
  );

  get("/", ctx -> {
    UserProfile user = ctx.getUser();
    return "Hello " + user.getId();
  });
}

1.2.3. JWT

This example shows how to use JSON WEB TOKEN.

1) Add the dependency:

Maven
Gradle
<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-jwt</artifactId>
  <version>6.1.0</version>
</dependency>

2) Generates key and secret tokens or use the one provided by pac4j (development only):

application.conf
jwt.salt = CoxUiYwQOSFDReZYdjigBA

2) Configure client

JWT
Java
Kotlin
import io.jooby.pac4j.Pac4jModule;

{
  install(new Pac4jModule()
    .client(conf -> {
      ParameterClient client = new ParameterClient("token",
          new JwtAuthenticator(new SecretSignatureConfiguration(conf.getString("jwt.salt"))));
      client.setSupportGetRequest(true);
      client.setSupportPostRequest(true);
      return client;
    })
  );

  get("/", ctx -> {
    UserProfile user = ctx.getUser();
    return "Hello " + user.getId();
  });
}

1.3. Protecting URLs

By default Pac4j restrict access to all the routes defined after the Pac4j module. You can specify what url must be protected using a path pattern:

Java
Kotlin
import io.jooby.pac4j.Pac4jModule;

{
  install(new Pac4jModule()
    .client("/admin/*", conf -> {
      return ...;
    })
  );
}

All routes under /admin will be protected by Pac4j.

1.4. Authorizer

Authorizers are registered and group by path. We do provide couple of ways to specific an authorizer:

Manual configuration
import org.pac4j.core.config.Config;
{

  Config pac4j = new Config();

  pac4j.addAuthorizer("test", new Authorizer<CommonProfile>() {
	@Override public boolean isAuthorized(WebContext context, List<CommonProfile> profiles) {
		return false;
	}
  });

  install(
      new Pac4jModule(pac4j)
          .client("/api/*", "test", conf -> {...});
  );
}
Automatic configuration
{

  install(
      new Pac4jModule()
          .client("/api/*", new MyTestAuthorizer(), conf -> {...});
  );
}
Registry (or dependency injection) integration
{

  install(
      new Pac4jModule()
          .client("/api/*", MyTestAuthorizer.class, conf -> {...});
  );
}

This last example ask application registry (dependency injection framework usually) to provisioning the MyTestAuthorizer authorizer.

1.5. Advanced Usage

You can customize default options by using the Pac4jOptions and/or providing your own Pac4j configuration.

Java
Kotlin
import io.jooby.pac4j.Pac4jModule;
import org.pac4j.core.config.Config;

{
  Config pac4j = new Config();
  pac4j.setSecurityLogic(...);

  install(new Pac4jModule(pac4j));
}

1.6. Starter

Checkout the starter/demo project for Pac4j that let you choose between multiple login clients: Pac4j Starter.