DEV Community: Jérôme LELEU

OpenID Federation with pac4j and CAS

Jérôme LELEU — Tue, 13 Oct 2026 11:21:57 +0000

We have made a long journey with pac4j and the OpenID federation protocol in this series of 3 articles:

2 articles on the Connect2id server acting as a federated OP: (Part 1) + (Part 2)
1 article on the Connect2id server being the OP and the CAS server being the trust anchor: pac4j + Connect2id + CAS.

As CAS v8.1.0 will also support the OpenID federation protocol as a server (OP), it is time to conclude this series with this fourth and final article, using pac4j and CAS only.

Like in our previous setup, we have 3 components:

a client, which is called the Relying Party (RP) in OIDC, and we use pac4j
a server, which is called the OpenID Provider (OP) in OIDC, and we use the CAS server
a trust anchor (TA for short) and we use the CAS server.

Although we use the CAS server for the OP and the TA, we can't use a single CAS node: we have two separate nodes of the CAS server, each supporting an exclusive role.

To be consistent with our previous installation:

the OP runs on http://localhost:8080/cas
the RP runs on http://localhost:8081
the TA runs on http://localhost:8082/cas.

For the CAS server nodes, we use this basic Maven overlay: https://github.com/casinthecloud/cas-overlay-demo.

Both our CAS servers have a similar pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.casinthecloud</groupId>
    <artifactId>cas-overlay-demo</artifactId>
    <version>8.1.0-SNAPSHOT</version>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-webapp${tomcat.properties}</artifactId>
            <version>${cas.version}</version>
            <type>war</type>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-oidc-federation</artifactId>
            <version>${cas.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                    <recompressZippedFiles>false</recompressZippedFiles>
                    <archive>
                        <compress>false</compress>
                        <manifestFile>${project.build.directory}/war/work/org.apereo.cas/cas-server-webapp${tomcat.properties}/META-INF/MANIFEST.MF</manifestFile>
                    </archive>
                    <overlays>
                        <overlay>
                            <groupId>org.apereo.cas</groupId>
                            <artifactId>cas-server-webapp${tomcat.properties}</artifactId>
                        </overlay>
                    </overlays>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <release>${java.version}</release>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>4.2.0-M1</version>
                <configuration>
                    <mainClass>org.apereo.cas.web.CasWebApplication</mainClass>
                    <excludes>
                        <exclude>
                            <groupId>org.apereo.cas</groupId>
                            <artifactId>cas-server-webapp-tomcat</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <finalName>cas</finalName>
    </build>

    <properties>
        <cas.version>8.1.0-RC1</cas.version>
        <java.version>25</java.version>
        <tomcat.properties>-tomcat</tomcat.properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

</project>

The OP has one more CAS dependency though (compared to the TA):

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-oidc</artifactId>
    <version>${cas.version}</version>
</dependency>

And the configuration specific to each server changes.

For the pac4j application, we use this simple demo: https://github.com/pac4j/simple-spring-boot-pac4j-demos/tree/oidc/src/main/java/org/pac4j/demos.

1) Setup a CAS server as the OP

In the application.yml file, let's set up the CAS server to act as the trust anchor:

server.ssl.enabled: false
server.port: 8080

cas.tgc.secure: false
cas.tgc.same-site-policy: Lax

cas.tgc.crypto.enabled: false
cas.webflow.crypto.enabled: false

cas.server.name: http://localhost:${server.port}
cas.server.prefix: ${cas.server.name}/cas
cas.host.name: casop

cas.authn.oidc.jwks.file-system.jwks-file: file:./metadata/oidc.jwks
cas.authn.oidc.federation.role: OPENID_PROVIDER
cas.authn.oidc.federation.jwks-file: file:./metadata/federation.jwks
cas.authn.oidc.federation.authority-hints:
  - http://localhost:8082/cas/oidc
cas.authn.oidc.core.issuer: ${cas.server.prefix}/oidc

The configuration is quite easy: we set up the CAS server to run on http://localhost:8080/cas (no SSL, Lax policy, no cookie/webflow encryption, this is for development only).

For OIDC, we define its OIDC base URL (issuer) and its JWKS (./metadata/oidc.jwks).

And for the federation part, we set the OPENID_PROVIDER role, the specific JWKS (./metadata/federation.jwks) and the trust anchor:

cas.authn.oidc.federation.authority-hints:
  - http://localhost:8082/cas/oidc

2) Setup the pac4j application as the RP

In the pac4j ecosystem, Spring Boot is the most popular web stack, so we use the spring-webmvc-pac4j implementation in this simple demo: https://github.com/pac4j/simple-spring-boot-pac4j-demos/tree/oidc/src/main/java/org/pac4j/demos:

the SpringBootDemo class runs the Spring Boot demo
the SecurityConfig class defines the security configuration (OIDC + URL protection)
the Application class is a simple controller with two URLs: one public and the other one protected.

a) Dependencies

We need the following dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-webmvc-pac4j</artifactId>
    <version>8.0.3</version>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.6</version>
</dependency>

b) Properties

We run it on port 8081 thanks to the application.properties file:

server.port=8081
app.base-url=http://localhost:8081

c) `SecurityConfig` class

We update the SecurityConfig class to change the configuration for the federation:

package org.pac4j.demos;

import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.oauth2.sdk.auth.ClientAuthenticationMethod;
import org.pac4j.core.config.Config;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;
import org.pac4j.oidc.config.method.PrivateKeyJwtClientAuthnMethodConfig;
import org.pac4j.oidc.federation.config.OidcTrustAnchorProperties;
import org.pac4j.springframework.config.Pac4jSecurityConfig;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;

import java.util.List;

@Configuration
public class SecurityConfig extends Pac4jSecurityConfig {

    @Value("${app.base-url:http://localhost:8080}")
    private String baseUri;

    @Bean
    public Config config() {
        final var config = new OidcConfiguration();
        config.setAllowUnsignedIdTokens(true);

        final var rpJwks = config.getRpJwks();
        rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
        rpJwks.setKid("defaultjwks26");
        config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
        final var privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(rpJwks);
        config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);

        config.setRequestObjectSigningAlgorithm(JWSAlgorithm.RS256);

        final var federation = config.getFederation();

        federation.setTargetOp("http://localhost:8080/cas/oidc");
        final var trust = new OidcTrustAnchorProperties();
        trust.setIssuer("http://localhost:8082/cas/oidc");
        trust.setJwksPath("classpath:trustanchor.jwks");
        federation.getTrustAnchors().add(trust);

        federation.getJwks().setJwksPath("file:./metadata/oidcfede.jwks");
        federation.getJwks().setKid("mykeyoidcfede26");
        federation.setContactName("RP with CAS");
        federation.setContactEmails(List.of("jerome@casinthecloud.com"));

        federation.setEntityId("http://localhost:8081");

        return new Config(baseUri + "/callback", new OidcClient(config));
    }

    @Override
    public void addInterceptors(final InterceptorRegistry registry) {
        addSecurity(registry, "OidcClient").addPathPatterns("/protected/**");
    }
}

The configuration is more complicated here.

We define a global JWKS for the RP that is also used for the private_key_jwt authentication method:

    final var rpJwks = config.getRpJwks();
    rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
    rpJwks.setKid("defaultjwks26");
    config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
    final var privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(rpJwks);
    config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);

For federation, we use:

    config.setRequestObjectSigningAlgorithm(JWSAlgorithm.RS256);

    final var federation = config.getFederation();

    federation.setTargetOp("http://localhost:8080/cas/oidc");
    final var trust = new OidcTrustAnchorProperties();
    trust.setIssuer("http://localhost:8082/cas/oidc");
    trust.setJwksPath("classpath:trustanchor.jwks");
    federation.getTrustAnchors().add(trust);

The target OP is of course the CAS server acting as an OP.

For the trust anchor, it's the other CAS node (on port 8082) for which we retrieve the JWKS from http://localhost:8082/cas/oidc/.well-known/openid-federation and save it in the trustanchor.jwks file.

Example:

{
    "keys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "19f7aaaa-c4d3-4c26-a26e-3ce4b8ab1beb",
            "n": "uXgnb...SEdSw"
        }
    ]
}

We also have a specific JWKS configuration dedicated to federation (displayed on the .well-known/openid-federation endpoint):

    federation.getJwks().setJwksPath("file:./metadata/oidcfede.jwks");
    federation.getJwks().setKid("mykeyoidcfede26");
    federation.setContactName("RP with CAS");
    federation.setContactEmails(List.of("jerome@casinthecloud.com"));

    federation.setEntityId("http://localhost:8081");

d) `Application` class

We also need to update the Application class to add the mapping for the OpenID federation endpoint:

@Controller
public class Application {

    @Autowired
    private Config config;

    @RequestMapping(value = "/.well-known/openid-federation", produces = DefaultEntityConfigurationGenerator.CONTENT_TYPE)
    @ResponseBody
    public String oidcFederation() throws HttpAction {
        final var oidcClient = (OidcClient) config.getClients().findClient("OidcClient").get();
        return oidcClient.getConfiguration().getFederation().getEntityConfigurationGenerator().generateEntityStatement();
    }

    ...
}

3) Setup a CAS server as the trust anchor

In the application.yml file, let's set up the CAS server as the trust anchor this time:

server.ssl.enabled: false
server.port: 8082

cas.tgc.secure: false
cas.tgc.same-site-policy: Lax

cas.tgc.crypto.enabled: false
cas.webflow.crypto.enabled: false

cas.server.name: http://localhost:${server.port}
cas.server.prefix: ${cas.server.name}/cas
cas.host.name: casta

cas.authn.oidc.federation.role: TRUST_ANCHOR
cas.authn.oidc.federation.jwks-file: file:./metadata/trustanchor.jwks
cas.authn.oidc.core.issuer: ${cas.server.prefix}/oidc
cas.authn.oidc.federation.subordinate-directory: ./subordinates

The configuration is close to that of the other CAS node, except that we define the TRUST_ANCHOR role as well as the file directory in which we will define its subordinates.

The subordinates are the entities for which the CAS server provides trust. They must be defined upfront with their metadata and their federation key(s).

Here, it will be the RP (the pac4j client, Spring Boot demo) and the OP (the other CAS server).

For the RP (pac4j), we call the URL: http://localhost:8081/.well-known/openid-federation. An entity statement is returned by the Spring Boot demo and we can decode it via any JWT tool or the jwt.io website.

The metadata and the keys from the jwks property (not in the metadata property) are the ones we use to build the subordinate rp.json file (placed in the ./subordinates directory):

{
    "entityId": "http://localhost:8081",
    "metadata": {
        "openid_relying_party": {
            "redirect_uris": [
                "http://localhost:8081/callback?client_name=OidcClient"
            ],
            "application_type": "web",
            "response_types": [
                "code"
            ],
            "grant_types": [
                "authorization_code"
            ],
            "scope": "openid email profile",
            "token_endpoint_auth_method": "private_key_jwt",
            "token_endpoint_auth_signing_alg": "RS256",
            "request_object_signing_alg": "RS256",
            "jwks": {
                "keys": [
                    {
                        "kty": "RSA",
                        "e": "AQAB",
                        "use": "sig",
                        "kid": "defaultjwks26",
                        "n": "v-zf7...G2tyw"
                    }
                ]
            },
            "client_registration_types": [
                "explicit",
                "automatic"
            ],
            "client_name": "RP with CAS",
            "contacts": [
                "jerome@casinthecloud.com"
            ]
        }
    },
    "federationKeys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "mykeyoidcfede26",
            "n": "uaov...EpbZQ"
        }
    ]
}

For the OP (CAS server), we do something similar and call the URL: http://localhost:8080/cas/oidc/.well-known/openid-federation to get the metadata and the federation keys and create the op.json file (in the ./subordinates directory).

{
    "entityId": "http://localhost:8080/cas/oidc",
    "metadata": {
        "openid_provider": {
            "DPopSigningAlgValuesSupported": [
                "RS256",
                "RS384",
                "RS512",
                "ES256",
                "ES384",
                "ES512"
            ],
            "request_parameter_supported": true,
            "pushed_authorization_request_endpoint": "http://localhost:8080/cas/oidc/oidcPushAuthorize",
            "introspection_signing_alg_values_supported": [
                "none",
                "RS256",
                "RS384",
                "RS512",
                "PS256",
                "PS384",
                "PS512",
                "ES256",
                "ES384",
                "ES512",
                "HS256",
                "HS384",
                "HS512"
            ],

            ...[TRUNCATED]...

            "registration_endpoint": "http://localhost:8080/cas/oidc/register",
            "request_object_signing_alg_values_supported": [
                "none",
                "RS256",
                "RS384",
                "RS512",
                "PS256",
                "PS384",
                "PS512",
                "ES256",
                "ES384",
                "ES512",
                "HS256",
                "HS384",
                "HS512"
            ],
            "request_object_encryption_alg_values_supported": [
                "RSA1_5",
                "RSA-OAEP",
                "RSA-OAEP-256",
                "A128KW",
                "A192KW",
                "A256KW",
                "A128GCMKW",
                "A192GCMKW",
                "A256GCMKW",
                "ECDH-ES",
                "ECDH-ES+A128KW",
                "ECDH-ES+A192KW",
                "ECDH-ES+A256KW"
            ]
        },
        "federation_entity": {
            "organization_name": "Apereo CAS",
            "contacts": []
        }
    },
    "federationKeys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "0bf6c36e-1cba-41d3-a50e-a11881fd85e7",
            "n": "xoP5Q...3EkRw"
        }
    ]
}

4) Final test

With the RP, OP and TA started, we call http://localhost:8081 in the browser:

Then, we click on the "Protected area" link.

On the CAS server login page, we use the pre-defined user: casuser / Mellon to log in:

and we validate the authorizations:

And it works:

We are finally logged in to the pac4j application thanks to the OpenID Federation protocol and the two CAS server nodes.

So the CAS server can now act as a federated OP and as a trust anchor with the pac4j RP client.

OpenID Federation with pac4j, Connect2id and CAS

Jérôme LELEU — Tue, 13 Oct 2026 11:20:51 +0000

In previous posts, we have presented the OpenID (Connect) Federation protocol with pac4j and the Connect2id server: (Part 1) + (Part 2).

From our previous setup, we have 3 components:

a client, which is called the Relying Party (RP) in OIDC, and we use pac4j
a server, which is called the OpenID Provider (OP) in OIDC, and we use the Connect2id server
a trust anchor (TA for short) and we use a simulated one.

As the pac4j library is a first-class citizen of the CAS server (it is used for authentication delegation, token authentication, the security of the OAuth/OIDC server support, etc.), let's bring the CAS server into action.

In this article, we will replace the simulated trust anchor by the CAS server.

1) Setup a CAS server as a trust anchor

The pac4j application runs on localhost:8081 and the Connect2id server is on 127.0.0.1:8080.

So let's choose localhost:8082 to run the CAS server as a trust anchor.

Let's start from this basic Maven overlay: https://github.com/casinthecloud/cas-overlay-demo.

For the version, it should be 8.0.0 (at least).

We can remove the useless cas-server-support-json-service-registry dependency and add the new cas-server-support-oidc-federation module dedicated to federation support.

To make things easier, let's turn the CAS server into a standalone (Tomcat embedded) JAR using the spring-boot-maven-plugin.

So we have the following pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.casinthecloud</groupId>
    <artifactId>cas-overlay-demo</artifactId>
    <version>8.0.0-SNAPSHOT</version>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-webapp${tomcat.properties}</artifactId>
            <version>${cas.version}</version>
            <type>war</type>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-oidc-federation</artifactId>
            <version>${cas.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                    <recompressZippedFiles>false</recompressZippedFiles>
                    <archive>
                        <compress>false</compress>
                        <manifestFile>${project.build.directory}/war/work/org.apereo.cas/cas-server-webapp${tomcat.properties}/META-INF/MANIFEST.MF</manifestFile>
                    </archive>
                    <overlays>
                        <overlay>
                            <groupId>org.apereo.cas</groupId>
                            <artifactId>cas-server-webapp${tomcat.properties}</artifactId>
                        </overlay>
                    </overlays>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <release>${java.version}</release>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>4.1.0</version>
                <configuration>
                    <mainClass>org.apereo.cas.web.CasWebApplication</mainClass>
                    <excludes>
                        <exclude>
                            <groupId>org.apereo.cas</groupId>
                            <artifactId>cas-server-webapp-tomcat</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <finalName>cas</finalName>
    </build>

    <properties>
        <cas.version>8.0.0</cas.version>
        <java.version>25</java.version>
        <tomcat.properties>-tomcat</tomcat.properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

</project>

In the application.yml file, let's set up the CAS server to act as a trust anchor:

server.ssl.enabled: false
server.port: 8082

cas.tgc.secure: false
cas.tgc.same-site-policy: Lax

cas.tgc.crypto.enabled: false
cas.webflow.crypto.enabled: false

cas.server.name: http://localhost:${server.port}
cas.server.prefix: ${cas.server.name}/cas
cas.host.name: castest

cas.authn.oidc.federation.role: TRUST_ANCHOR
cas.authn.oidc.core.issuer: ${cas.server.prefix}/oidc
cas.authn.oidc.federation.subordinate-directory: /etc/cas/config/subordinates

The configuration is quite easy: we set up the CAS server to run on localhost:8082 (no SSL, Lax policy, no cookie/webflow encryption, for development only).

And for the federation part, we define the TRUST_ANCHOR role, its OIDC base URL (issuer) as well as the file directory in which we will define its subordinates.

The subordinates are the entities for which the CAS server provides trust. They must be defined upfront with their metadata and their federation key(s).

Here, it will be the RP = pac4j client (Spring Boot demo) and the Connect2id server = OP.

2) Define its subordinates

To define the subordinates of the trust anchor, we need to retrieve the information from the current RP and OP.

{
  "sub": "http://localhost:8081",
  "metadata": {
    "openid_relying_party": {
      "redirect_uris": [
        "http://localhost:8081/callback?client_name=OidcClient"
      ],
      "application_type": "web",
      "response_types": [
        "code"
      ],
      "grant_types": [
        "authorization_code"
      ],
      "scope": "openid email profile",
      "token_endpoint_auth_method": "private_key_jwt",
      "token_endpoint_auth_signing_alg": "RS256",
      "request_object_signing_alg": "RS256",
      "jwks": {
        "keys": [
          {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "defaultjwks0526",
            "n": "2moVQ...2aq7Q"
          }
        ]
      },
      "client_registration_types": [
        "explicit",
        "automatic"
      ],
      "client_name": "New RP test",
      "contacts": [
        "jerome@casinthecloud.com"
      ]
    }
  },
  "nbf": 1777901081,
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "mykeyoidcfede26",
        "n": "nVoec...qELzQ"
      }
    ]
  },
  "iss": "http://localhost:8081",
  "authority_hints": [
    "http://localhost:8081/trustanchor"
  ],
  "exp": 1785677081,
  "iat": 1777901081,
  "jti": "59fad759-60e7-4cc9-a3fe-203e6d02319b"
}

The metadata and the keys from the jwks property (not in the metadata property) are the ones we use to build the subordinate rp.json file (placed in the /etc/cas/config/subordinates directory):

{
  "entityId": "http://localhost:8081",
  "metadata": {
    "openid_relying_party": {
      "redirect_uris": [
        "http://localhost:8081/callback?client_name=OidcClient"
      ],
      "application_type": "web",
      "response_types": [
        "code"
      ],
      "grant_types": [
        "authorization_code"
      ],
      "scope": "openid email profile",
      "token_endpoint_auth_method": "private_key_jwt",
      "token_endpoint_auth_signing_alg": "RS256",
      "request_object_signing_alg": "RS256",
      "jwks": {
        "keys": [
          {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "defaultjwks0526",
            "n": "2moVQ...2aq7Q"
          }
        ]
      },
      "client_registration_types": [
        "explicit",
        "automatic"
      ],
      "client_name": "New RP test",
      "contacts": [
        "jerome@casinthecloud.com"
      ]
    }
  },
  "federationKeys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "mykeyoidcfede26",
      "n": "nVoec...qELzQ"
    }
  ]
}

For the OP, we do something similar and call the URL: http://127.0.0.1:8080/c2id/.well-known/openid-federation to get the metadata and the federation keys:

{
  "sub": "http://127.0.0.1:8080/c2id",
  "metadata": {
    "federation_entity": {
      "organization_name": "pac4j_test_c2id"
    },
    "openid_provider": {
      "authorization_endpoint": "http://127.0.0.1:8080/c2id-login",
      "token_endpoint": "http://127.0.0.1:8080/c2id/token",
      "registration_endpoint": "http://127.0.0.1:8080/c2id/clients",
      "introspection_endpoint": "http://127.0.0.1:8080/c2id/token/introspect",
      "revocation_endpoint": "http://127.0.0.1:8080/c2id/token/revoke",
      "pushed_authorization_request_endpoint": "http://127.0.0.1:8080/c2id/par",
      "issuer": "http://127.0.0.1:8080/c2id",
      "jwks_uri": "http://127.0.0.1:8080/c2id/jwks.json",
      "scopes_supported": [
        "openid"
      ],
      "response_types_supported": [
        "code",
        "token",
        "id_token",
        "id_token token",
        "code id_token",
        "code id_token token"
      ],

      ...TRUNCATED...

      "claims_parameter_supported": true,
      "frontchannel_logout_supported": true,
      "frontchannel_logout_session_supported": true,
      "backchannel_logout_supported": true,
      "backchannel_logout_session_supported": true
    }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "bjBN",
        "iat": 1774636985,
        "n": "qoXzz...atFCQ"
      }
    ]
  },
  "iss": "http://127.0.0.1:8080/c2id",
  "authority_hints": [
    "http://localhost:8081/trustanchor"
  ],
  "exp": 1778493319,
  "iat": 1777888519,
  "constraints": {
    "max_path_length": 2
  }
}

and create the op.json file (in the /etc/cas/config/subordinates directory).

3) Declare CAS as the trust anchor

We have a trust anchor ready to use, but the RP and the OP don't know it: they still refer to the simulated one.

So let's update their configurations for that.

For the pac4j client, we adjust the Pac4jConfig Java configuration:

final var rpJwks = config.getRpJwks();
rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
rpJwks.setKid("defaultjwks0526");
config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
final var privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(rpJwks);
config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);

config.setRequestObjectSigningAlgorithm(JWSAlgorithm.RS256);

val federation = config.getFederation();

federation.setTargetOp("http://127.0.0.1:8080/c2id");
val trust = new OidcTrustAnchorProperties();
trust.setIssuer("http://localhost:8082/cas/oidc");
trust.setJwksPath("classpath:trustanchor.jwks");
federation.getTrustAnchors().add(trust);

federation.getJwks().setJwksPath("file:./metadata/oidcfede.jwks");
federation.getJwks().setKid("mykeyoidcfede26");
federation.setContactName("New RP test");
federation.setContactEmails(List.of("jerome@casinthecloud.com"));

federation.setEntityId("http://localhost:8081");

This setup is quite similar to the original one, except that the trust anchor is defined by the http://localhost:8082/cas/oidc URL and that we need to update its trustanchor.jwks definition file.

For that, we call its federation endpoint (http://localhost:8082/cas/oidc/.well-known/openid-federation) and decode its result:

{
  "sub": "http://localhost:8082/cas/oidc",
  "metadata": {
    "federation_entity": {
      "organization_name": "Apereo CAS",
      "federation_fetch_endpoint": "http://localhost:8082/cas/oidc/fetch",
      "contacts": []
    }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "4ddec6ab-b5d2-453a-8036-932f8770c9af",
        "n": "7jXA3...71IGw"
      }
    ]
  },
  "iss": "http://localhost:8082/cas/oidc",
  "exp": 1785628800,
  "iat": 1777852800,
  "constraints": {
    "max_path_length": 1
  }
}

The keys must be defined in the trustanchor.jwks file in the RP:

{
    "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "4ddec6ab-b5d2-453a-8036-932f8770c9af",
        "n": "7jXA3...71IGw"
      }
    ]
}

After this change, restart the pac4j RP.

For the Connect2id server, things are even easier as only the URL of the trust anchor is required.

In the ./tomcat/webapps/c2id/WEB-INF/oidcProvider.properties, you need this configuration:

### Federation ###

# Enables / disables OpenID Federation 1.0. Disabled by default.
op.federation.enable=true

# The configured trust anchors. Leave blank if none.
op.federation.trustAnchors.1=http://localhost:8082/cas/oidc

# Trust anchors or intermediate entities that may issue an entity statement
# about this OpenID provider. Leave blank if none.
op.federation.authorityHints.1=http://localhost:8082/cas/oidc
op.federation.authorityHints.2=
op.federation.authorityHints.3=

# The enabled OpenID Federation 1.0 client registration types. The default
# value is none (for deployments that use manual client registration only).
#
# Supported OpenID Federation 1.0 client registration types:
#
#     * explicit
#     * automatic
#
op.federation.clientRegistrationTypes=automatic

Federation is enabled, of course. The CAS trust anchor is defined as the first trust anchor and as the first authority hint. The registration is set to automatic.

Stop (./tomcat/bin/shutdown.sh) and restart (./tomcat/bin/startup.sh) the Connect2id server.

To make a proper test, you may need to remove any previously registered http://localhost:8081 client.

Using your token from the oidcProvider.properties file, you can query all existing clients:

curl -X GET http://127.0.0.1:8080/c2id/clients -H "Authorization: Bearer ztucZ...exmd6"

And remove it if it is still registered:

curl -X DELETE http://127.0.0.1:8080/c2id/clients/http%3A%2F%2Flocalhost%3A8081 -H "Authorization: Bearer ztucZ...exmd6"

Notice that for the client_id defined as a URL, you may need to update:

the setenv.sh file to add export JAVA_OPTS="$JAVA_OPTS -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
the server.xml file to add encodedSolidusHandling="decode" on the <Connector> definition.

4) Test again

With the RP and OP updated and restarted, and the CAS trust anchor running, you may try to log in by calling http://localhost:8081 in your browser and clicking on the protected link.

Now it works thanks to the real trust anchor.

If we take a look at the logs of the CAS server:

INFO [org.apereo.cas.oidc.federation.web.OidcWellKnownFederationEndpointController] - <Generating federation entity statement>
INFO [org.apereo.cas.oidc.federation.subordinate.OidcFederationSubordinateRepository] - <Loaded [2] subordinates>
INFO [org.apereo.cas.oidc.federation.web.OidcTrustAnchorFetchEndpointController] - <Building entity statement for
 subordinate: [http://127.0.0.1:8080/c2id]>
INFO [org.apereo.cas.oidc.federation.web.OidcWellKnownFederationEndpointController] - <Generating federation entity statement>
INFO [org.apereo.cas.oidc.federation.web.OidcTrustAnchorFetchEndpointController] - <Building entity statement for
 subordinate: [http://localhost:8081]>

We see that the federation endpoint has been called twice and the fetch endpoint (which returns the trust anchor confidence for the entity) has been called twice as well: one for the OP (http://127.0.0.1:8080/c2id) and the other for the RP (http://localhost:8081).

This was fully expected: the trust anchor is used to build the trust chains!

If we do the test again, nothing appears in the CAS trust anchor logs this time as the entity statements are not requested again: they are already known by the RP and the OP, until they expire or get lost (in-memory storage).

So the CAS server can act as a real trust anchor between the pac4j RP and the Connect2id OP.

How to secure a Java client application with OpenID Connect (using Spring Boot)

Jérôme LELEU — Mon, 12 Oct 2026 06:39:29 +0000

You want users to sign in to your Java application with Keycloak, Google, Microsoft Entra ID, Okta, Auth0 or even a CAS server. They already have an account there, so your application should not ask them for another password.

This is what OpenID Connect (OIDC) is for. It adds an identity layer on top of OAuth 2.0: the provider authenticates the user, and your application receives an ID token, a signed JWT describing who signed in. The user's password stays with the provider.

Let's put this into practice with pac4j and Spring Boot. We'll start with the public pac4j test server, then see what to change for Keycloak, Google or Azure AD. The same approach applies to other OpenID Connect providers.

What you need:

Java 17+ and Maven
an OpenID Connect provider where you can register an application, or the public demo server used below.

1) Create the Maven project

Create an empty Spring Boot project with Java 17:

mkdir -p spring-oidc-app/src/main/java/org/example
mkdir -p spring-oidc-app/src/main/resources
cd spring-oidc-app

Create a pom.xml file at the project root. The Spring Boot parent manages the Spring dependencies, and its Maven plugin runs the application:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>
    <groupId>org.example</groupId>
    <artifactId>spring-oidc-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Save the Java classes below in the org.example package so that Spring Boot discovers the configuration and controllers. Put the application settings in src/main/resources/application.yml.

2) Add the Maven dependencies

Inside the <dependencies> element, on top of Spring MVC, you need two pac4j artifacts: the Spring MVC integration and the OpenID Connect module.

<!-- Spring Boot web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- pac4j implementation for Spring MVC so for Spring Boot as well -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-webmvc-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for OpenID Connect -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>

Why two dependencies? pac4j-oidc handles the protocol, built on the Nimbus OAuth 2.0 / OpenID Connect SDK, while spring-webmvc-pac4j connects it to Spring MVC. The OidcClient itself knows nothing about Spring: you can use it with Jakarta EE, Play, Vert.x, JAX-RS and the other pac4j integrations.

3) Configure OpenID Connect (OIDC) authentication

Create src/main/java/org/example/SecurityConfig.java:

package org.example;

import org.pac4j.core.config.Config;
import org.pac4j.springframework.config.Pac4jSecurityConfig;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;

@Configuration
public class SecurityConfig extends Pac4jSecurityConfig {

    @Value("${app.base-url:http://localhost:8080}")
    private String baseUri;

    @Bean
    public Config config() {
        // configuration of the authentication via the OpenID Connect protocol
        final var config = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        return new Config(baseUri + "/callback", new OidcClient(config));
    }

    @Override
    public void addInterceptors(final InterceptorRegistry registry) {
        // the /protected/** URLs require the OIDC authentication
        addSecurity(registry, "OidcClient").addPathPatterns("/protected/**");
    }
}

There are two things to configure here: the OIDC client and the URLs of our application.

For the client, setDiscoveryURI points to the provider's .well-known/openid-configuration document. pac4j reads the authorization, token, user info and JWKS endpoints from it. So you do not have to configure each endpoint yourself. setClientId and setSecret are the credentials you receive when registering the application at the provider.

On the application side, Pac4jSecurityConfig registers /callback and /logout. The callback URL comes from new Config(baseUri + "/callback", ...), and pac4j appends ?client_name=OidcClient to it. This full URL is the redirect URI to register at your provider.

Finally, addSecurity(registry, "OidcClient") protects /protected/**. An anonymous user requesting one of these pages is redirected to the provider to log in.

By default, pac4j uses the authorization code flow and adds PKCE when the provider advertises support for it in its discovery document.

You may wonder why the example allows unsigned ID tokens. This is only because the public demo server issues them. Remove setAllowUnsignedIdTokens(true) for a real provider, so pac4j verifies the ID token signature against the provider's JWKS.

4) Register the application at your identity provider

Every provider needs the same three things: an application (or "client") with a redirect URI of http://localhost:8080/callback?client_name=OidcClient, and the resulting client ID and secret. What changes is where the discovery document lives, and pac4j ships dedicated clients for the common providers.

- For Keycloak: create a confidential client in your realm and set its "Valid redirect URIs". The KeycloakOidcConfiguration builds the discovery URL from the server base URL and the realm name:

final var config = new KeycloakOidcConfiguration()
    .setBaseUri("https://keycloak.example.com")
    .setRealm("myrealm");
config.setClientId("myclient");
config.setSecret("mysecret");
return new Config(baseUri + "/callback", new KeycloakOidcClient(config));

- For Google: create an "OAuth client ID" of type "Web application" in the Google Cloud console and add the redirect URI to "Authorized redirect URIs". The GoogleOidcClient already knows Google's discovery URL:

final var config = new OidcConfiguration()
    .setClientId("xxx.apps.googleusercontent.com")
    .setSecret("GOCSPX-...");
return new Config(baseUri + "/callback", new GoogleOidcClient(config));

- For Microsoft Entra ID (Azure AD): register an application in the Entra portal, add the redirect URI under "Web" platform and create a client secret. The AzureAd2Client takes the tenant identifier:

final var config = new AzureAd2OidcConfiguration("38c46e5a-21f0-46e5-940d-3ca06fd1a330");
config.setClientId("788339d7-1c44-4732-97c9-134cb201f01f");
config.setSecret("...");
return new Config(baseUri + "/callback", new AzureAd2Client(config));

For Okta, Auth0, a CAS server or any other provider, the generic OidcClient with the provider's discovery URL is all you need. Replace client_name=OidcClient in the redirect URI with the name of the client you use (KeycloakOidcClient, GoogleOidcClient, AzureAd2Client).

Update the security interceptor as well: the name passed to addSecurity must match the configured client. For example, with KeycloakOidcClient, replace the interceptor configuration from step 3 with:

addSecurity(registry, "KeycloakOidcClient").addPathPatterns("/protected/**");

Use GoogleOidcClient or AzureAd2Client in both places for the corresponding provider.

5) Access the authenticated user

Create src/main/java/org/example/Application.java to expose a public page and a protected page:

package org.example;

import org.pac4j.core.profile.ProfileManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class Application {

    @Autowired
    private ProfileManager profileManager;

    @GetMapping(value = "/", produces = "text/html")
    public String index() {
        return "<h1>Public area</h1><p><a href='/protected/index'>Protected area</a></p>"
            + "<p><a href='/logout'>Logout</a></p>";
    }

    @GetMapping(value = "/protected/index", produces = "text/plain")
    public String secure() {
        return "Protected area\n" + profileManager.getProfiles() + "\nVisit /logout to sign out.";
    }
}

Now that the user is authenticated, how do we get their information? The ProfileManager reads the profile saved in the session. For OIDC, this is an OidcProfile, with getters for the standard claims and access to the raw tokens:

final var profile = (OidcProfile) profileManager.getProfile().orElseThrow();
profile.getId();            // the "sub" claim
profile.getEmail();
profile.getDisplayName();
profile.getAttribute("preferred_username");
profile.getIdToken();       // the parsed ID token (JWT)
profile.getAccessToken();   // to call the provider's APIs

Which claims are present depends on the scopes you request. The default is openid profile email; add more with config.setScope("openid profile email phone").

6) Logout

The /logout link removes the profile from the application's session. This is the local logout: the user may still be logged in at the provider.

To end that session as well, enable central logout in application.yml:

pac4j:
  logout:
    centralLogout: true
    defaultUrl: http://localhost:8080/

For providers supporting OIDC logout, pac4j redirects the browser to the end_session_endpoint from the discovery document and supplies the absolute default URL as post_logout_redirect_uri. Register http://localhost:8080/ as an allowed post-logout redirect URI at the provider. A relative default URL such as / works for local logout but is not passed to the provider as a return URL.

If your provider supports OIDC logout but does not publish its endpoint, set it explicitly with config.setLogoutUrl(...). Logout support and registration requirements vary by provider; the dedicated GoogleOidcClient uses its own logout action rather than this discovery-based flow.

7) Run the application

Create src/main/java/org/example/SpringBootDemo.java:

package org.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootDemo {
    public static void main(final String[] args) {
        SpringApplication.run(SpringBootDemo.class, args);
    }
}

Start the application with mvn spring-boot:run.

Open http://localhost:8080/ and follow Protected area. You are redirected to the identity provider to sign in, then returned to the protected page, where the controller prints your profile.

If something goes wrong:

"Invalid redirect URI" or "redirect_uri_mismatch" at the provider: the registered URI must be the full callback URL, including ?client_name=OidcClient (or the name of the dedicated client configured in step 4).
"invalid_client" on the token request: wrong client secret, or the client is public at the provider while pac4j sends a secret.
The ID token signature fails: check that discovery points to the intended provider, that its JWKS is reachable and contains the current signing key, and that the expected signing algorithm matches the provider's client configuration. If an explicit algorithm is needed, use config.setIdTokenSigningAlgorithm(...) with that configured algorithm; changing it to ES256 is not a general fix for signature errors.
Empty name or email: the scopes or the provider's claim mapping do not release them. Check the scopes first, then the client configuration at the provider.

8) Learn more

The Spring Boot OIDC demo for a complete reference application.
The documentation for the OIDC client for Java: all the OidcConfiguration options, the implicit flow, private_key_jwt client authentication, nonce and state handling.
Direct OIDC authentication to protect a REST API with the access tokens issued by your provider.
OpenID Federation when your application belongs to a trust federation.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Java client application with SAML (using Spring Boot)

Jérôme LELEU — Mon, 12 Oct 2026 06:35:55 +0000

Your organization already has an identity provider and asks you to connect your Java application using SAML 2.0. Before writing any code, let's clarify the two sides of that connection.

The identity provider (IdP) authenticates the user. It might be Microsoft Entra ID, Okta, ADFS, Shibboleth, Keycloak or a CAS server. Your application is the service provider (SP): it receives a signed XML assertion from the IdP describing the authenticated user.

We'll make our application a SAML service provider with pac4j and Spring Boot. The example uses the public pac4j test IdP. Along the way, we'll see how to exchange metadata with your own IdP, read user attributes and handle logout.

What you need:

Java 17+ and Maven
the metadata of your IdP, as a URL or an XML file. Every IdP publishes it; ask your identity team if you do not know where it is. The example uses the metadata URL of the public test IdP.

1) Create the Maven project

Create an empty Spring Boot project with Java 17:

mkdir -p spring-saml-app/src/main/java/org/example
mkdir -p spring-saml-app/src/main/resources
cd spring-saml-app

Create a pom.xml file at the project root. The Spring Boot parent manages the Spring dependencies, and its Maven plugin runs the application:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>
    <groupId>org.example</groupId>
    <artifactId>spring-saml-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Save the Java classes below in the org.example package so that Spring Boot discovers the configuration and controllers. Put the application settings in src/main/resources/application.yml.

2) Add the Maven dependencies

Inside the <dependencies> element, on top of Spring MVC, you need the pac4j Spring MVC integration and the SAML module:

<!-- Spring Boot web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- pac4j implementation for Spring MVC so for Spring Boot as well -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-webmvc-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for SAML2 -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-saml</artifactId>
    <version>6.5.9</version>
</dependency>

pac4j-saml is built on OpenSAML, the reference SAML library in the Java world, which it brings in transitively.

3) Create the service provider keystore

Our service provider needs a key pair to sign requests and decrypt encrypted assertions. Let's create a Java keystore with keytool:

keytool -genkeypair -alias pac4j-demo -keypass pac4j-demo-passwd -storetype JKS -keystore src/main/resources/samlKeystore.jks -storepass pac4j-demo-passwd -keyalg RSA -keysize 2048 -validity 3650

Create a metadata directory at the project root for the generated SP metadata (mkdir -p metadata). If the keystore path you configure does not exist and is writable, pac4j generates the keystore and its key pair for you at first use.

4) Configure SAML 2.0 authentication

Create src/main/java/org/example/SecurityConfig.java:

package org.example;

import org.pac4j.core.config.Config;
import org.pac4j.springframework.config.Pac4jSecurityConfig;
import org.pac4j.saml.client.SAML2Client;
import org.pac4j.saml.config.SAML2Configuration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;

@Configuration
public class SecurityConfig extends Pac4jSecurityConfig {

    @Value("${app.base-url:http://localhost:8080}")
    private String baseUri;

    @Bean
    public Config config() {
        // configuration of the authentication via the SAML2 protocol
        final var cfg = new SAML2Configuration();
        cfg.getKeystore().setKeystorePath("classpath:samlKeystore.jks");
        cfg.getKeystore().setKeystorePassword("pac4j-demo-passwd");
        cfg.getKeystore().setPrivateKeyPassword("pac4j-demo-passwd");
        cfg.setIdentityProviderMetadataPath("https://www.casserverpac4j.dev/idp/metadata");
        cfg.setServiceProviderEntityId(baseUri + "/callback?client_name=SAML2Client");
        cfg.setServiceProviderMetadataPath("file:metadata/sp-metadata-8080.xml");
        return new Config(baseUri + "/callback", new SAML2Client(cfg));
    }

    @Override
    public void addInterceptors(final InterceptorRegistry registry) {
        // the /protected/** URLs require the SAML2 authentication
        addSecurity(registry, "SAML2Client").addPathPatterns("/protected/**");
    }
}

The first settings point to the keystore from step 3 and use the two passwords we gave to keytool. The classpath: prefix loads it from the application resources; file: and https: are also supported.

Then we tell pac4j about the IdP with setIdentityProviderMetadataPath. Its metadata contains the single sign-on URL, signing certificate and logout endpoint. There is no need to copy these values into separate settings.

Our application also needs an identity of its own. setServiceProviderEntityId gives it a unique name in the SAML world. Any URI works; the callback URL is a convenient choice. setServiceProviderMetadataPath tells pac4j where to write our SP metadata. We'll give that file to the IdP in the next step.

Finally, Pac4jSecurityConfig registers /callback and /logout, and addSecurity(registry, "SAML2Client") protects /protected/**. In SAML terms, the callback is our Assertion Consumer Service (ACS).

The IdP returns the assertion by a cross-site POST. Configure the session cookie in src/main/resources/application.yml so that the browser sends it on the callback:

server:
  servlet:
    session:
      cookie:
        same-site: none
        secure: true

Use HTTPS when deploying beyond localhost: SameSite=None requires a secure cookie.

5) Exchange metadata with your identity provider

We have given pac4j the IdP metadata, but we are only halfway there: the IdP must also know our application.

When the SAML2Client initializes, pac4j generates the SP metadata into metadata/sp-metadata-8080.xml. This XML document contains your entity ID, your public certificate and your ACS URL, http://localhost:8080/callback?client_name=SAML2Client. Register it at the IdP:

Entra ID, Okta, Auth0, Keycloak: create a SAML application and either upload this file or copy the entity ID and the ACS URL into the form.
Shibboleth, ADFS, simpleSAMLphp: add the file, or a URL serving it, to the IdP's list of relying parties.

You can also get the same XML programmatically with client.getServiceProviderMetadataResolver().getMetadata(), for instance to serve it from an endpoint.

If the IdP metadata is not reachable over HTTP from your application, download it once and load it from the classpath with cfg.setIdentityProviderMetadataPath("classpath:idp-metadata.xml").

6) Access the authenticated user

Create src/main/java/org/example/Application.java to expose a public page and a protected page:

package org.example;

import org.pac4j.core.profile.ProfileManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class Application {

    @Autowired
    private ProfileManager profileManager;

    @GetMapping(value = "/", produces = "text/html")
    public String index() {
        return "<h1>Public area</h1><p><a href='/protected/index'>Protected area</a></p>"
            + "<p><a href='/logout'>Logout</a></p>";
    }

    @GetMapping(value = "/protected/index", produces = "text/plain")
    public String secure() {
        return "Protected area\n" + profileManager.getProfiles() + "\nVisit /logout to sign out.";
    }
}

After login, the ProfileManager returns a SAML2Profile. Its identifier is the assertion's NameID, and its attributes are those released by the IdP.

Do not be surprised if the attribute names look like URNs instead of email or name: pac4j keeps the names supplied by the IdP. SAML attributes are also multi-valued, so you get a list:

final var profile = (SAML2Profile) profileManager.getProfile().orElseThrow();
profile.getId();                                            // the NameID
profile.getAttribute("urn:oid:0.9.2342.19200300.100.1.3");  // "mail" in many directories
profile.getAttributes();                                    // everything the IdP sent

Of course, you probably do not want these URNs all over your application code. Map them to readable names in the configuration:

cfg.setMappedAttributes(Map.of("urn:oid:0.9.2342.19200300.100.1.3", "email"));

The IdP decides which attributes it releases: if a value is missing, the attribute release rule for your SP at the IdP is the place to look.

7) Single logout

The /logout link removes the local profile. But the user can still have a session at the IdP and in other applications.

SAML defines single logout (SLO) for this: our application asks the IdP to end its session and notify the other applications. Enable it in application.yml:

pac4j:
  logout:
    centralLogout: true
    defaultUrl: /

pac4j then sends a LogoutRequest to the IdP's single logout endpoint, read from the IdP metadata, and processes the LogoutResponse on the callback URL. To sign outgoing logout requests, add this setting to the SAML2Configuration in step 4 before creating the client:

cfg.setSpLogoutRequestSigned(true);

In pac4j 6.5.9, this option is false by default: enabling central logout alone does not enable request signing. The HTTP-POST and HTTP-Redirect bindings are supported for these messages; pick the one your IdP expects with cfg.setSpLogoutRequestBindingType(...). SLO only works if the IdP metadata declares a SingleLogoutService.

8) Run the application

Create src/main/java/org/example/SpringBootDemo.java:

package org.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootDemo {
    public static void main(final String[] args) {
        SpringApplication.run(SpringBootDemo.class, args);
    }
}

Start the application with mvn spring-boot:run.

Open http://localhost:8080/ and follow Protected area. You are redirected to the IdP to sign in, then posted back to the callback URL with the assertion, and the protected page prints your profile.

If something goes wrong:

The IdP rejects the request as an unknown service provider: the SP metadata is not registered, or the entity ID at the IdP differs from setServiceProviderEntityId.
"Authentication issue instant is too old": check the clocks of both machines and any maximum authentication age configured with cfg.setMaximumAuthenticationLifetime(seconds). In pac4j 6.5.9, the default is 0, which disables this authentication-age check; an explicit positive value limits the age of the IdP authentication. Assertion validity timestamps are checked separately.
Signature validation fails: the IdP rotated its certificate. Reload the IdP metadata.
The assertion is missing a Destination: some IdPs omit it; pac4j requires it for security but you can relax it with cfg.setResponseDestinationAttributeMandatory(false).

9) Learn more

The Spring Boot SAML demo for a complete reference application.
The documentation for the SAML 2.0 client for Java: bindings, signature algorithms, forced and passive authentication, attribute converters and IdP-specific notes.
The SAML2Client keeps a replay cache between authentications, so define it once as a singleton, which is what the Spring bean above does.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Java client application with CAS (using Spring Boot)

Jérôme LELEU — Mon, 12 Oct 2026 06:34:24 +0000

CAS can mean two things: the open source single sign-on server maintained by the Apereo foundation, or the Central Authentication Service protocol. Here, we'll use the CAS protocol to connect our Java application to a CAS server.

The flow is easy to follow. Your application redirects the user to the CAS login page. After authentication, CAS sends the browser back with a short-lived service ticket. Your application validates this ticket with the CAS server to find out who the user is.

Let's see how to do this with pac4j and Spring Boot. We'll use the public pac4j test server first, then look at service registration for your own CAS server.

What you need:

Java 17+ and Maven
the login URL of a CAS server, such as https://cas.example.com/cas/login, and the right to register a service on it. The demo uses the public test server.

1) Create the Maven project

Create an empty Spring Boot project with Java 17:

mkdir -p spring-cas-app/src/main/java/org/example
mkdir -p spring-cas-app/src/main/resources
cd spring-cas-app

Create a pom.xml file at the project root. The Spring Boot parent manages the Spring dependencies, and its Maven plugin runs the application:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>
    <groupId>org.example</groupId>
    <artifactId>spring-cas-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Save the Java classes below in the org.example package so that Spring Boot discovers the configuration and controllers. Put application properties in src/main/resources/application.properties.

2) Add the Maven dependencies

Inside the <dependencies> element, on top of Spring MVC, you need the pac4j Spring MVC integration and the CAS module:

<!-- Spring Boot web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- pac4j implementation for Spring MVC so for Spring Boot as well -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-webmvc-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for CAS -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-cas</artifactId>
    <version>6.5.9</version>
</dependency>

pac4j-cas is a full CAS client (based on the official Apereo CAS client): it speaks the CAS protocol versions 1.0, 2.0 and 3.0, and also supports proxy tickets and the CAS REST API, covered at the end of this guide.

3) Configure CAS authentication

Create src/main/java/org/example/SecurityConfig.java:

package org.example;

import org.pac4j.core.config.Config;
import org.pac4j.springframework.config.Pac4jSecurityConfig;
import org.pac4j.cas.client.CasClient;
import org.pac4j.cas.config.CasConfiguration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;

@Configuration
public class SecurityConfig extends Pac4jSecurityConfig {

    @Value("${app.base-url:http://localhost:8080}")
    private String baseUri;

    @Value("${cas.login-url:https://www.casserverpac4j.dev/login}")
    private String casLoginUrl;

    @Bean
    public Config config() {
        // configuration of the authentication via the CAS protocol
        return new Config(baseUri + "/callback", new CasClient(new CasConfiguration(casLoginUrl)));
    }

    @Override
    public void addInterceptors(final InterceptorRegistry registry) {
        // the /protected/** URLs require the CAS authentication
        addSecurity(registry, "CasClient").addPathPatterns("/protected/**");
    }
}

The CAS configuration starts with a single URL: CasConfiguration(casLoginUrl). pac4j derives the ticket validation URL from it. If validation must use an internal address, you can set it separately with config.setPrefixUrl("http://cas-internal:8080/cas").

Pac4jSecurityConfig registers /callback, where CAS sends the service ticket, and /logout. With new Config(baseUri + "/callback", ...), we tell pac4j where the callback lives. It appends ?client_name=CasClient, and this full URL is the service CAS will see.

We then protect /protected/** with addSecurity(registry, "CasClient"). When an anonymous user requests a protected page, pac4j redirects the browser to casLoginUrl with that service URL as a parameter.

pac4j uses the CAS 3.0 protocol by default, which returns the user attributes with the validation response. Switch with config.setProtocol(CasProtocol.CAS20) for an older server. Two other options are worth knowing: setRenew(true) forces the user to re-enter credentials even with an active SSO session, and setGateway(true) returns silently when the user is not logged in instead of showing the login page.

4) Register the service on the CAS server

A CAS server only issues tickets for services it knows. In the CAS service registry, declare a service whose serviceId pattern matches the callback URL. With the JSON service registry of Apereo CAS v6+, the definition looks like this:

{
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "^http://localhost:8080/callback\\?client_name=CasClient.*",
  "name" : "pac4j Spring Boot demo",
  "id" : 1000,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllAttributeReleasePolicy"
  }
}

There are two settings to pay attention to:

serviceId is a regular expression. Escape the ? and keep the trailing .*, because CAS appends its own parameters to the callback.
attributeReleasePolicy decides which user attributes your application receives. ReturnAllAttributeReleasePolicy is fine for a demo; production services usually list the allowed attributes with ReturnAllowedAttributeReleasePolicy.

See the Apereo CAS service management documentation for the other registries (database, LDAP, Git...) and options.

5) Access the authenticated user

Create src/main/java/org/example/Application.java to expose a public page and a protected page:

package org.example;

import org.pac4j.core.profile.ProfileManager;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class Application {

    @Autowired
    private ProfileManager profileManager;

    @GetMapping(value = "/", produces = "text/html")
    public String index() {
        return "<h1>Public area</h1><p><a href='/protected/index'>Protected area</a></p>"
            + "<p><a href='/logout'>Logout</a></p>";
    }

    @GetMapping(value = "/protected/index", produces = "text/plain")
    public String secure() {
        return "Protected area\n" + profileManager.getProfiles() + "\nVisit /logout to sign out.";
    }
}

After login, the ProfileManager returns a CasProfile. Its identifier is the CAS principal, usually the username, and its attributes are exactly those released by the service's attribute release policy:

final var profile = (CasProfile) profileManager.getProfile().orElseThrow();
profile.getId();                 // the CAS principal
profile.getAttribute("email");
profile.getAttributes();         // everything the release policy allowed

No attributes in the profile? Check what the service is allowed to receive. The release policy may filter them out, or the server may still use CAS 2.0, which does not carry attributes.

6) Logout

Logging out of the application and logging out of CAS are two different operations. The /logout link removes the local profile. To also end the SSO session on the CAS server, enable central logout in application.properties:

pac4j.logout.centralLogout=true
pac4j.logout.defaultUrl=/

pac4j then redirects the browser to the CAS /logout endpoint. The reverse direction works too: when the user logs out from CAS or from another application, the CAS server notifies every service that received a ticket during the session, and the CasClient processes these single logout requests to destroy the local session.

7) Run the application

Create src/main/java/org/example/SpringBootDemo.java:

package org.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootDemo {
    public static void main(final String[] args) {
        SpringApplication.run(SpringBootDemo.class, args);
    }
}

Start the application with mvn spring-boot:run.

Open http://localhost:8080/ and click on the Protected area link. You are redirected to the CAS login page, then sent back to the callback with a service ticket, and the protected page prints your profile.

If something goes wrong:

"Application Not Authorized to Use CAS": the service is not registered, or the serviceId pattern does not match the full callback URL.
Ticket validation fails after the redirection: the validation URL derived from the login URL is not reachable from your server. Set setPrefixUrl explicitly.
The login page shows again and again: the server and the application disagree on the service URL, typically because of a reverse proxy. Set app.base-url to the public URL of the application.
No attributes in the profile: see the release policy and the protocol version in step 5.

8) Beyond the login page

So far, we have used CAS to log in through a browser. The same pac4j-cas module also handles other situations:

Proxy tickets: a web application authenticated by CAS calls a web service on behalf of the user. Configure a CasProxyReceptor on the caller and protect the web service with a DirectCasProxyClient.
CAS REST API: a mobile or standalone application sends the user credentials to your web service, which validates them against the CAS REST protocol with a CasRestFormClient or a CasRestBasicAuthClient.

9) Learn more

The Spring Boot CAS demo for a complete reference application.
Read the documentation for the CAS client for Java for the proxy and REST configurations, the stateless DirectCasClient and all the CasConfiguration options.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Spring Security client application with OIDC (using pac4j)

Jérôme LELEU — Thu, 08 Oct 2026 07:22:30 +0000

If you already have Spring Security in your application, with hasRole rules, @PreAuthorize on services and code reading SecurityContextHolder and you want to add an OpenID Connect login, while keeping that authorization code, you can use pac4j for that.

Whatever the provider (Keycloak, Microsoft Entra ID, Okta, a CAS server, etc.), once pac4j has authenticated the user, it can make that user available to Spring Security.

The spring-security-pac4j bridge does this. It transfers the pac4j profile into the Spring Security context; it does not perform authentication itself. Adding the bridge alone will not give you an OIDC login.

For authentication, choose a pac4j implementation:

jakartaee-pac4j, servlet filters that fit in any Spring Security filter chain, used in this guide
spring-webmvc-pac4j, interceptors for Spring MVC
spring-webflux-pac4j, for reactive applications.

The implementation runs the OIDC flow and builds a profile. The bridge turns it into a Spring Security Authentication, with the pac4j roles as authorities. Your hasRole rules, method security and SecurityContextHolder can then use it.

If you are starting from scratch, a pac4j implementation alone is simpler. Here, we're interested in connecting pac4j to an application that already relies on Spring Security.

What you need:

Java 17 or later and Maven
Spring Boot v4.x, which brings Spring Security v7, or Spring Boot v3.x with Spring Security v6: the bridge supports both
an OpenID Connect provider where you can register an application, or the public demo server used below.

1) Create the Maven project

Create an empty Spring Boot project with Java 17:

mkdir -p spring-security-oidc-app/src/main/java/org/pac4j/demo/spring
mkdir -p spring-security-oidc-app/src/main/resources
cd spring-security-oidc-app

Create a pom.xml file at the project root. The Spring Boot parent manages the Spring dependencies, and its Maven plugin runs the application:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>
    <groupId>org.example</groupId>
    <artifactId>spring-security-oidc-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Save the Java classes below in the org.pac4j.demo.spring package so that Spring Boot discovers the configuration and controllers. Put application properties in src/main/resources/application.properties.

Create src/main/java/org/pac4j/demo/spring/SpringBootApp.java:

package org.pac4j.demo.spring;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootApp {

    public static void main(final String[] args) {
        SpringApplication.run(SpringBootApp.class, args);
    }
}

2) Add the Maven dependencies

On top of the Spring Boot Web MVC and security starters, you need three pac4j artifacts: the pac4j implementation that authenticates, here the jakartaee-pac4j servlet filters, the OpenID Connect module, and the bridge.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<!-- the pac4j implementation: security, callback and logout filters -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>jakartaee-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for OpenID Connect -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>
<!-- the bridge: pushes the pac4j profile into the Spring Security context -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-security-pac4j</artifactId>
    <version>10.1.0</version>
</dependency>

Spring Boot v4 splits the former spring-boot-starter-web into spring-boot-starter-webmvc and spring-boot-starter-webflux. With Spring Boot v3.x, use spring-boot-starter-web instead: the other dependencies are the same. No logging dependency is needed in either case: Spring Framework v6 brings its spring-jcl bridge transitively, and Spring Framework v7 uses Apache Commons Logging directly, routed to SLF4J by Spring Boot.

The bridge needs an implementation such as jakartaee-pac4j, spring-webmvc-pac4j or spring-webflux-pac4j to produce a profile. It has no configuration of its own: pac4j detects it on the classpath and installs a SpringSecurityProfileManager.

Each time a profile is saved or removed, this manager updates the Spring Security context. The bridge version used here, v10.1.0, targets pac4j v6 and works with Spring Security v6 and v7: the Spring Boot parent, v3.x or v4.x, decides which Spring Security version is used. The configuration below is the same in both cases.

3) Configure pac4j

Create src/main/java/org/pac4j/demo/spring/Pac4jConfig.java to declare our Config as a Spring bean. The OIDC client configuration is familiar, but we'll add an authorization generator: it turns trusted profile attributes into the roles our application expects.

package org.pac4j.demo.spring;

import java.util.Collection;
import java.util.Optional;
import org.pac4j.core.config.Config;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Pac4jConfig {

    @Bean
    public Config config() {
        // configuration of the authentication via the OpenID Connect protocol
        final var oidcConfiguration = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        final var oidcClient = new OidcClient(oidcConfiguration);

        // the roles of the pac4j profile become the Spring Security authorities
        oidcClient.setAuthorizationGenerator((ctx, profile) -> {
            profile.addRole("ROLE_USER");
            if (profile.getAttribute("groups") instanceof Collection<?> groups
                    && groups.contains("administrators")) {
                profile.addRole("ROLE_ADMIN");
            }
            return Optional.of(profile);
        });

        return new Config("http://localhost:8080/callback", oidcClient);
    }
}

The bridge keeps role names unchanged when creating GrantedAuthority instances. So if your code checks hasRole("ADMIN"), the profile needs ROLE_ADMIN, including the prefix.

In this example, only a user whose groups attribute contains administrators receives that role. The provider must release this claim, and trusted administrators must control group membership. Adapt the mapping to the claims your provider actually releases: Keycloak, for example, puts realm roles in a realm_access claim holding a roles list, not in a flat groups claim. Without the expected group, our user only gets ROLE_USER.

The callback URL, with the ?client_name=OidcClient suffix pac4j appends, is the redirect URI to register at the provider. setAllowUnsignedIdTokens(true) only exists for the public demo server: remove it for a real provider. To register the application at Keycloak, Google or Entra ID, see the provider section of the Spring Boot guide.

4) Put the pac4j filters in the Spring Security chain

The pac4j filters run inside the Spring Security filter chains, one chain per URL pattern, so that the session and the security context are shared.

Save the filter-chain configuration in src/main/java/org/pac4j/demo/spring/SecurityConfig.java:

package org.pac4j.demo.spring;

import org.pac4j.core.config.Config;
import org.pac4j.jee.filter.CallbackFilter;
import org.pac4j.jee.filter.LogoutFilter;
import org.pac4j.jee.filter.SecurityFilter;
import org.pac4j.springframework.security.web.Pac4jEntryPoint;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.www.BasicAuthenticationFilter;

@Configuration
@EnableMethodSecurity
@EnableWebSecurity
public class SecurityConfig {

    @Autowired
    private Config config;

    // the OIDC login protects /protected/**
    @Bean
    @Order(1)
    public SecurityFilterChain protectedFilterChain(final HttpSecurity http) throws Exception {
        http
            .securityMatcher("/protected/**")
            .addFilterBefore(new SecurityFilter(config, "OidcClient"), BasicAuthenticationFilter.class)
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.ALWAYS));
        return http.build();
    }

    // the provider redirects the user here after login
    @Bean
    @Order(2)
    public SecurityFilterChain callbackFilterChain(final HttpSecurity http) throws Exception {
        http
            .securityMatcher("/callback")
            .addFilterBefore(new CallbackFilter(config), BasicAuthenticationFilter.class)
            .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // logs the user out of pac4j and of Spring Security
    @Bean
    @Order(3)
    public SecurityFilterChain logoutFilterChain(final HttpSecurity http) throws Exception {
        final var logoutFilter = new LogoutFilter(config, "/");
        logoutFilter.setDestroySession(true);
        http
            .securityMatcher("/pac4jLogout")
            .addFilterBefore(logoutFilter, BasicAuthenticationFilter.class)
            .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // rules for requests not handled by the chains above
    @Bean
    @Order(4)
    public SecurityFilterChain defaultFilterChain(final HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .anyRequest().permitAll())
            .exceptionHandling(handling -> handling
                .authenticationEntryPoint(new Pac4jEntryPoint(config, "OidcClient")));
        return http.build();
    }
}

Let's follow the login through these chains. On /protected/**, SecurityFilter redirects an anonymous user to the OIDC provider. SessionCreationPolicy.ALWAYS ensures that pac4j has a session to keep the login state.

The provider then returns the browser to /callback. CallbackFilter validates the ID token and saves the profile. The bridge also saves a Spring Security Authentication in the session.

The callback chain disables Spring Security's CSRF checks to accept provider responses sent by POST, such as OIDC form_post. The default code flow returns by GET. pac4j validates the OIDC response and its state; keep CSRF protection on the application's other state-changing endpoints.

The default chain handles the remaining URLs. It protects /admin/** with hasRole("ADMIN"), using the role from our authorization generator. Its optional Pac4jEntryPoint starts OIDC login for anonymous users instead of showing a form login page.

Only the first matching Spring Security chain runs. Rules in defaultFilterChain do not apply to /protected/**, /callback or /pac4jLogout. The protected chain above delegates access control to pac4j; add any additional Spring Security authorization rules to that chain, or use pac4j authorizers. When adapting an existing application, preserve its required rules in the appropriate chains.

Using Spring MVC interceptors instead of servlet filters? Follow the webmvc bridge demo. Interceptors run after Spring Security's servlet filters, so its chains must allow requests to reach the pac4j interceptors where required. Switching the dependency alone is not sufficient.

5) Access the authenticated user

Create src/main/java/org/pac4j/demo/spring/ProtectedController.java to read the Spring Security context after login. Its Authentication is a Pac4jAuthenticationToken: the name is the user identifier, the authorities are the pac4j roles and the principal is the profile itself.

package org.pac4j.demo.spring;

import org.pac4j.oidc.profile.OidcProfile;
import org.springframework.http.MediaType;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ProtectedController {

    @GetMapping(value = "/protected/oidc", produces = MediaType.TEXT_PLAIN_VALUE)
    public String index() {
        final var authentication = SecurityContextHolder.getContext().getAuthentication();
        final var profile = (OidcProfile) authentication.getPrincipal();
        return "Hello " + profile.getDisplayName() + " (" + profile.getEmail() + ")"
            + "\nAuthorities: " + authentication.getAuthorities();
    }
}

@EnableMethodSecurity in the configuration above enables method authorization. On a Spring-managed service, the authorities come from the same context:

@PreAuthorize("hasRole('ADMIN')")
public void deleteAccount(final String accountId) {
    // delete the account
}

You can also inject the principal with @AuthenticationPrincipal OidcProfile profile in a controller method, or use the pac4j ProfileManager when you need the list of profiles.

6) Logout

Use the /pac4jLogout URL, as configured above, to log out. Through the bridge, this clears both the pac4j profile and the Spring Security context (destroySession also invalidates the HTTP session). Calling Spring Security's /logout only clears the Spring Security context, not the pac4j profile.

To also end the session at the provider, enable central logout on the filter:

logoutFilter.setCentralLogout(true);
logoutFilter.setDefaultUrl("http://localhost:8080/");

For providers that support OIDC logout, pac4j redirects the browser to the end_session_endpoint in the discovery document. Register the absolute return URL as an allowed post-logout redirect URI at the provider; use your public HTTPS URL in production. If you accept a dynamic return URL through the logout request's url parameter, also restrict it with setLogoutUrlPattern(...).

7) Run the application

mvn spring-boot:run

Open http://localhost:8080/protected/oidc: you are redirected to the identity provider, then back to the page, where both the Spring Security context and the pac4j profile show the same user. To try the /admin/** role rule, add an admin endpoint to your controller. It returns 403 unless the provider supplies the administrators group expected by the authorization generator.

If something goes wrong:

403 on `/admin/ after login**: the role is missing or lacks the ROLE_` prefix. Check the authorization generator.
The form login page shows instead of the provider: the anonymous request hit the default chain. Either map the URL to a chain with the pac4j SecurityFilter, or set the Pac4jEntryPoint as above.
403 on a POST to /callback: check that the callback chain matches and that Spring Security CSRF checks are disabled on that chain.
Logged in for pac4j but anonymous for Spring Security: the bridge is not on the classpath, or a custom ProfileManagerFactory overrides its SpringSecurityProfileManager.
Nothing happens at all: the bridge is alone on the classpath. Add a pac4j implementation, it is the one that authenticates.

8) Switching to SAML or CAS

Add the corresponding pac4j-saml or pac4j-cas dependency, replace the OidcClient in the Config bean with a SAML2Client or a CasClient, and update the client name in the SecurityFilter and the Pac4jEntryPoint. Adapt the authorization generator to the attributes supplied by that provider, and replace the controller's OidcProfile cast with the corresponding profile type or the common UserProfile interface. The filter-chain structure and the bridge remain the same; callback and logout registration depend on the protocol. The protocol-specific setup is described in the SAML guide and the CAS guide.

9) Learn more

The documentation for the OIDC client for Java for all the OidcConfiguration options.
The spring-security-pac4j bridge and its documentation.
The three demos, all on Spring Boot v4 and Spring Security v7: with the servlet filters, with Spring MVC and with Spring WebFlux.
Why you may not need Spring Security at all: Spring Boot security: choose spring-webmvc-pac4j over Spring Security and the REST API follow-up.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Shiro client application with CAS (using pac4j)

Jérôme LELEU — Wed, 07 Oct 2026 07:11:14 +0000

Here is your use case: your application already uses Shiro, you have defined URL rules in shiro.ini, it calls SecurityUtils.getSubject() and role checks in the code. Now you need to connect it to a CAS server, while keeping those authorization rules.

Since the shiro-cas module was retired, Shiro no longer provides its own CAS client. So we can use pac4j for the authentication and pass the result to Shiro.

This is the role of buji-pac4j. But there is a distinction to make: buji-pac4j is a bridge, not an authentication implementation. It transfers the pac4j profile to the Shiro subject, but it cannot start a CAS login on its own.

For that, you need to choose a pac4j implementation:

jakartaee-pac4j, servlet filters that Shiro can map on URLs like its own filters, used in this guide
spring-webmvc-pac4j, if your Shiro application is also a Spring MVC application.

The implementation handles CAS and produces a user profile. The bridge then logs that profile into Shiro through a dedicated realm, exposing the pac4j roles as Shiro roles. Then, your roles[...] rules and subject.hasRole checks can use them.

For a new application, a pac4j implementation alone is simpler. The bridge is useful when you already have Shiro code to keep.

What you need:

Java 17 or later and Maven
Apache Shiro 3.x on a Servlet 5 or 6 container: Tomcat 10+, Jetty 11+, or the Jetty Maven plugin used below
the login URL of a CAS server and the right to register a service on it, or the public pac4j test server used below.

1) Create the Maven project

Create a small web application packaged as a WAR:

mkdir -p shiro-cas-app/src/main/java/org/example/security shiro-cas-app/src/main/resources
mkdir -p shiro-cas-app/src/main/webapp/WEB-INF shiro-cas-app/src/main/webapp/protected shiro-cas-app/src/main/webapp/admin
cd shiro-cas-app

Create a pom.xml file. Jetty 11 supplies the Jakarta Servlet runtime and serves the JSP pages:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.example</groupId>
    <artifactId>shiro-cas-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>

    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.16.0</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.5.1</version>
            </plugin>
            <plugin>
                <groupId>org.eclipse.jetty</groupId>
                <artifactId>jetty-maven-plugin</artifactId>
                <version>11.0.26</version>
                <configuration>
                    <webApp>
                        <contextPath>/</contextPath>
                    </webApp>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Create src/main/webapp/WEB-INF/web.xml to install the Shiro environment and filter:

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">
    <listener>
        <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
    </listener>
    <filter>
        <filter-name>ShiroFilter</filter-name>
        <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>ShiroFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
</web-app>

Create src/main/webapp/index.jsp with links to the resources we'll protect:

<%@ page contentType="text/html; charset=UTF-8" %>
<a href="/protected/index.jsp">Protected area</a>
<a href="/admin/index.jsp">Admin area</a>
<a href="/pac4jLogout">Logout</a>

The buji-pac4j-demo is a more complete reference with several authentication mechanisms.

2) Add the Maven dependencies

Inside the <dependencies> element, add shiro-web and three pac4j artifacts: the pac4j implementation that authenticates, here the jakartaee-pac4j servlet filters, the CAS module, and the bridge.

<!-- Apache Shiro for web applications -->
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-web</artifactId>
    <version>3.0.1</version>
</dependency>
<!-- the pac4j implementation: security, callback and logout filters -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>jakartaee-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for CAS -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-cas</artifactId>
    <version>6.5.9</version>
</dependency>
<!-- the bridge: pushes the pac4j profile into the Shiro subject -->
<dependency>
    <groupId>io.buji</groupId>
    <artifactId>buji-pac4j</artifactId>
    <version>10.0.1</version>
</dependency>

Each dependency has a job: without jakartaee-pac4j (or spring-webmvc-pac4j), nothing starts the login, so the bridge has no profile to pass to Shiro.

The versions above use Jakarta APIs. Shiro 3 does not need a jakarta classifier, and bridge version 10 targets pac4j v6 and Shiro v3. For Shiro v2 with javax.servlet, use bridge version 9.1 and the javaee-pac4j filters.

You may notice that we haven't declared a realm yet. The bridge supplies a default Shiro INI alongside yours, loaded through its WebEnvironment. It declares config, clients, a Pac4jRealm and a subject factory.

On the pac4j side, it installs a ShiroProfileManager. Saving a profile logs the Shiro subject in while removing the profile logs it out. This is where the two security models meet.

3) Configure pac4j in shiro.ini

Create src/main/resources/shiro.ini. Everything else is plain Shiro INI. The config and clients objects come from the bridge. You declare the CAS client, plug it into clients, and define the pac4j filters as Shiro filters:

[main]
# the CAS client
casConfig = org.pac4j.cas.config.CasConfiguration
casConfig.loginUrl = https://www.casserverpac4j.dev/login

casClient = org.pac4j.cas.client.CasClient
casClient.configuration = $casConfig

# the callback URL and the list of clients (the "clients" object is declared by the bridge)
clients.callbackUrl = http://localhost:8080/callback
clients.clients = $casClient

# the pac4j filters, declared like any Shiro filter
casSecurityFilter = org.pac4j.jee.filter.SecurityFilter
casSecurityFilter.config = $config
casSecurityFilter.clients = CasClient

callbackFilter = org.pac4j.jee.filter.CallbackFilter
callbackFilter.config = $config

pac4jLogout = org.pac4j.jee.filter.LogoutFilter
pac4jLogout.config = $config
pac4jLogout.defaultUrl = /
pac4jLogout.destroySession = true

[urls]
/protected/** = casSecurityFilter
/callback = callbackFilter
/pac4jLogout = pac4jLogout
/admin/** = casSecurityFilter, roles[ROLE_ADMIN]
/** = anon

For CAS itself, casConfig.loginUrl is the only mandatory setting. pac4j derives the validation URL from it and uses CAS 3.0 by default to retrieve user attributes. If validation needs an internal address, set casConfig.prefixUrl = http://cas-internal:8080/cas. For an older server, casConfig.protocol = CAS20 selects CAS 2.0.

clients.callbackUrl, with ?client_name=CasClient appended by pac4j, is the service URL seen by CAS. Register it as explained in the service registration section of the Spring Boot guide.

Now follow a request to /protected/**: casSecurityFilter starts the login for an anonymous user. On the way back, callbackFilter validates the service ticket, saves the pac4j profile and, through the bridge, logs the Shiro subject in. The same callback also receives CAS single logout notifications. You can declare more SecurityFilter instances for other clients or authorizers.

Pay attention to /admin/**: roles[ROLE_ADMIN] alone would not start the CAS login, so casSecurityFilter comes first in its chain. Shiro walks [urls] from top to bottom and runs only the first chain whose pattern matches, without adding the others. So each rule must list every filter it needs, and the catch-all /** = anon must stay last.

The web.xml is the standard Shiro one: the EnvironmentLoaderListener and the ShiroFilter mapped on /*. Nothing pac4j-specific goes there.

4) Map the CAS user to Shiro roles

Create src/main/java/org/example/security/RoleAuthorizationGenerator.java. We now have an authenticated user, but where do the Shiro roles come from? Pac4jRealm exposes the pac4j profile's roles with their names unchanged. CAS, however, sends attributes, not pac4j roles.

An authorization generator makes the connection. For example, we can derive a role from a memberOf attribute released by the CAS service:

package org.example.security;

import java.util.Collection;
import java.util.Optional;
import org.pac4j.core.authorization.generator.AuthorizationGenerator;
import org.pac4j.core.context.CallContext;
import org.pac4j.core.profile.UserProfile;

public class RoleAuthorizationGenerator implements AuthorizationGenerator {

    @Override
    public Optional<UserProfile> generate(final CallContext ctx, final UserProfile profile) {
        profile.addRole("ROLE_USER");
        final var groups = profile.getAttribute("memberOf");
        final var adminGroup = "cn=admins,ou=groups,dc=example,dc=com";
        if (adminGroup.equals(groups)
                || (groups instanceof Collection<?> values && values.contains(adminGroup))) {
            profile.addRole("ROLE_ADMIN");
        }
        return Optional.of(profile);
    }
}

Add these declarations to the [main] section, before [urls]:

roleGenerator = org.example.security.RoleAuthorizationGenerator
casClient.authorizationGenerator = $roleGenerator

Replace adminGroup with the exact group value released by your CAS server. Group membership must be controlled by administrators as a substring check could grant access to a different group with a similar name.

Shiro permissions work the same way: put the permission strings, or Shiro Permission objects, in the profile attribute named by Pac4jRealm.SHIRO_PERMISSIONS, as a collection, an array or a single value, and subject.isPermitted(...) sees them. With a Shiro cache manager, the realm caches the roles and permissions per login and clears them when pac4j renews the profiles.

5) Access the authenticated user

Create src/main/webapp/protected/index.jsp to read the user through the Shiro API, and copy it to src/main/webapp/admin/index.jsp to exercise the admin rule:

<%@ page contentType="text/plain; charset=UTF-8" %>
<%@ page import="org.apache.shiro.SecurityUtils" %>
<%@ page import="io.buji.pac4j.subject.Pac4jPrincipal" %>
<%
    final var subject = SecurityUtils.getSubject();
    final var principal = subject.getPrincipals().oneByType(Pac4jPrincipal.class);
    out.println("Shiro principal: " + subject.getPrincipal());
    out.println("pac4j profile: " + principal.getProfile());
%>

The plain-text response displays the profile without interpreting its attributes as HTML. We can also read the user in Java code through the Shiro API. The subject is authenticated and its primary principal is the CAS principal, usually the username. A Pac4jPrincipal in the principal collection gives us the full pac4j profile:

final var subject = SecurityUtils.getSubject();
subject.isAuthenticated();               // true after the CAS login
subject.hasRole("ROLE_ADMIN");           // from the authorization generator
subject.getPrincipal();                  // the CAS principal

final var principal = subject.getPrincipals().oneByType(Pac4jPrincipal.class);
final var profile = (CasProfile) principal.getProfile();
profile.getAttribute("email");
profile.getAttributes();                 // everything the release policy allowed

An empty attribute map can mean the release policy of the service is too restrictive, or the server still uses the CAS 2.0 protocol. To use another attribute as the principal name, set pac4jRealm.principalNameAttribute = email in the [main] section; a user without that attribute keeps the CAS principal as name.

6) Logout

For logout, use the /pac4jLogout URL (configured above). The pac4j filter (and bridge) remove the profile and log the Shiro subject out together (the destroySession option invalidates the session). This must not be confused with Shiro's built-in logout filter, which does not perform this whole operation.

To also end the CAS SSO session, enable central logout on the filter:

pac4jLogout.centralLogout = true
pac4jLogout.defaultUrl = http://localhost:8080/

pac4j then redirects the browser to the CAS /logout endpoint. The CAS server must allow the requested return URL. If you accept a dynamic url parameter, restrict it separately with logoutUrlPattern.

When CAS single logout is enabled, the CAS server can notify participating services on their callback URLs. Processing those notifications on pac4j Shiro side also requires a session store that can recover and destroy the recorded session. A local logout alone does not notify other applications.

7) Run the application

mvn clean package jetty:run

Open http://localhost:8080/protected/index.jsp: you are redirected to the CAS login page, then back with a service ticket, and the page shows both the Shiro principals and the pac4j profile. Then try http://localhost:8080/admin/index.jsp: access is denied unless CAS releases the exact administrator group expected by the generator.

If unfortunately something goes wrong:

"Application Not Authorized to Use CAS": the service is not registered, or its serviceId pattern does not match the full callback URL.
The subject is anonymous after the callback: the bridge is not on the classpath, or another WebEnvironment is configured in web.xml and shadows the bridge's Pac4jIniEnvironment.
roles[ROLE_ADMIN] denies a CAS user: no authorization generator sets the role, or the attribute it reads is not released by the service.
Nothing happens at all: the bridge is alone on the classpath. Add a pac4j implementation, it is the one that authenticates.

8) Switching to OIDC or SAML

Add pac4j-oidc or pac4j-saml, declare the corresponding client in the INI, reference it in clients.clients and update the security filter's clients property. Keep the bridge and realm, but adapt profile casts, attribute-to-role mappings and callback/logout registration to the provider. The protocol-specific setup is described in the OIDC guide and the SAML guide. The demo's shiro.ini declares all three side by side.

9) Learn more

The buji-pac4j bridge and its documentation.
The buji-pac4j-demo application, with CAS, OIDC, SAML and HTTP basic authentication.
The documentation for the CAS client for Java for proxy tickets, the CAS REST API and all the CasConfiguration options, and the Jakarta EE guide for the pac4j filters used here, outside Shiro.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Spring WebFlux client application with OIDC (using pac4j)

Jérôme LELEU — Mon, 05 Oct 2026 06:00:31 +0000

Spring WebFlux is Spring's reactive alternative to Spring MVC: it uses non-blocking I/O and Reactor's Mono and Flux to handle concurrent requests with a small pool of threads. Both frameworks share the same controller annotations.

To migrate, replace spring-boot-starter-web with spring-boot-starter-webflux, adapt servlet APIs to WebFilter, ServerWebExchange and WebSession, and compose asynchronous operations with reactive types. Replace blocking calls with non-blocking APIs or move them to worker threads.

For authentication, spring-webflux-pac4j runs pac4j's synchronous security logic on worker threads. We'll reuse the OIDC configuration from the Spring Boot guide and adapt the web integration.

The example uses Spring Boot 3, Java 17 and spring-webflux-pac4j 3.0.2, with the default OIDC authorization code flow.

1) Add the Maven dependencies

Start with a Spring Boot 3 Maven application using the WebFlux starter and the Spring Boot Maven plugin. Add these dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<!-- Spring 6 logging bridge; version managed by Spring Boot -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jcl</artifactId>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>spring-webflux-pac4j</artifactId>
    <version>3.0.2</version>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>

Why declare spring-jcl explicitly? pac4j 6.5.9 excludes it from its transitive spring-core dependency, but Spring 6 still needs it at runtime.

The spring-webflux-pac4j-boot-demo contains a broader application. To adapt it, replace its security configuration with the one below. Place the following classes under the package scanned by your @SpringBootApplication.

2) Configure pac4j and protect the routes

First, let's create the OIDC client and protect the routes under /protected/:

package org.example;

import org.pac4j.core.config.Config;
import org.pac4j.core.matching.matcher.PathMatcher;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;
import org.pac4j.springframework.web.SecurityFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(basePackages = "org.pac4j.springframework.web")
public class SecurityConfig {

    @Bean
    public Config config() {
        final var oidc = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        return new Config("http://localhost:8080/callback", new OidcClient(oidc));
    }

    @Bean
    public SecurityFilter protectedFilter(final Config config) {
        return SecurityFilter.build(config, "OidcClient",
            new PathMatcher().includePath("/protected/"));
    }
}

setAllowUnsignedIdTokens(true) is only for the public demo server: remove it for your own provider. Register http://localhost:8080/callback?client_name=OidcClient as the redirect URI. The provider section of the Spring Boot guide covers Keycloak, Google and Microsoft Entra ID.

Look closely at the path: PathMatcher.includePath uses a prefix match. /protected/ covers /protected/index and deeper paths, but not /protected itself or /protected-other. Add rules for those paths if you need them, and keep callback and logout outside the protected prefix.

The SecurityFilter loads the session and dispatches synchronous pac4j work to Reactor's bounded elastic scheduler. The OIDC HTTP calls remain blocking, but they run away from the Netty event loop. There is no scheduler wrapper to add in the application, this is done automatically.

3) Handle the callback and logout

The @ComponentScan above registers the library's CallbackController and LogoutController. Their default paths are /callback and /logout. The callback receives the provider's response, saves the authenticated profile and sends the user back to the requested page.

Let's set the callback and logout options in src/main/resources/application.properties using the default property options:

pac4j.callback.defaultUrl=/
pac4j.callback.renewSession=true
pac4j.logout.defaultUrl=http://localhost:8080/
pac4j.logout.logoutUrlPattern=^http://localhost:8080/$
pac4j.logout.localLogout=true
pac4j.logout.destroySession=true
pac4j.logout.centralLogout=false

The callback renews the session identifier after authentication to protect against session fixation attacks. Logout removes the local profile and destroys the session. The integration waits for these session operations before continuing.

The logout regex only allows the local home URL in the dynamic url parameter. For production, update both the return URL and this allowlist to your public HTTPS origin.

4) Access the authenticated user

With the session loaded and the user authenticated, we can read the profile in a controller. We'll return plain text so attribute values are not interpreted as HTML:

package org.example;

import org.pac4j.core.profile.ProfileManager;
import org.pac4j.oidc.profile.OidcProfile;
import org.pac4j.springframework.context.SpringWebfluxSessionStore;
import org.pac4j.springframework.context.SpringWebfluxWebContext;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ServerWebExchange;

@RestController
public class ProtectedController {

    @GetMapping(value = "/", produces = MediaType.TEXT_PLAIN_VALUE)
    public String home() {
        return "Visit /protected/index to sign in, or /logout to sign out.";
    }

    @GetMapping(value = "/protected/index", produces = MediaType.TEXT_PLAIN_VALUE)
    public String index(final ServerWebExchange exchange) {
        final var context = new SpringWebfluxWebContext(exchange);
        final var manager = new ProfileManager(context, new SpringWebfluxSessionStore(exchange));
        final var profile = (OidcProfile) manager.getProfile().orElseThrow();
        return "Hello " + profile.getDisplayName() + " (" + profile.getEmail() + ")";
    }
}

The filter has already loaded the session before the protected controller runs. OidcProfile exposes standard claims and provides access to the ID token and access token. Of course, the available attributes depend on the provider and requested scopes.

5) Enable central logout

The endpoint above is only configured for local logout. To also request logout at the provider (= central logout), set these properties:

pac4j.logout.centralLogout=true
pac4j.logout.defaultUrl=http://localhost:8080/

The provider must expose an end_session_endpoint and allow http://localhost:8080/ as a post-logout redirect URI. Use the public HTTPS URL in production.

6) Run the application

mvn spring-boot:run

Open http://localhost:8080/protected/index, sign in and verify that you return to the protected page. Visiting /logout removes the local profile and session.

If the filter never triggers, check the full request path against the /protected/ prefix. If the provider rejects the redirect URI, include ?client_name=OidcClient in its registration. If /callback or /logout returns 404, check that the component scan registers the library's controllers. If Spring reports duplicate mappings, remove any custom controller left over from the earlier example.

7) Switching to SAML or CAS

The protocol configuration from the SAML guide or CAS guide can be reused with this integration. Add the corresponding module, replace the OidcClient and update the client name in the filter. Adapt the profile type and attributes, and register the callback and logout URLs at the provider. SAML also needs a keystore and metadata exchange.

8) Learn more

The documentation for the OIDC client for Java for the complete client configuration.
The spring-webflux-pac4j library and its documentation.
The spring-webflux-pac4j-boot-demo and Spring Security WebFlux demo. The Spring Security guide explains the bridge concept using servlet filters; reactive security requires its own configuration.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Play client application with SAML (using pac4j)

Jérôme LELEU — Fri, 02 Oct 2026 06:50:04 +0000

In a Play application, we want to protect actions while keeping the usual routes and controllers. The play-pac4j library lets us do that with a @Secure annotation, a CallbackController and a LogoutController.

Here, we'll use SAML 2.0. Our application will act as a service provider (SP), delegating login to an IdP such as Microsoft Entra ID, Okta, ADFS, Shibboleth or Keycloak. The same integration also supports the other pac4j authentication mechanisms.

We'll work with play-pac4j v14, designed for Play 3 and Scala 3, and write our application in Java. We'll create a minimal application; the play-pac4j-java-demo provides a more complete reference with OIDC, CAS, OAuth, form and JWT examples. There is also a play-pac4j-scala-demo for Scala developers.

If you've read the Spring Boot SAML guide, you'll recognize the protocol configuration. What changes here is the Guice module, the session store and the way we protect actions.

What you need:

Java 17 or later and sbt
Play 3.0 with Scala 3.9 or later, even for a Java application
the metadata of your identity provider, as a URL or an XML file. This example uses the public pac4j test IdP.

1) Create the sbt project

Create a minimal Play Java project:

mkdir -p play-saml-app/app/controllers play-saml-app/app/modules play-saml-app/conf play-saml-app/project
cd play-saml-app

Create project/build.properties:

sbt.version=1.12.10

Create project/plugins.sbt to enable Play 3:

addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.12")

Create build.sbt at the root, then add the dependencies from step 2:

name := "play-saml-app"
version := "1.0-SNAPSHOT"
scalaVersion := "3.9.0"

lazy val root = (project in file(".")).enablePlugins(PlayJava)

play-pac4j v14 is built with Scala 3.9 LTS, so the Scala version must be set to 3.9 or later, even if your code is only Java: sbt uses it to pick the Scala artifacts of Play and play-pac4j.

Create an empty conf/application.conf. Save the Java classes from the following steps in app/modules and app/controllers, and the routes in conf/routes.

2) Add the sbt dependencies

Add play-pac4j and the SAML module to build.sbt. The %% appends the Scala version to the artifact name: with Scala 3, it resolves play-pac4j_3, the only artifact published by v14.

We'll also need Guice for our module and a cache for the session store in step 4.

resolvers += "Shibboleth releases" at "https://build.shibboleth.net/nexus/content/repositories/releases/"

libraryDependencies += guice
libraryDependencies += caffeine

val playPac4jVersion = "14.0.0"
val pac4jVersion = "6.5.9"

libraryDependencies ++= Seq(
  "org.pac4j" %% "play-pac4j" % playPac4jVersion,
  "org.pac4j" % "pac4j-saml" % pac4jVersion,
  "com.fasterxml.jackson.module" %% "jackson-module-scala" % "2.22.1"
)

OpenSAML is published in the Shibboleth repository, so a specific resolver is required. The Scala Jackson module must match the Jackson 2.22.x databind brought by pac4j 6.5.9; Play's default 2.14.x module cannot run with it. Keep the transitive dependencies required by pac4j SAML.

play-pac4j v14 only supports Play 3 and Scala 3. For Scala 2.13 or Play 2.8 / 2.9, use older versions as displayed in this matrix.

3) Create the service provider keystore

A SAML service provider signs its requests and decrypts the assertions it receives, so it needs its own key pair. Generate a Java keystore with keytool and put it in the conf directory, which is on Play's classpath:

keytool -genkeypair -alias pac4j-demo -keypass pac4j-demo-passwd -storetype JKS -keystore conf/samlKeystore.jks -storepass pac4j-demo-passwd -keyalg RSA -keysize 2048 -validity 3650

See the keystore section of the Spring Boot guide for the details.

4) Write the security module

Play uses Guice, so let's put our configuration in a module. It provides the Config and its SAML client, and binds the session store and the callback and logout controllers:

package modules;

import com.google.inject.AbstractModule;
import com.google.inject.Provides;
import com.google.inject.Singleton;
import org.pac4j.core.config.Config;
import org.pac4j.core.context.session.SessionStore;
import org.pac4j.play.CallbackController;
import org.pac4j.play.LogoutController;
import org.pac4j.play.store.PlayCacheSessionStore;
import org.pac4j.saml.client.SAML2Client;
import org.pac4j.saml.config.SAML2Configuration;
import play.Environment;
import play.cache.SyncCacheApi;

public class SecurityModule extends AbstractModule {

    private final String baseUrl;

    public SecurityModule(final Environment environment, final com.typesafe.config.Config configuration) {
        this.baseUrl = configuration.getString("baseUrl");
    }

    @Override
    protected void configure() {
        // where pac4j keeps the login state and the user profile
        final var sessionStore = new PlayCacheSessionStore(getProvider(SyncCacheApi.class));
        bind(SessionStore.class).toInstance(sessionStore);

        // finishes the login when the identity provider posts the assertion back
        final var callbackController = new CallbackController();
        callbackController.setDefaultUrl("/");
        callbackController.setRenewSession(true);
        bind(CallbackController.class).toInstance(callbackController);

        // logs the user out
        final var logoutController = new LogoutController();
        logoutController.setDefaultUrl("/");
        logoutController.setDestroySession(true);
        bind(LogoutController.class).toInstance(logoutController);
    }

    @Provides @Singleton
    protected SAML2Client provideSaml2Client() {
        // configuration of the authentication via the SAML2 protocol
        final var cfg = new SAML2Configuration();
        cfg.getKeystore().setKeystorePath("resource:samlKeystore.jks");
        cfg.getKeystore().setKeystorePassword("pac4j-demo-passwd");
        cfg.getKeystore().setPrivateKeyPassword("pac4j-demo-passwd");
        cfg.setIdentityProviderMetadataPath("https://www.casserverpac4j.dev/idp/metadata");
        cfg.setServiceProviderEntityId(baseUrl + "/callback?client_name=SAML2Client");
        cfg.setSpLogoutRequestSigned(true);
        cfg.setServiceProviderMetadataPath("file:target/sp-metadata.xml");
        return new SAML2Client(cfg);
    }

    @Provides @Singleton
    protected Config provideConfig(final SAML2Client saml2Client, final SessionStore sessionStore) {
        final var config = new Config(baseUrl + "/callback", saml2Client);
        config.setSessionStoreFactory(p -> sessionStore);
        return config;
    }
}

Then enable the security module and set the base URL in conf/application.conf:

play.modules.enabled += "modules.SecurityModule"
baseUrl = "http://localhost:9000"
# The IdP posts SAML responses from another site.
play.http.session.sameSite = "none"
play.http.session.secure = true

The session cookie must be sent on the IdP's cross-site POST: use SameSite=None with Secure, and HTTPS when deploying beyond localhost. See Play's session settings.

Why do we need a session store? Play has a session cookie, but no server-side session of its own. PlayCacheSessionStore keeps the pac4j data in the cache and puts only a session identifier in the cookie. Without a configured store, pac4j fails at startup with an explicit message. You can also use PlayCookieSessionStore, which encrypts everything into the cookie and needs no cache. Let Play inject it: its encryption key is then derived from play.http.secret.key, which must be stable and shared by all the nodes of your application.

The SAML2Configuration describes our keystore, the IdP metadata, our entity ID and the output path for our SP metadata. These are the same settings explained in the Spring Boot guide.

Finally, new Config(baseUrl + "/callback", saml2Client) sets the callback URL. pac4j appends ?client_name=SAML2Client: the full URL is our Assertion Consumer Service address.

5) Declare the routes and exchange metadata

Add the callback and logout routes to conf/routes, next to the action you want to protect. The @ prefix tells Play to inject the controllers, so the instances bound in the module are used. The identity provider posts the assertion to the callback, so the POST route (on /callback) is the one that matters here:

GET     /                       controllers.Application.index
GET     /protected/index.html    controllers.Application.protectedIndex(request: Request)

GET     /callback                @org.pac4j.play.CallbackController.callback(request: Request)
+ nocsrf
POST    /callback                @org.pac4j.play.CallbackController.callback(request: Request)
GET     /logout                  @org.pac4j.play.LogoutController.logout(request: Request)

The + nocsrf modifier is needed on the callback: the IdP sends a cross-origin POST, which Play's CSRF filter would otherwise reject.

We have configured the IdP metadata, but the IdP also needs ours. When the client initializes, pac4j writes the SP metadata to target/sp-metadata.xml. Register this file, or its entity ID and ACS URL, at the IdP. The metadata exchange section of the Spring Boot guide also covers this step.

6) Protect the action with @secure

Annotate the action, or the whole controller, with @Secure and name the client to use for authentication:

package controllers;

import com.google.inject.Inject;
import java.util.List;
import org.pac4j.core.config.Config;
import org.pac4j.core.profile.UserProfile;
import org.pac4j.play.context.PlayFrameworkParameters;
import org.pac4j.play.java.Secure;
import play.mvc.Controller;
import play.mvc.Http;
import play.mvc.Result;

public class Application extends Controller {

    public Result index() {
        return ok("Visit /protected/index.html to sign in, or /logout to sign out.").as("text/plain");
    }

    @Inject
    private Config config;

    @Secure(clients = "SAML2Client")
    public Result protectedIndex(final Http.Request request) {
        final var profile = getProfiles(request).get(0);
        return ok("Hello " + profile.getId()).as("text/plain");
    }
}

An anonymous request to /protected/index.html is redirected to the identity provider; after login, the callback restores the originally requested URL. The annotation also accepts authorizers, for example authorizers = "admin" for a role check declared with config.addAuthorizer("admin", new RequireAnyRoleAuthorizer("ROLE_ADMIN")), and matchers.

Prefer URL patterns to annotations? The SecurityFilter protects paths by regular expression from application.conf:

play.http.filters = "filters.Filters"

pac4j.security.rules = [
  {"/protected/.*" = {
    clients = "SAML2Client"
  }}
]

with a Filters class that returns securityFilter.asJava() in its list, as the demo does. Both mechanisms can coexist.

7) Access the authenticated user

Add this helper method to the Application controller. It builds the ProfileManager through the factories of the Config:

private List<UserProfile> getProfiles(final Http.Request request) {
    final var parameters = new PlayFrameworkParameters(request);
    final var context = config.getWebContextFactory().newContext(parameters);
    final var sessionStore = config.getSessionStoreFactory().newSessionStore(parameters);
    final var profileManager = config.getProfileManagerFactory().apply(context, sessionStore);
    return profileManager.getProfiles();
}

After a SAML login, we get a SAML2Profile. Its identifier comes from the assertion's NameID. The attributes keep the names supplied by the IdP, often URNs, and can have several values:

final var profile = (SAML2Profile) getProfiles(request).get(0);
profile.getId();                                            // the NameID
profile.getAttribute("urn:oid:0.9.2342.19200300.100.1.3");  // "mail" in many directories
profile.getAttributes();                                    // everything the IdP sent

Map the attributes to readable names with cfg.setMappedAttributes(Map.of("urn:oid:0.9.2342.19200300.100.1.3", "email")). If a value is missing, the attribute release rule for your SP at the IdP is the place to look.

8) Single logout

The /logout route only removes the local login. To log out at the IdP and, through it, at the other applications, we need SAML single logout (SLO). Add a second controller and its route:

package controllers;

import org.pac4j.play.LogoutController;

public class CentralLogoutController extends LogoutController {

    public CentralLogoutController() {
        setDefaultUrl("http://localhost:9000/");
        setLocalLogout(true);
        setCentralLogout(true);
        setDestroySession(true);
        setLogoutUrlPattern("http://localhost:9000/.*");
    }
}

GET     /centralLogout           controllers.CentralLogoutController.logout(request: Request)

pac4j then sends a LogoutRequest to the IdP's single logout endpoint, read from the IdP metadata, and processes the LogoutResponse on the callback URL. The configuration above enables logout-request signing with cfg.setSpLogoutRequestSigned(true). SLO only works if the IdP metadata declares a SingleLogoutService; pick the binding your IdP expects with cfg.setSpLogoutRequestBindingType(...).

9) Run the application

sbt run

Open http://localhost:9000/protected/index.html. You are redirected to the identity provider to sign in, then posted back to the callback URL with the assertion, and the protected page shows your profile.

If something goes wrong:

"Please create a SessionStore and define it in the config" at startup: config.setSessionStoreFactory(...) is missing in the module.
The IdP rejects the request as an unknown service provider: the SP metadata is not registered, or the entity ID at the IdP differs from setServiceProviderEntityId.
403 on the POST callback: the + nocsrf modifier is missing on the route.
"Authentication issue instant is too old": check the clocks and any positive limit configured with cfg.setMaximumAuthenticationLifetime(seconds). In pac4j 6.5.9, the default is 0, which disables this authentication-age check; assertion validity timestamps are still checked.

10) Switching to OIDC or CAS

Add pac4j-oidc or pac4j-cas to build.sbt, provide the corresponding client in the module and pass it to Config. Update @Secure and any URL rules, adapt profile casts and attribute mappings, and register the protocol-specific callback and logout URLs. The same session store and controller structure apply; the SAML keystore is no longer needed. The protocol-specific setup is described in the OIDC guide and the CAS guide.

11) Learn more

The play-pac4j library and its documentation, including the Security trait for Scala controllers and the Twirl template helper.
The play-pac4j-java-demo and play-pac4j-scala-demo applications, with many authentication mechanisms.
The documentation for the SAML 2.0 client for Java for bindings, signature algorithms, attribute converters and IdP-specific notes.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a Jakarta EE client application with OIDC (using pac4j)

Jérôme LELEU — Fri, 02 Oct 2026 06:28:35 +0000

You do not need Spring to add OpenID Connect login to a Java web application. If you already have servlets and a servlet container, we can use those directly.

The jee-pac4j library provides three filters: one to protect your pages (SecurityFilter), one to handle the callback (CallbackFilter) and one for logout (LogoutFilter). We'll configure them to authenticate users with an OIDC provider such as Keycloak, Google, Microsoft Entra ID or Okta.

The OIDC configuration is the same as in the Spring Boot guide. Here, we'll connect it to the servlet container with a configuration class and web.xml; CDI is optional. The jee-pac4j-demo goes further, with SAML, CAS, OAuth and form login as well.

What you need:

Java 17 or later and Maven
a Servlet 6.0 or later container, such as Tomcat 10.1 or 11, or Jetty 12, to match the Servlet API and web.xml below
an OpenID Connect provider where you can register an application, or the public demo server used below.

1) Add the Maven dependencies

Start from a Maven web application with <packaging>war</packaging> and a Java 17 compiler configuration. Two pac4j artifacts are needed: the Jakarta EE integration from jee-pac4j, which provides the filters, and the OpenID Connect module.

<!-- pac4j integration for Jakarta EE (servlet filters) -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>jakartaee-pac4j</artifactId>
    <version>8.0.4</version>
</dependency>
<!-- pac4j support for OpenID Connect -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>
<!-- the servlet API, provided by your container -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

For a legacy javax.servlet application, use the javaee-pac4j artifact instead of jakartaee-pac4j, the corresponding javax.servlet-api dependency, javax.servlet imports and a compatible web.xml descriptor. The pac4j configuration follows the same pattern.

2) Write the security configuration

First, we need a Config to hold our authentication client. How do the filters get it? As usual in the pac4j world, through a ConfigFactory: they instantiate this class at startup and call its build method.

package org.example.security;

import org.pac4j.core.config.Config;
import org.pac4j.core.config.ConfigFactory;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;

public class SecurityConfigFactory implements ConfigFactory {

    @Override
    public Config build(final Object... parameters) {
        // configuration of the authentication via the OpenID Connect protocol
        final var config = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        return new Config("http://localhost:8080/callback", new OidcClient(config));
    }
}

setDiscoveryURI gives pac4j the provider's .well-known/openid-configuration document. From it, pac4j reads the authorization, token, user info and JWKS endpoints. setClientId and setSecret are the credentials obtained when registering the application.

The callback is configured by new Config("http://localhost:8080/callback", ...). pac4j appends ?client_name=OidcClient, where OidcClient is the name of the client (by default, its class name), so register that full URL as the redirect URI at the provider. In production, use the public URL of your application.

By default pac4j uses the authorization code flow, with PKCE when the provider supports it (if needed, you can disable PKCE with setDisablePkce(true) on the OidcConfiguration). setAllowUnsignedIdTokens(true) only exists because the public demo server issues unsigned ID tokens: remove it for a real provider. To register the application at Keycloak, Google or Entra ID, follow the provider section of the Spring Boot guide: the Java configuration is the same, only the wiring below differs.

3) Declare the filters in web.xml

The integration provides three servlet filters. Declare them in WEB-INF/web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">

    <!-- protects /protected/* with the OIDC login -->
    <filter>
        <filter-name>securityFilter</filter-name>
        <filter-class>org.pac4j.jee.filter.SecurityFilter</filter-class>
        <init-param>
            <param-name>configFactory</param-name>
            <param-value>org.example.security.SecurityConfigFactory</param-value>
        </init-param>
        <init-param>
            <param-name>clients</param-name>
            <param-value>OidcClient</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>securityFilter</filter-name>
        <url-pattern>/protected/*</url-pattern>
    </filter-mapping>

    <!-- finishes the login when the provider redirects the user back -->
    <filter>
        <filter-name>callbackFilter</filter-name>
        <filter-class>org.pac4j.jee.filter.CallbackFilter</filter-class>
        <init-param>
            <param-name>defaultUrl</param-name>
            <param-value>/</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>callbackFilter</filter-name>
        <url-pattern>/callback</url-pattern>
    </filter-mapping>

    <!-- logs the user out -->
    <filter>
        <filter-name>logoutFilter</filter-name>
        <filter-class>org.pac4j.jee.filter.LogoutFilter</filter-class>
        <init-param>
            <param-name>defaultUrl</param-name>
            <param-value>/</param-value>
        </init-param>
        <init-param>
            <param-name>destroySession</param-name>
            <param-value>true</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>logoutFilter</filter-name>
        <url-pattern>/logout</url-pattern>
    </filter-mapping>

</web-app>

Let's follow a request to /protected/*. The SecurityFilter checks whether the user is authenticated. If not, it redirects the browser to the provider using the client defined by the clients parameter. You can also configure authorizers, such as isAuthenticated or a role check, and use matchers to exclude paths.

After login, the provider sends the browser to /callback. The CallbackFilter exchanges the authorization code for tokens, validates the ID token and saves the profile in the session. It then redirects to the originally requested page, or to defaultUrl. By default, the session identifier is also renewed to protect against session fixation (the renewSession parameter).

The third filter, LogoutFilter, removes the profile when the user logs out. destroySession also invalidates the HTTP session.

The configFactory parameter builds the configuration once and shares it with the other pac4j filters, so declaring it on one filter is sufficient. You can declare several SecurityFilter instances with different clients or authorizers for different URL patterns.

If you prefer to define things programmatically, you can register the same filters from a ServletContextListener with FilterHelper. Choose this or the XML declarations above, not both: the filter names would clash and the application would fail to start.

package org.example.security;

import jakarta.servlet.ServletContextEvent;
import jakarta.servlet.ServletContextListener;
import jakarta.servlet.annotation.WebListener;
import org.pac4j.jee.filter.CallbackFilter;
import org.pac4j.jee.filter.LogoutFilter;
import org.pac4j.jee.filter.SecurityFilter;
import org.pac4j.jee.util.FilterHelper;

@WebListener
public class SecurityInitializer implements ServletContextListener {

    @Override
    public void contextInitialized(final ServletContextEvent event) {
        final var config = new SecurityConfigFactory().build();
        final var filters = new FilterHelper(event.getServletContext());
        filters.addFilterMapping("securityFilter", new SecurityFilter(config, "OidcClient"), "/protected/*");
        filters.addFilterMapping("callbackFilter", new CallbackFilter(config, "/"), "/callback");
        final var logoutFilter = new LogoutFilter(config, "/");
        logoutFilter.setDestroySession(true);
        filters.addFilterMapping("logoutFilter", logoutFilter, "/logout");
    }
}

4) Access the authenticated user

Once the filters have done their work, our servlet can read the user profile. Wrap the request and response in a JEEContext, then use the ProfileManager:

package org.example.security;

import java.io.IOException;
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.pac4j.core.profile.ProfileManager;
import org.pac4j.jee.context.JEEContext;
import org.pac4j.jee.context.session.JEESessionStore;
import org.pac4j.oidc.profile.OidcProfile;

@WebServlet("/protected/index")
public class ProtectedServlet extends HttpServlet {

    @Override
    protected void doGet(final HttpServletRequest request, final HttpServletResponse response) throws IOException {
        final var context = new JEEContext(request, response);
        final var manager = new ProfileManager(context, new JEESessionStore());
        final var profile = (OidcProfile) manager.getProfile().orElseThrow();

        response.setContentType("text/plain;charset=UTF-8");
        response.getWriter().println("Hello " + profile.getDisplayName() + " (" + profile.getEmail() + ")");
        response.getWriter().println("Visit /logout to sign out.");
    }
}

The OidcProfile exposes the standard claims as getters, provides the mapped profile attributes through getAttributes(), and gives access to the raw tokens with getIdToken() and getAccessToken(). Which claims are present depends on the scopes: the default is openid profile email.

In a CDI application, the integration can produce a ProfileManager, a WebContext and a SessionStore for injection. This requires a CDI-managed Config and injectable HTTP request and response objects; the XML ConfigFactory alone does not supply them. Follow the setup in the jee-pac4j-cdi-demo. Inject the WebContext interface, rather than JEEContext.

5) Logout

The /logout URL mapped above performs the local logout. To also end the session at an identity provider that supports OIDC logout, add centralLogout to the LogoutFilter and replace its existing defaultUrl parameter with an absolute return URL:

<init-param>
    <param-name>centralLogout</param-name>
    <param-value>true</param-value>
</init-param>
<init-param>
    <param-name>defaultUrl</param-name>
    <param-value>http://localhost:8080/</param-value>
</init-param>

pac4j then redirects the browser to the provider's end_session_endpoint, read from the discovery document. Register http://localhost:8080/ as an allowed post-logout redirect URI at the provider. In production, use your application's public HTTPS URL.

If you accept a dynamic return URL through the logout request's url parameter, restrict it with logoutUrlPattern. That pattern validates the requested URL, it does not set the return URL.

6) Run the application

Package the application as a WAR:

mvn clean package

Deploy it to your servlet container at the root context on port 8080, matching the URLs above. With Tomcat, deploy the WAR as ROOT.war. For a different context path or port, update the callback URL, the registered redirect URI and the logout return URL accordingly. Provide a public home page, such as src/main/webapp/index.html, for the default redirect after logout.

The jee-pac4j-demo can also run with mvn jetty:run (as it configures the Jetty Maven plugin in its pom.xml).

Open http://localhost:8080/protected/index. You are redirected to the identity provider to sign in, then returned to the protected page, which greets you by name.

If something goes wrong:

"Invalid redirect URI" at the provider: the registered URI must be the full callback URL, including ?client_name=OidcClient.
The security filter never triggers: check the filter mapping. If an annotated servlet or listener is missing, remove metadata-complete="true" from web.xml or declare that component explicitly: this setting disables annotation scanning.
The callback loops back to the login page: the callback URL in the Config does not match the URL the browser actually uses, typically behind a reverse proxy. Set the public URL.
No profile in the servlet: the SecurityFilter is not mapped on that URL. The profile is only guaranteed on URLs the filter protects.

7) Switching to SAML or CAS

Add the corresponding pac4j-saml or pac4j-cas dependency, replace the OidcClient in the ConfigFactory with a SAML2Client or a CasClient, and update the security filter's clients parameter. Adapt the OidcProfile cast in the servlet to the new profile type, or use the common UserProfile interface. The same filter structure applies, with the callback and logout URLs registered for the chosen protocol. The protocol-specific configuration, the SAML keystore and metadata exchange, and the CAS service registration, are described in the SAML guide and the CAS guide.

8) Learn more

The jee-pac4j library and its documentation for every filter parameter and the JSF and CDI support.
The jee-pac4j-demo web application, with JSP pages and many authentication mechanisms, and the jee-pac4j-cdi-demo with JSF and CDI.
The documentation for the OIDC client for Java for all the OidcConfiguration options.
Authorizers to restrict access by role or attribute once the user is authenticated.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure a JAX-RS client application with OIDC (using pac4j)

Jérôme LELEU — Thu, 01 Oct 2026 11:38:27 +0000

Before adding OIDC to a JAX-RS application, let's distinguish two cases. A browser visits a protected page and needs to be redirected to a login form. An API caller, on the other hand, already has an access token and sends it with the request. The application must handle these differently.

The jax-rs-pac4j library (like pac4j) supports both. It protects resources with pac4j clients through annotations, on Jersey or RESTEasy (JAX-RS is now called Jakarta REST).

We'll start with browser login on Jersey 4, using an indirect client: OidcClient redirects the browser to the identity provider and completes the login on the callback endpoint. Then we'll protect a REST API with bearer tokens. We'll also see what changes for Jersey 3, RESTEasy and Dropwizard, whose pac4j bundle handles registration for us.

We'll create a small application from scratch.

What you need:

Java 17 or later and Maven
a Jakarta REST runtime: Jersey 3 or 4, RESTEasy 6 or 7, standalone on Grizzly or inside a servlet container, or Dropwizard 5
an OpenID Connect provider where you can register an application, or the public demo server used below (https://www.casserverpac4j.dev).

1) Create the Maven project

Create the directories for our application and its resources:

mkdir -p jaxrs-oidc-app/src/main/java/org/example/resources
cd jaxrs-oidc-app

Create a pom.xml at the project root. It targets Java 17, aligns the Jersey dependencies with a BOM and runs org.example.App with the Maven exec plugin:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.example</groupId>
    <artifactId>jaxrs-oidc-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <jersey.version>4.0.2</jersey.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.glassfish.jersey</groupId>
                <artifactId>jersey-bom</artifactId>
                <version>${jersey.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.16.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.6.4</version>
                <configuration>
                    <mainClass>org.example.App</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

For Jersey 3, use jersey.version v*3.1.12* and jersey3-pac4j in step 2. The Java code below is the same.

2) Add the Maven dependencies

Pick the jax-rs-pac4j module matching your runtime, and add the OpenID Connect module. The integration modules have the org.pac4j groupId and their version is 8.1.0 (it is based on pac4j v*6.5.9* as well):

Your runtime	Maven artifact
Jersey 3.1	`jersey3-pac4j`
Jersey 4.0	`jersey4-pac4j`
RESTEasy 6.2	`resteasy6-pac4j`
RESTEasy 7.0	`resteasy7-pac4j`

Add these dependencies inside the <dependencies> element of your pom.xml:

<!-- Jersey runtime and dependency injection -->
<dependency>
    <groupId>org.glassfish.jersey.core</groupId>
    <artifactId>jersey-server</artifactId>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.inject</groupId>
    <artifactId>jersey-hk2</artifactId>
</dependency>
<!-- embedded HTTP server -->
<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-grizzly2-http</artifactId>
</dependency>
<!-- pac4j integration for Jersey 4 -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>jersey4-pac4j</artifactId>
    <version>8.1.0</version>
</dependency>
<!-- pac4j support for OpenID Connect -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>

The pac4j integration declares the runtime in provided scope, so our standalone application supplies it explicitly above. The dependency guide lists the tested combinations.

3) Configure pac4j and register the features

First, build the Config with our OIDC client. We then need to tell JAX-RS three things:

how pac4j should access requests and sessions
how to process its security annotations
how to inject profiles into resource methods.

Create src/main/java/org/example/App.java. It registers the runtime feature, security feature and profile value factory:

package org.example;

import java.net.URI;
import org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpServerFactory;
import org.glassfish.jersey.server.ResourceConfig;
import org.pac4j.core.config.Config;
import org.pac4j.jax.rs.features.Pac4JSecurityFeature;
import org.pac4j.jax.rs.grizzly.features.Pac4JGrizzlyFeature;
import org.pac4j.jax.rs.jersey.features.Pac4JValueFactoryProvider;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;

public class App {

    public static void main(final String[] args) throws InterruptedException {
        final var baseUrl = "http://localhost:8080";

        // configuration of the authentication via the OpenID Connect protocol
        final var oidcConfiguration = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        final var config = new Config(baseUrl + "/callback", new OidcClient(oidcConfiguration));

        final var application = new ResourceConfig()
            .register(new Pac4JGrizzlyFeature(config))          // request context and session on Grizzly
            .register(new Pac4JSecurityFeature())               // @Pac4JSecurity, @Pac4JCallback, @Pac4JLogout
            .register(new Pac4JValueFactoryProvider.Binder())   // @Pac4JProfile, @Pac4JProfileManager
            .packages("org.example.resources");

        final var server = GrizzlyHttpServerFactory.createHttpServer(URI.create(baseUrl + "/"), application);
        Runtime.getRuntime().addShutdownHook(new Thread(server::shutdownNow));
        Thread.currentThread().join();
    }
}

For OIDC, we set the discovery URI, client ID and secret as usual. Remove setAllowUnsignedIdTokens(true) when leaving the public demo server. The provider section of the Spring Boot guide covers registration at Keycloak, Google and Entra ID.

Our new Config(baseUrl + "/callback", ...) supplies the callback URL. Register it at the provider with the ?client_name=OidcClient suffix that pac4j appends.

The runtime choice matters for sessions. Here, Pac4JGrizzlyFeature uses Grizzly. Inside Tomcat, Jetty or WildFly, use Pac4JServletFeature(config) to access the container's HttpSession. Browser login needs a session to keep state between the redirect and the callback.

The profile injection is runtime-specific too: Pac4JValueFactoryProvider.Binder is for Jersey. With RESTEasy and CDI, register Pac4JSecurityFeature as a class and use Pac4JProfileInjectorFactory instead, following the RESTEasy configuration guide.

On Dropwizard, none of this registration code is needed: see the Dropwizard section below, then continue with step 4.

4) Declare the callback and logout endpoints

Create src/main/java/org/example/resources/AuthResource.java. The callback and logout look like ordinary resource methods with annotations. Their bodies never run, though: the pac4j filter processes the request and responds before JAX-RS reaches them.

package org.example.resources;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.pac4j.jax.rs.annotations.Pac4JCallback;
import org.pac4j.jax.rs.annotations.Pac4JLogout;

@Path("/")
public class AuthResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String home() {
        return "Visit /protected/index to sign in, or /logout to sign out.";
    }

    @GET
    @Path("callback")
    @Pac4JCallback(defaultUrl = "/", renewSession = true)
    public void callback() {
        // handled by pac4j
    }

    @POST
    @Path("callback")
    @Pac4JCallback(defaultUrl = "/", renewSession = true)
    public void callbackPost() {
        // handled by pac4j, for the form_post response mode
    }

    @GET
    @Path("logout")
    @Pac4JLogout(destroySession = true, defaultUrl = "/")
    public void logout() {
        // handled by pac4j
    }
}

Keep renewSession = true: pac4j rotates the session identifier after login to protect against session fixation. Version 8.1.0 fixes session renewal and preservation of session attributes on Grizzly, so there is no need to disable it for this setup.

5) Protect a resource and read the profile

Create src/main/java/org/example/resources/ProtectedResource.java. Annotate the resource method, or the whole class, with @Pac4JSecurity and name the client. Add a @Pac4JProfile parameter to receive the authenticated user:

package org.example.resources;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.pac4j.jax.rs.annotations.Pac4JProfile;
import org.pac4j.jax.rs.annotations.Pac4JSecurity;
import org.pac4j.oidc.profile.OidcProfile;

@Path("/protected")
public class ProtectedResource {

    @GET
    @Path("/index")
    @Produces(MediaType.TEXT_PLAIN)
    @Pac4JSecurity(clients = "OidcClient")
    public String index(@Pac4JProfile OidcProfile profile) {
        return "Hello " + profile.getDisplayName() + " (" + profile.getEmail() + ")"
            + "\nVisit /logout to sign out.";
    }
}

When a user who has not signed in opens /protected/index, pac4j redirects their browser to the identity provider. After login, the provider returns the browser to /callback. pac4j validates the login, saves the user profile in the session and redirects the browser back to /protected/index.

pac4j then calls index(...) and supplies the authenticated user's OidcProfile through the @Pac4JProfile parameter. The two annotations have different jobs: @Pac4JSecurity protects the endpoint, while @Pac4JProfile gives the method access to the user's information.

You can extend @Pac4JSecurity with authorizers to check permissions, such as a required role, or with matchers to decide when security applies. These refer to authorizers and matchers configured in your Config.

There are other ways to access the profile, depending on what the method needs:

@Pac4JProfile CommonProfile profile gives access to fields shared across authentication mechanisms, such as the user ID.
@Pac4JProfile Optional<CommonProfile> profile can be empty when the endpoint's security configuration allows anonymous access. Using Optional alone does not allow anonymous access.
@Pac4JProfileManager ProfileManager profileManager gives access to the profile manager, for example to retrieve all profiles associated with the request.

6) Protect a REST API with the access token

This step is an alternative to browser login. Let's take the second case: an API caller that already has an access token. For this setup, add org.pac4j:pac4j-http:6.5.9 for HeaderClient and a JSON provider such as jersey-media-json-jackson, matching your Jersey version. Also add this BOM inside <dependencyManagement><dependencies> to align the Jackson dependencies of Jersey and pac4j:

<dependency>
    <groupId>com.fasterxml.jackson</groupId>
    <artifactId>jackson-bom</artifactId>
    <version>2.22.1</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Replace the stateful registration from step 3 with the configuration below.

Here we use a direct client, HeaderClient: the caller sends its access token in the Authorization: Bearer header, and authentication happens on that request. There is no browser redirect and no local session. HeaderClient checks the token at the OIDC provider's user info endpoint, using the OIDC client's profile creator.

In App.java, keep the OIDC configuration and server startup, replace the Config and ResourceConfig declarations, and add these imports:

import org.pac4j.http.client.direct.HeaderClient;
import org.pac4j.jax.rs.features.Pac4JJaxRsFeature;
import org.pac4j.jax.rs.pac4j.NoOpSessionStoreFactory;

final var oidcClient = new OidcClient(oidcConfiguration);
oidcClient.setCallbackUrl("notused");
oidcClient.init();
final var bearerClient = new HeaderClient("Authorization", "Bearer ", oidcClient.getProfileCreator());

final var config = new Config(bearerClient);
config.setSessionStoreFactory(NoOpSessionStoreFactory.INSTANCE);

final var application = new ResourceConfig()
    .register(new Pac4JJaxRsFeature(config))    // no session at all
    .register(new Pac4JSecurityFeature())
    .register(new Pac4JValueFactoryProvider.Binder())
    .packages("org.example.api");

Create src/main/java/org/example/api/MeResource.java:

package org.example.api;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import java.util.LinkedHashMap;
import java.util.Map;
import org.pac4j.core.profile.CommonProfile;
import org.pac4j.jax.rs.annotations.Pac4JProfile;
import org.pac4j.jax.rs.annotations.Pac4JSecurity;

@Path("/api/me")
public class MeResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Pac4JSecurity(clients = "HeaderClient")
    public Map<String, Object> me(@Pac4JProfile CommonProfile profile) {
        final Map<String, Object> user = new LinkedHashMap<>();
        user.put("id", profile.getId());
        user.put("email", profile.getEmail());
        return user;
    }
}

curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:8080/api/me

Restart the application, then set ACCESS_TOKEN to a real access token issued by your provider before running the command above. This checks credentials on every request. The provider must expose UserInfo and accept the access token there. We have identified the user, but we still need to enforce our API's audience, scopes and application-specific permissions. Configure these checks for your provider and API.

If the provider issues JWT access tokens, you can also validate them locally. Replace the profile creator with a JwtAuthenticator from pac4j-jwt, configured with the provider's JWKS and the expected issuer, audience and token lifetime checks.

An application can offer both browser login and bearer authentication. Keep a stateful configuration for the browser routes and a separate stateless one for the API: an API request must supply valid bearer credentials, even when the caller also has a browser session.

7) Logout

The /logout endpoint of step 4 performs the local logout. To also end the session at the identity provider, enable the central logout in the annotation:

@GET
@Path("logout")
@Pac4JLogout(destroySession = true, centralLogout = true, defaultUrl = "http://localhost:8080/")
public void logout() {
}

For a provider supporting OIDC logout, pac4j redirects to its end_session_endpoint. Register http://localhost:8080/ as an allowed post-logout redirect URI. If accepting a dynamic url parameter, also restrict it with logoutUrlPattern.

The stateless API has no local session to destroy. Stopping token use on the client does not revoke the token; it remains valid until expiry or provider-side revocation.

8) Run the application

mvn compile exec:java

For the browser configuration from steps 3–5, open http://localhost:8080/protected/index. You are redirected to the identity provider to sign in, then returned to the resource, which greets you by name.

If something goes wrong:

"Invalid redirect URI" at the provider: the registered URI must be the full callback URL, including ?client_name=OidcClient.
The login loops or the state is lost: an indirect client such as OidcClient needs a session. Use Pac4JGrizzlyFeature or Pac4JServletFeature, not Pac4JJaxRsFeature, for the browser login.
@Pac4JProfile is not injected: the value factory is missing. Register Pac4JValueFactoryProvider.Binder on Jersey, or Pac4JProfileInjectorFactory on RESTEasy.
401 on the API with a valid token: the provider rejects the token at the user info endpoint. Check that the token was issued for this provider and carries the openid scope.

9) Using Dropwizard

What if your application uses Dropwizard? It runs Jersey inside Jetty, so the resource annotations above still apply. The dropwizard-pac4j bundle takes care of step 3: it builds Config from a factory named in YAML, registers the servlet and security features and the profile value factory, and enables Jetty sessions.

Create a separate dropwizard-oidc-app project with src/main/java/org/example/resources and src/main/java/org/example/security. Reuse the Maven skeleton from step 1, change its artifact ID to dropwizard-oidc-app and the exec plugin's main class to org.example.MyApplication.

Replace the Jersey BOM with io.dropwizard:dropwizard-bom:5.0.2 (also with type set to pom and scope to import), and replace the dependencies from step 2 with these:

<dependency>
    <groupId>io.dropwizard</groupId>
    <artifactId>dropwizard-core</artifactId>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>dropwizard-pac4j</artifactId>
    <version>8.1.0</version>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>

Dropwizard 5 uses Jersey 3. The dropwizard-pac4j 8.1.0 bundle already brings jersey3-pac4j 8.1.0; keep the Jersey 4 dependencies out of this project. It also uses pac4j 6.5.9 and jakartaee-pac4j 8.0.3.

Create src/main/java/org/example/security/SecurityConfigFactory.java and move the OIDC configuration of step 3 into this ConfigFactory. Use the externally reachable callback URL, including any configured application context path.

By default, the bundle considers all JAX-RS requests as AJAX requests: an indirect client like OidcClient then returns a 401 error instead of redirecting to the identity provider, which suits REST APIs. For browser login on JAX-RS resources, restore the default pac4j behavior with a DefaultAjaxRequestResolver, as described in the bundle README:

package org.example.security;

import org.pac4j.core.config.Config;
import org.pac4j.core.config.ConfigFactory;
import org.pac4j.core.http.ajax.DefaultAjaxRequestResolver;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;

public class SecurityConfigFactory implements ConfigFactory {

    @Override
    public Config build(final Object... parameters) {
        final var oidcConfiguration = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        final var config = new Config("http://localhost:8080/callback", new OidcClient(oidcConfiguration));
        // redirect the browser to the identity provider instead of returning a 401 error
        config.getClients().setAjaxRequestResolver(new DefaultAjaxRequestResolver());
        return config;
    }
}

Create config.yml at the project root and reference the factory under a pac4j section:

pac4j:
  configFactory: org.example.security.SecurityConfigFactory

Expose that section in your configuration class as a Pac4jFactory property, annotated with @Valid so that its content is validated, and add the bundle to the application:

package org.example;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.dropwizard.core.Configuration;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import org.pac4j.dropwizard.Pac4jFactory;

public class MyConfiguration extends Configuration {

    @NotNull
    @Valid
    @JsonProperty("pac4j")
    private Pac4jFactory pac4jFactory = new Pac4jFactory();

    public Pac4jFactory getPac4jFactory() {
        return pac4jFactory;
    }
}

package org.example;

import io.dropwizard.core.Application;
import io.dropwizard.core.setup.Bootstrap;
import io.dropwizard.core.setup.Environment;
import org.example.resources.AuthResource;
import org.example.resources.ProtectedResource;
import org.pac4j.dropwizard.Pac4jBundle;
import org.pac4j.dropwizard.Pac4jFactory;

public class MyApplication extends Application<MyConfiguration> {

    public static void main(final String[] args) throws Exception {
        new MyApplication().run(args);
    }

    private final Pac4jBundle<MyConfiguration> pac4j = new Pac4jBundle<>() {
        @Override
        public Pac4jFactory getPac4jFactory(final MyConfiguration configuration) {
            return configuration.getPac4jFactory();
        }
    };

    @Override
    public void initialize(final Bootstrap<MyConfiguration> bootstrap) {
        bootstrap.addBundle(pac4j);
    }

    @Override
    public void run(final MyConfiguration configuration, final Environment environment) {
        environment.jersey().register(AuthResource.class);
        environment.jersey().register(ProtectedResource.class);
    }
}

Save the configuration and application classes as src/main/java/org/example/MyConfiguration.java and src/main/java/org/example/MyApplication.java. Copy AuthResource and ProtectedResource from steps 4 and 5 into the resource directory. Their callbacks already enable session renewal; Dropwizard uses servlet sessions.

Start this application with its YAML configuration:

mvn compile exec:java -Dexec.args="server config.yml"

Open http://localhost:8080/protected/index to follow the same browser login flow.

You can also declare a global filter (globalFilters, which accepts only one entry) in the pac4j section to protect the whole API, or servlet-level filters for the non-Jersey parts of the application. The bundle README describes these options.

For the bearer-token API from step 6, set sessionEnabled: false, build the HeaderClient in the factory and, as in step 6, disable the session store with config.setSessionStoreFactory(NoOpSessionStoreFactory.INSTANCE). The dropwizard-pac4j-demo protects Dropwizard views with form, HTTP Basic and CAS logins.

10) Switching to SAML or CAS

For browser login, add pac4j-saml or pac4j-cas, replace the OidcClient and update @Pac4JSecurity. Adapt the injected profile type or use CommonProfile, and register the protocol-specific callback and logout settings. SAML also needs a keystore and metadata exchange. The bearer-token example is a separate authentication mechanism and is not converted by changing this browser client. The protocol-specific setup is described in the SAML guide and the CAS guide.

11) Learn more

The jax-rs-pac4j library and its documentation, including the Servlet, Grizzly, CDI and sessionless setups.
The jax-rs-pac4j-demo application, and the release post on Jersey 4 and RESTEasy 7 support.
The dropwizard-pac4j bundle and the dropwizard-pac4j-demo application.
The documentation for the OIDC client for Java for the complete client configuration.
Direct OIDC authentication and JWT validation for the access token case.

Discover more pac4j frameworks and more authentication mechanisms…

How to secure an Undertow client application with OIDC (using pac4j)

Jérôme LELEU — Thu, 01 Oct 2026 04:59:37 +0000

You can connect an Undertow application to an OpenID Connect provider. You just need to use the undertow-pac4j library to add three handlers to your PathHandler: SecurityHandler, CallbackHandler and LogoutHandler.

The OIDC provider handles the login page and authenticates the user. It can be Keycloak, Google, Microsoft Entra ID, Okta or another OIDC server, or the public pac4j demo provider we'll use below.

This example uses undertow-pac4j v6.1.0, Undertow v2.4 and Java 17. The OIDC client is configured just as in the Spring Boot OIDC guide.

For a more complete example, see the undertow-pac4j-demo.

1) Create the Maven project

Start from an empty Maven project with Java 17 or later:

mkdir -p undertow-oidc-app/src/main/java/org/example
cd undertow-oidc-app

Create a pom.xml at the project root. The compiler targets Java 17, and the exec plugin will run the App class we write in section 4:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.example</groupId>
    <artifactId>undertow-oidc-app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Add the dependencies from section 2 here. -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.16.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.6.4</version>
                <configuration>
                    <mainClass>org.example.App</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2) Add the Maven dependencies

Inside the <dependencies> element, add Undertow, the Undertow integration for the handlers and the OpenID Connect module for the client:

<dependency>
    <groupId>io.undertow</groupId>
    <artifactId>undertow-core</artifactId>
    <version>2.4.3.Final</version>
</dependency>
<!-- pac4j integration for Undertow -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>undertow-pac4j</artifactId>
    <version>6.1.0</version>
</dependency>
<!-- pac4j support for OpenID Connect -->
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.5.9</version>
</dependency>

undertow-pac4j v6.1 targets Undertow v2.4 and pac4j v6. It declares undertow-core in the provided scope, so your application must bring its own Undertow dependency.

3) Write the security configuration

Create src/main/java/org/example/SecurityConfigFactory.java. It builds the pac4j Config with the OIDC client:

package org.example;

import org.pac4j.core.config.Config;
import org.pac4j.core.config.ConfigFactory;
import org.pac4j.oidc.client.OidcClient;
import org.pac4j.oidc.config.OidcConfiguration;

public class SecurityConfigFactory implements ConfigFactory {

    @Override
    public Config build(final Object... parameters) {
        // configuration of the authentication via the OpenID Connect protocol
        final var oidcConfiguration = new OidcConfiguration()
            .setDiscoveryURI("https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration")
            .setClientId("myclient")
            .setSecret("mysecret")
            .setAllowUnsignedIdTokens(true);
        return new Config("http://localhost:8080/callback", new OidcClient(oidcConfiguration));
    }
}

There is nothing specific to Undertow in this configuration and this is the beauty of pac4j!

pac4j reads the provider metadata (endpoints, algorithms, etc.) from the discovery URI. The callback URL, with ?client_name=OidcClient appended by pac4j, is the redirect URI to register at your provider.

One demo setting should be removed when using your own provider: setAllowUnsignedIdTokens(true). It is only here because the public demo server issues unsigned ID tokens.

4) Wire the handlers and start the server

Create src/main/java/org/example/App.java. We register the pac4j handlers on their paths, then wrap the whole PathHandler with the session handler. Add the protectedPage helper from section 5 inside this class before compiling:

package org.example;

import io.undertow.Undertow;
import io.undertow.server.HttpServerExchange;
import io.undertow.server.handlers.PathHandler;
import io.undertow.server.session.InMemorySessionManager;
import io.undertow.server.session.SessionAttachmentHandler;
import io.undertow.server.session.SessionCookieConfig;
import io.undertow.util.Headers;
import org.pac4j.oidc.profile.OidcProfile;
import org.pac4j.undertow.account.Pac4jAccount;
import org.pac4j.undertow.handler.CallbackHandler;
import org.pac4j.undertow.handler.LogoutHandler;
import org.pac4j.undertow.handler.SecurityHandler;

public class App {

    public static void main(final String[] args) {
        final var config = new SecurityConfigFactory().build();
        final var path = new PathHandler();

        // the OIDC login protects /protected
        path.addExactPath("/protected", SecurityHandler.build(App::protectedPage, config, "OidcClient"));

        // the provider redirects the user here after login
        path.addExactPath("/callback", CallbackHandler.build(config, "/", true, null, null));

        // logs the user out
        final var logout = new LogoutHandler(config, "/");
        logout.setDestroySession(true);
        path.addExactPath("/logout", logout);

        path.addExactPath("/", exchange -> {
            exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, "text/html; charset=UTF-8");
            exchange.getResponseSender().send("<a href='/protected'>Protected area</a>");
        });

        // the Undertow session, around all the routes
        final var sessionHandler = new SessionAttachmentHandler(path,
            new InMemorySessionManager("sessions"), new SessionCookieConfig().setHttpOnly(true));

        Undertow.builder()
            .addHttpListener(8080, "localhost")
            .setHandler(sessionHandler)
            .build()
            .start();
    }
}

Here are the main points in this setup:

Session handling: SessionAttachmentHandler must wrap the protected, callback and logout paths: it attaches the Undertow SessionManager and SessionConfig to each request, and pac4j's UndertowSessionStore reads and writes the session through them. Here the session cookie is JSESSIONID, marked HttpOnly.
Default components: undertow-pac4j provides a FrameworkAdapterImpl that pac4j discovers on the classpath. Its applyDefaultSettingsIfUndefined method supplies the Undertow-specific web context, session store and profile manager factories, along with the HTTP action adapter, as defaults in the Config. Explicitly configured components are preserved.
Protected paths: SecurityHandler.build wraps our handler: it redirects anonymous users to the OIDC provider, and for authenticated users, it calls our handler. The other build variants also accept authorizers and matchers. For example, SecurityHandler.build(App::protectedPage, config, "OidcClient", "admin") can refer to a role check declared with config.addAuthorizer("admin", new RequireAnyRoleAuthorizer("ROLE_ADMIN")).
Login callback: CallbackHandler receives the authorization code, exchanges it for an access token and an ID token, validates the ID token, saves the profile and redirects to the requested page or the default URL ("/"). The third argument (true) renews the session identifier to protect against session fixation. The same path also accepts the POST requests of the OIDC form_post response mode, while the default code flow returns by GET.
Local logout: LogoutHandler removes the profile. With setDestroySession(true), it invalidates the Undertow session as well.
IO threads: SecurityHandler.build and CallbackHandler.build return handlers already wrapped in a BlockingHandler and a form parser: the pac4j logic and our protected handler run on a worker thread, in blocking mode, and POST parameters are available. LogoutHandler dispatches itself to a worker thread. So no extra BlockingHandler wrapper is needed.
Error pages: the 401, 403 and error responses have an empty body. To display your own pages, add a default response listener in front of the PathHandler, like the ErrorHandler of the undertow-pac4j-demo.
Multiple instances: InMemorySessionManager keeps the sessions in the memory of one server. Behind a load balancer, use sticky sessions or a distributed SessionManager.

5) Access the authenticated user

Add this helper method to App. It reads the profile from the Undertow security context and returns plain text:

private static void protectedPage(final HttpServerExchange exchange) {
    final var account = (Pac4jAccount) exchange.getSecurityContext().getAuthenticatedAccount();
    final var profile = (OidcProfile) account.getProfile();
    exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, "text/plain; charset=UTF-8");
    exchange.getResponseSender().send("Hello " + profile.getDisplayName() + " (" + profile.getEmail() + ")"
        + "\nVisit /logout to sign out.");
}

When pac4j loads the profiles, it registers a Pac4jAccount as the authenticated account of the request. Its principal is the user identifier, its roles are those of the profiles, and getProfiles() returns all the profiles.

The OidcProfile gives us getters for the standard claims, plus getIdTokenString() for the raw ID token and getAccessToken() for the access token. The claims depend on the requested scopes, which default to openid profile email (but this is configurable).

You can also directly use the pac4j API: new UndertowProfileManager(new UndertowWebContext(exchange), new UndertowSessionStore(exchange)).getProfiles() returns the same list of profiles, even on a path that is not protected.

6) Logout

The user can be logged out of the Undertow application and still have a session at the identity provider. Our /logout path handles the first part, the local logout. For central logout as well, add a second handler inside App.main, before starting the server:

final var centralLogout = new LogoutHandler(config, "http://localhost:8080/", "http://localhost:8080/.*");
centralLogout.setLocalLogout(true);
centralLogout.setDestroySession(true);
centralLogout.setCentralLogout(true);
path.addExactPath("/centralLogout", centralLogout);

For a provider supporting OIDC logout, pac4j clears the local profile and redirects to its end_session_endpoint. Register http://localhost:8080/ as an allowed post-logout redirect URI. The logout URL pattern (third constructor argument) validates an optional dynamic url parameter (the second argument is the default return URL).

7) Run the application

The main method returns once the server is started: the Undertow worker threads keep the application running. From the directory containing pom.xml, run:

mvn clean compile exec:java

Open http://localhost:8080/protected. You are redirected to the identity provider to sign in, then returned to the protected page, which greets you by name.

If the provider rejects the redirect URI, register the full callback URL including ?client_name=OidcClient.

If the request fails with "No Undertow session manager or session config found in the exchange", the SessionAttachmentHandler is missing: it must wrap the protected path and the callback.

8) Switching to SAML or CAS

Add the pac4j-saml or pac4j-cas module, replace the OidcClient in Config and update the clients passed to SecurityHandler.build. Adapt the OidcProfile type and provider attributes, and register callback/logout URLs for the selected protocol. The callback already parses the form body of SAML POST responses and CAS logout requests. SAML also needs a keystore and metadata exchange.

The protocol-specific setup is described in the SAML documentation and the CAS documentation.

9) Learn more

The undertow-pac4j library and its documentation, and the undertow-pac4j-demo application.
The documentation for the OIDC client for Java for client configuration and provider options.

Discover more pac4j frameworks and more authentication mechanisms…

DEV Community: Jérôme LELEU

OpenID Federation with pac4j and CAS

1) Setup a CAS server as the OP

2) Setup the pac4j application as the RP

a) Dependencies

b) Properties

c) SecurityConfig class

d) Application class

3) Setup a CAS server as the trust anchor

4) Final test

OpenID Federation with pac4j, Connect2id and CAS

1) Setup a CAS server as a trust anchor

2) Define its subordinates

3) Declare CAS as the trust anchor

4) Test again

How to secure a Java client application with OpenID Connect (using Spring Boot)

1) Create the Maven project

2) Add the Maven dependencies

3) Configure OpenID Connect (OIDC) authentication

4) Register the application at your identity provider

5) Access the authenticated user

6) Logout

7) Run the application

8) Learn more

How to secure a Java client application with SAML (using Spring Boot)

1) Create the Maven project

2) Add the Maven dependencies

3) Create the service provider keystore

4) Configure SAML 2.0 authentication

5) Exchange metadata with your identity provider

6) Access the authenticated user

7) Single logout

8) Run the application

9) Learn more

How to secure a Java client application with CAS (using Spring Boot)

1) Create the Maven project

2) Add the Maven dependencies

3) Configure CAS authentication

4) Register the service on the CAS server

5) Access the authenticated user

6) Logout

7) Run the application

8) Beyond the login page

9) Learn more

How to secure a Spring Security client application with OIDC (using pac4j)

1) Create the Maven project

2) Add the Maven dependencies

3) Configure pac4j

4) Put the pac4j filters in the Spring Security chain

5) Access the authenticated user

6) Logout

7) Run the application

8) Switching to SAML or CAS

9) Learn more

How to secure a Shiro client application with CAS (using pac4j)

1) Create the Maven project

2) Add the Maven dependencies

3) Configure pac4j in shiro.ini

4) Map the CAS user to Shiro roles

5) Access the authenticated user

6) Logout

7) Run the application

8) Switching to OIDC or SAML

9) Learn more

How to secure a Spring WebFlux client application with OIDC (using pac4j)

1) Add the Maven dependencies

2) Configure pac4j and protect the routes

3) Handle the callback and logout

4) Access the authenticated user

5) Enable central logout

6) Run the application

7) Switching to SAML or CAS

8) Learn more

How to secure a Play client application with SAML (using pac4j)

1) Create the sbt project

2) Add the sbt dependencies

3) Create the service provider keystore

4) Write the security module

5) Declare the routes and exchange metadata

6) Protect the action with @secure

c) `SecurityConfig` class

d) `Application` class