DEV Community: Jérôme LELEU

JWKS explained: what every developer should know

Jérôme LELEU — Tue, 16 Jun 2026 13:32:03 +0000

When it comes to security, certificates are used everywhere since the early days of the web.

While storing them in PEM/DER format has always been complicated, things have become much easier with the modern JWKS (J for JSON) format.

And you're probably already using JWKS without knowing it, every time you validate a JWT from Google, GitHub, or your identity provider.

1) A word about cryptography

We can use symmetric cryptography based on a secret.

As this secret must be shared by both parties, this is not generally a very convenient solution.

Or we can use asymmetric cryptography based on key pairs.

In that case, there are two keys: a public one and a private one.

Two mechanisms are available:

the signature ensures that the sender is confirmed (the sender uses its private key to sign the message and the receiver can confirm that using the public key of the sender)
the encryption protects the data itself (the sender uses the public key of the receiver to encrypt the data and only the receiver can read the data thanks to its private key).

Both mechanisms are complementary and serve different purposes.

2) In the past: SAML and XML

Back when SAML was the main protocol and XML very popular, you generated certificates using the openssl tool:

openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes -keyout private.key -out public.crt -subj "/CN=localhost"

It created two files:

private.key:

-----BEGIN PRIVATE KEY-----
MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQDdx8R3Y1Eyh69R
O8iACpe6MWJAUgMadWPt1VW2XGkrkvSBn9hY866VBt8wkH1uFmOAvvjwx55Tvu1K
...TRUNCATED...
ySD6rqvGLLxGkZoUGyuHt9D7B/FaBAMvjjgOSMYbHxYj0ncQioaVSpcUZIpTrHRo
jA1drmXT/LHPGeQgp/CJQ3Zf7qqavA==
-----END PRIVATE KEY-----

public.crt:

-----BEGIN CERTIFICATE-----
MIIFLjCCAxagAwIBAgIUOtBi9hdWAqh1sL8U7wS3ttXgg40wDQYJKoZIhvcNAQEL
BQAwITELMAkGA1UEBhMCRlIxEjAQBgNVBAMMCWxvY2FsaG9zdDAeFw0yNjA1MTgx
...TRUNCATED...
po1DwOR88q6xAws/qM1+PxigbFRh4E8zUeVVF0vED+VxeCG0AwKDYawPjw5/9qfJ
qC8ewt6SVZmmdtMg2MK8Tdmzv0W+ciiYO21CF45Pa6YZVA==
-----END CERTIFICATE-----

These raw contents were hard to manipulate.

You could even generate a keystore (for Java) using the keytool command line.

3) Modern ecosystem: OIDC and JSON

Today, the OIDC protocol has somehow supplanted the SAML protocol and JSON has truly replaced the XML format.

Everyone knows the JSON format:

{
    "key1": "value1",
    "key2": "value2"
}

Most people also know that a JSON Web Token (aka JWT) is a signed and/or encrypted JSON message.

It comes as a string in three parts separated by dots, each part being base64 encoded: part1.part2.part3.

part1 is the header, part2 is the JSON itself (it can be encrypted) and part3 is the signature (it may not be signed).

Let's take an example from jwt.io:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.
KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

We have three parts which decode to:

a header: { "alg": "HS256", "typ": "JWT" }
a body: { "sub": "1234567890", "name": "John Doe", "admin": true, "iat": 1516239022 }
a signature.

And the encryption/signing of the JWTs is ensured by the public/private keys.

4) JWK and JWKS

Given the popularity of JSON, it was high time to find a better format than the PEM(/DER) format for certificates and what better format than JSON?

So, JWK (for JSON Web Key) is the format to define a key:

the kty property defines the type RSA, EC, ...
the use property indicates if the key is used for signature ("sig") or encryption ("enc")
the alg property defines the algorithm (it can be omitted)
the kid property defines the name for the key and this is a very cool feature to distinguish between keys
the specific n and e properties for RSA, the specific x and y properties for Elliptic Curve.

For example, you can have this JWK:

{
    "kty" : "RSA",
    "e" : "AQAB",
    "use" : "sig",
    "kid" : "keyname",
    "n" : "2moVQ...2aq7Q"
}

And a JWKS, the S stands for Set (not for the plural), is a set of JWKs = keys listed in an array defined by the keys property.

For example, the JWKS of our previous JWK is:

{
  "keys" : [ {
    "kty" : "RSA",
    "e" : "AQAB",
    "use" : "sig",
    "kid" : "keyname",
    "n" : "2moVQ...2aq7Q"
  } ]
}

This is super easy and much clearer than the PEM format given that you now have an identifier for your key, the use of your key, an algorithm, etc.

Instead of a block certificate, you have several separate pieces of information.

5) Easier but...

Despite the more pleasant format, there is no magic, there are pitfalls to avoid (like with regular certificates).

Plain certificates were painful and no one would take them lightly. Yet, this nicer JWKS format of the keys must not make you forget that you deal with security.

Trap #1

So you still need to take care of the rotation/revocation of the keys in your JWKS: add a JWK, remove an old one, ... things don't happen by themselves (hopefully).

Trap #2

While JWKS exposed on the internet contain public keys, private/internal JWKS can contain private keys.

For example, this is the JWKS of the private key for our previous public JWK:

{
   "keys":[
      {
         "p":"-4uskk...sMm98",
         "kty":"RSA",
         "q":"3kg3S...FgErM",
         "d":"UT_QS...l1LYw",
         "e":"AQAB",
         "use":"sig",
         "kid":"keyname",
         "qi":"Lp-0T...lo4afg",
         "dp":"xcakA...18JHE",
         "dq":"JByJV...XmqiP8",
         "n":"2moVQ...2aq7Q"
      }
   ]
}

You should notice that there are more information for private keys and especially you always find the d property in a private key.

This is really important as you must always be able to distinguish between a public key and a private key.

Because the golden rule remains: you must never publicly disclose a private key.

Trap #3

There is even a new trap with the alg property: this is absolutely not a security constraint, it is only a recommendation.

So you must not be confused by this value and only trust what you have really configured and applied in your code.

This is exactly like for the JWT header where the alg key is only informative: trusting it could expose you to the algorithm confusion attack.

You must always rely on what you actually defined and used for encryption/signature. You must never rely on what is provided to you from the outside.

JWKS is a modern format to store/manage keys you will really enjoy,
but you must never forget the good practices regardless!

See how pac4j deals with JWKS in the OIDC private_key_jwt authentication method or in the OpenID Federation...

More OpenID Federation with pac4j and Connect2id

Jérôme LELEU — Mon, 18 May 2026 10:06:26 +0000

I strongly recommend that you read the first article about the OpenID Federation protocol.

This new article dives deeper into the OpenID Federation support in pac4j and Connect2id.

You should download and use the latest versions of both software (at least version 6.5.1 for pac4j).

1) Let's log in (again)

a) Calling the login page

As we have previously seen, the first login generates several logs on both sides (client = RP = pac4j + server = OP = connect2id).

Several HTTP calls are required to check the JWKS and the entity statements and establish the trust chains.

This could be a performance issue if these HTTP calls were made for each login attempt, though on the second try, the logs are much less verbose before displaying the login page:

The pac4j logs:

DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Request Object claim names: [iss, aud, iat, exp, jti, scope, response_type,
 redirect_uri, state, code_challenge_method, client_id, code_challenge, response_mode]
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Authz parameter names: [response_type, request, client_id, scope]
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Authentication request URL: http://127.0.0.1:8080/c2id-login
 ?response_type=code&request=eyJr...hULhwg&client_id=http%3A%2F%2Flocalhost%3A8081&scope=openid%20profile%20email

The Connect2id logs:

INFO AUTHZ-SESSION - [OP2101] Created new auth session: sid=FKEttMylh3MVBAtu59F7CXx5m4BTGXZ2_DKowRh_8eg
 client_id=http://localhost:8081 scope=[openid, profile, email]

Hopefully, trust chains have been cached depending on the expiration time and the whole plumbing has not been triggered a second time.

b) After typing in the login and password

After a successful login, we get the following logs:

On the Connect2id side:

INFO SESSION-STORE - [SS0201] Added new session: sub=alice ctx=web sid_key=MhNnqmimFgizG5ALmnp-tg
INFO AUTHZ-SESSION - [OP2103] Created new consent session: sid=FKEttMylh3MVBAtu59F7CXx5m4BTGXZ2_DKowRh_8eg subject=alice
 client_id=http://localhost:8081
INFO AUTHZ-SESSION - [OP2108] Created authZ response: subject=alice client_id=http://localhost:8081 response_type=[code]
INFO TOKEN - HTTP POST request: ip=127.0.0.1 path=/c2id/token
INFO TOKEN - [OP6204] Authenticated: client_id=http://localhost:8081 method=private_key_jwt client_auth_id=NgAiEAADRhMrDiZp
INFO AUTHZ-STORE - [AS0280] Issued access token: sub=alice act=null client_id=http://localhost:8081 scope=[openid]
INFO TOKEN - [OP6225] Success response: client_id=http://localhost:8081 grant=code tokens=[access,id]
INFO USERINFO - HTTP GET request: ip=127.0.0.1 path=/c2id/userinfo
INFO AUTHZ-STORE - [AS0213] Inspected valid SELF_CONTAINED Bearer access token: sub=alice act=null client_id
 =http://localhost:8081 iat=1775213922: eyJraWQiOiJQUlJ6Iiwid...
INFO USERINFO - [OP7307] Received valid UserInfo request: sub=alice claims=null ia_id=aac191d2-dcc5-4837-8545-692e204bcc07

This is fairly obvious:

A POST call is performed on the /c2id/token endpoint using the private_key_jwt client authentication method (this is what we have configured on the pac4j side)
A GET call is performed on the /c2id/userinfo endpoint using the access_token as bearer (= HTTP header).

This is the regular OIDC login process even if the flow has started in a federation way.

On the pac4j side:

DEBUG o.p.o.c.e.OidcCredentialsExtractor       : Authentication response successful
DEBUG o.p.o.c.e.OidcCredentialsExtractor       : Request state: d508c0f0ad/response state: d508c0f0ad
DEBUG org.pac4j.oidc.client.OidcClient         : clean authentication attempt from session
DEBUG o.p.o.c.authenticator.OidcAuthenticator  : Token response: status=200, content={"access_token":"eyJ...bng","token_type":"Bearer","expires_in":600}
DEBUG o.p.o.c.authenticator.OidcAuthenticator  : Token response successful
DEBUG org.pac4j.oidc.client.OidcClient         : clean authentication attempt from session (second call)
DEBUG org.pac4j.oidc.client.OidcClient         : Credentials validation took: 32 ms
DEBUG org.pac4j.oidc.client.OidcClient         : credentials : OidcCredentials(code=sjtox4...NQw, accessToken=...
DEBUG org.pac4j.oidc.profile.OidcProfile       : adding => key: access_token / value: eyJh...MDB9 / class java.lang.String
DEBUG org.pac4j.oidc.profile.OidcProfile       : adding => key: expiration / value: 1775214522541 / class java.lang.Long
DEBUG org.pac4j.oidc.profile.OidcProfile       : adding => key: id_token / value: eyJ...bng / class java.lang.String
DEBUG o.p.oidc.profile.creator.TokenValidator  : Trying IDToken validator, issuer: http://127.0.0.1:8080/c2id, type: null, JWS:
DEBUG o.p.oidc.profile.creator.TokenValidator  : Validated: {"iss":"http:\/\/127.0.0.1:8080\/c2id","sub":"alice",
 "aud":"http:\/\/localhost:8081","exp":1775214522,"iat":1775213922,"amr":["pwd"]}
DEBUG o.p.o.p.creator.OidcProfileCreator       : User info response: status=200, content={"sub":"alice","groups":["admin","audit"]}
DEBUG o.p.oidc.profile.OidcProfileDefinition   : converted to => key: sub / value: alice / class java.lang.String
DEBUG org.pac4j.oidc.profile.OidcProfile       : adding => key: sub / value: alice / class java.lang.String
...
DEBUG org.pac4j.oidc.profile.OidcProfile       : adding => key: token_expiration_advance / value: 0 / class java.lang.Integer
DEBUG org.pac4j.oidc.client.OidcClient         : profile: Optional[OidcProfile(super=AbstractJwtProfile(super=CommonProfile(
 super=BasicUserProfile(logger=Logger[org.pac4j.oidc.profile.OidcProfile], id=alice, attributes={access_token=eyJ...MDB9,
 token_expiration_advance=0, sub=alice, aud=[http://localhost:8081], amr=[pwd], id_token=eyJr...Hsbng,
 iss=http://127.0.0.1:8080/c2id, groups=[admin, audit], expiration=1775214522541, exp=Fri Apr 03 13:08:42 CEST 2026,

The logs are straightforward on the pac4j side as well: we see the successful authentication, the token and the userprofile calls.

c) After the login process

Even though we’re not doing anything, new logs keep appearing for the Connect2id server:

INFO AUTHZ-STORE - [AS0228] Revoking multiple authzs: client_id=http://localhost:8081
INFO CLIENT-REG - [OP5184] Deleted client: client_id=http://localhost:8081 num_revoked_authz=1
INFO FED-REG - [OP8041] Reaped 1 expired federation clients

These logs are related to the fact that we have performed an automatic registration. The logs indicate that the temporarily created client is deleted.

Indeed, as Connect2id does not know the pac4j client, it has temporarily registered this client and after some time, the registered client is cleaned.

While this is a very convenient mechanism, it can impact server performance.

Therefore, it could be useful to consider explicitly and permanently registering our OIDC pac4j client.

2) Let's log in with explicit registration

a) The client identifier

And this is a feature supported by the OpenID Federation protocol:

the explicit registration of the OIDC client.

This must be of course supported by the OIDC server and this is the case of the Connect2id server.

pac4j supports both modes depending on the OIDC server, so the configuration must only be updated on the Connect2id server.

Stop the server (tomcat/bin/shutdown.sh), edit the tomcat/webapps/c2id/WEB-INF/oidcProvider.properties file:

op.federation.clientRegistrationTypes=explicit

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

On the pac4j side:

DEBUG o.p.o.m.r.FederationClientRegister       : Registration endpoint exists and only explicit registration by OP (and RP)
 -> performing explicit registration
 INFO .f.e.DefaultEntityConfigurationGenerator : Generating entity configuration for: http://localhost:8081
DEBUG o.p.o.m.r.FederationClientRegister       : Received response registration: eyJraW...mkaMxZQ
 WARN o.p.o.m.r.FederationClientRegister       : /!\ ================================================
 WARN o.p.o.m.r.FederationClientRegister       : /!\ Explicit registration of the client 'http://localhost:8081' returns
  id: [t4j746kwjax6s]. This information won't be repeated. You MUST add this value to your configuration before the next
   application startup!
 WARN o.p.o.m.r.FederationClientRegister       : /!\ ================================================

On the Connect2id side:

INFO FED-REG - [OP8014] Registered entity http://localhost:8081 as explicit client with client_id=xkqolxvshcjv6 exp=1783005293
INFO FED-REG - [OP8019] Explicit registration response statement for entity http://localhost:8081: {sub=http://localhost:8081,
 aud=[http://localhost:8081], metadata={openid_relying_party={client_registration_types=[explicit, automatic],
 token_endpoint_auth_signing_alg=RS256, grant_types=[authorization_code], jwks={keys=[{kty=RSA, e=AQAB, use=sig, kid=...

The explicit registration is duly taken into account by Connect2id which generates a specific client_id for the OIDC client, returns it to pac4j to be displayed in its logs.

Let's follow the instruction given in the logs and add this client_id in the pac4j configuration:

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

    // the new clientId!
    config.setClientId("xkqolxvshcjv6");

    final var rpJwks = config.getRpJwks();
    rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
    rpJwks.setKid("defaultjwks0426");
    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://127.0.0.1:8080/c2id");
    final var trust = new OidcTrustAnchorProperties();
    trust.setIssuer("http://localhost:8081/trustanchor");
    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");

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

Here is the complete configuration for reference (and not only the added client_id).

We restart the Spring Boot application and try a new login process.

This time, no registration happens and Connect2id directly recognizes the provided client_id:

INFO AUTHZ-SESSION - [OP2101] Created new auth session: sid=reJ...58w client_id=xkqolxvshcjv6 scope=[openid, profile, email]

b) The client secret

At this point in the article, you may wonder why we only have a client_id and no client_secret.

In fact, we don't need a secret as we use the private_key_jwt client authentication method: the credential is the private key, not the secret.

As this pac4j configuration is revealed in its entity statement, the Connect2id server is aware of that setting and, accordingly, decides to only return a client_id for this OIDC client.

Let's go further and replace this configuration in pac4j:

config.setClientAuthenticationMethod(ClientAuthenticationMethod.PRIVATE_KEY_JWT);
final var privateKeyJwtConfig = new PrivateKeyJwtClientAuthnMethodConfig(rpJwks);
config.setPrivateKeyJWTClientAuthnMethodConfig(privateKeyJwtConfig);

by:

config.setClientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC);

to use the client_secret_basic authentication (and not the private_key_jwt).

We also remove the previous client_id:

config.setClientId("xkqolxvshcjv6");

and completely change the contact name:

federation.setContactName("New RP test");

Restart the Spring Boot application and try to log in.

This time, we call the Connect2id server with explicit registration and no configured client id/secret and a client_secret_basic authentication method.

And we get a new error from pac4j:

org.pac4j.oidc.exceptions.OidcException: Client secret export file is required

This seems definitely a weird one, but it's not! Let me explain: the received client_id is output in the logs, though it would not be safe to output the client_secret in the logs as well.

So the received client_secret is planned to be saved on the disk, on a file defined by the secretExportFile property.

Let's define it in the configuration:

federation.setSecretExportFile("./mysecret.tmp");

and try again. It works!

The generated client_id and client_secret have been added on-the-fly to the OIDC configuration and have been used to perform the client_secret_basic authentication method.

The client_id is in the logs: Explicit registration of the client 'http://localhost:8081' returns id: [wzcyln5hdtmck].

The client_secret is in the defined file: The received secret has been saved into the file: ./mysecret.tmp. Its value is: U9UaF99rUopAXnWqXqkWBj_RsOZXfM1Efs67N4KweHo.

These seem to be the right settings as the login process has worked, but we'd like to check that on the Connect2id side.

Let's seek in the Connect2id configuration file oidcProvider.properties for the property: op.reg.apiAccessTokenSHA256. I find:

# Evaluation note: Use token value ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
op.reg.apiAccessTokenSHA256=cca68b8b82bcf0b96cb826199429e50cd95a042f8e8891d1ac56ab135d096633

Let's try to use the Connect2id API to list the existing clients with this key:

curl -X GET http://127.0.0.1:8080/c2id/clients -H "Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6"

We get two clients:

[
    {
        "client_registration_types":[
            "explicit",
            "automatic"
        ],
        "grant_types":[
            "authorization_code"
        ],
        "jwks":{
            "keys":[
                {
                    "kty":"RSA",
                    "e":"AQAB",
                    "use":"sig",
                    "kid":"defaultjwks0426",
                    "n":"2moV...aq7Q"
                }
            ]
        },
        "subject_type":"public",
        "application_type":"web",
        "registration_client_uri":"http:\/\/127.0.0.1:8080\/c2id\/clients\/wzcyln5hdtmck",
        "redirect_uris":[
            "http:\/\/localhost:8081\/callback?client_name=OidcClient"
        ],
        "registration_access_token":"0QKFCVfBe5PqVFwgjEaRousXHKEa9My0-IMMMCTPB20.YSxpLHI",
        "token_endpoint_auth_method":"client_secret_basic",
        "client_id":"wzcyln5hdtmck",
        "client_secret_expires_at":0,
        "request_object_signing_alg":"RS256",
        "client_id_issued_at":1775836027,
        "client_secret":"U9UaF99rUopAXnWqXqkWBj_RsOZXfM1Efs67N4KweHo",
        "client_name":"New RP test",
        "contacts":[
            "jerome@casinthecloud.com"
        ],
        "response_types":[
            "code"
        ],
        "id_token_signed_response_alg":"RS256"
    },
    {
        "token_endpoint_auth_signing_alg":"RS256",
        "grant_types":[
            "authorization_code"
        ],
        "jwks":{
            "keys":[
                {
                    "kty":"RSA",
                    "e":"AQAB",
                    "use":"sig",
                    "kid":"defaultjwks0426",
                    "n":"2moV...aq7Q"
                }
            ]
        },
        "subject_type":"public",
        "application_type":"web",
        "registration_client_uri":"http:\/\/127.0.0.1:8080\/c2id\/clients\/xkqolxvshcjv6",
        "redirect_uris":[
            "http:\/\/localhost:8081\/callback?client_name=OidcClient"
        ],
        "registration_access_token":"7ilSWZGsH4wOyehETCNJQz0My8NO-6efLiV1ED2HcN0.YSxpLHI",
        "token_endpoint_auth_method":"private_key_jwt",
        "client_id":"xkqolxvshcjv6",
        "request_object_signing_alg":"RS256",
        "client_id_issued_at":1775747499,
        "client_name":"C2ID Test RP (Localhost)",
        "contacts":[
            "jerome@casinthecloud.com"
        ],
        "response_types":[
            "code"
        ],
        "id_token_signed_response_alg":"RS256"
    }
]

The second one has only the right client_id, no client_secret and is defined with private_key_jwt.

The first one has the right client_id and client_secret and is defined with client_secret_basic.

Notice the appropriate client_name property as well.

The Connect2id configuration perfectly matches what was received by pac4j (not that I had any doubts 😉)

The magic of the federation continues:

The pac4j RP and the Connect2id OP only know and rely on the trust anchor, they don't know each other.

But nonetheless the RP has been able to definitely register itself on the OP!

OpenID Federation with pac4j and Connect2id

Jérôme LELEU — Thu, 02 Apr 2026 07:24:34 +0000

Since version 6.4.0, pac4j supports the OpenID (Connect) Federation specification.

The OpenID Connect (in short, OIDC) support in pac4j (pac4j-oidc module) is strongly based on the Nimbus libraries:

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>oauth2-oidc-sdk</artifactId>
</dependency>
<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>nimbus-jose-jwt</artifactId>
</dependency>

These are great Open Source libraries developed by the Connect2id team:

And as they also developed an OIDC server, let's test the pac4j OpenID Federation support with it!

1) Components

In this article, we will focus on the setup of this particular configuration more than entering into the details and options of each component.

We need 3 components:

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

a) RP = pac4j

In the pac4j ecosystem, Spring Boot is the most popular web stack so let's use the spring-webmvc-pac4j implementation in action 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.

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.2</version>
</dependency>
<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-oidc</artifactId>
    <version>6.4.0</version>
</dependency>

b) OP = Connect2id

To make things easy, let's use the "Quick start" of the Connect2id server: https://connect2id.com/products/server/docs/quick-start

Download the ZIP and unzip it. You will get a connect2id-server-19.8 directory or something similar.

In that directory, you can:

run the server: tomcat/bin/startup.sh
stop the server: tomcat/bin/shutdown.sh
change its configuration in the tomcat/webapps/c2id/WEB-INF/oidcProvider.properties file
check the logs in the tomcat/logs/c2id-server.log file.

c) TA is simulated

The trust anchor is a core component in our installation: it plays the role of the certificate authority.

We could use some specific existing software, but to make things easier, we will simulate it without entering into the details.

2) Configuration

Now that we have our 3 components, let's configure them to work together via the OpenID Federation protocol.

So far, when using the OpenID Connect protocol, you always need to define your client (client_id + credentials + redirect_uri) at the server level to be able to perform the authentication process.

The OpenID Federation introduces the idea of trust and chain of trust between components to allow authenticating without registering upfront/at all.

And each component (entry) in the federation exposes its metadata on the new .well-known/openid-federation endpoint. A dedicated JWKS ensures security, similar to an X.509 certificate but without its complexity/difficulty.

a) pac4j

As the Connect2id server runs by default on port 8080, we'll move our pac4j application to port 8081 via this configuration in the application.properties file:

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

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();

        final var rpJwks = config.getRpJwks();
        rpJwks.setJwksPath("file:./metadata/rpjwks.jwks");
        rpJwks.setKid("defaultjwks0426");
        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://127.0.0.1:8080/c2id");
        final var trust = new OidcTrustAnchorProperties();
        trust.setIssuer("http://localhost:8081/trustanchor");
        trust.setJwksPath("classpath:trustanchor.jwks");
        federation.getTrustAnchors().add(trust);

        federation.getJwks().setJwksPath("file:./metadata/oidcfede.jwks");
        federation.getJwks().setKid("mykeyoidcfede26");
        federation.setContactName("C2ID Test RP (Localhost)");
        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/**");
    }
}

This new configuration needs explanations!

Notice that we don't have any dicsoveryURI, nor any clientId or any credentials!

We need two distinct and separate JWKS for our setup here: one for the federation (to sign our entity statement) and one for the private_key_jwt client authentication (when calling the token endpoint). You should never use the same JWKS for both!

The source code:

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

defines the JWKS used for the private_key_jwt client authentication. This will create a key named defaultjwks0426 and save it as a JWKS in the metadata/rpjwks.jwks file.

We use the Request Object signing configuration as the federation requires more security:

config.setRequestObjectSigningAlgorithm(JWSAlgorithm.RS256);

The JWKS used for signing here is the previous one defined in the rpJwks property.

In federation, you must define your trust anchor(s) (the root authority). So we do that with:

final var trust = new OidcTrustAnchorProperties();
trust.setIssuer("http://localhost:8081/trustanchor");
trust.setJwksPath("classpath:trustanchor.jwks");
federation.getTrustAnchors().add(trust);

It assumes the simulated TA is available at the http://localhost:8081/trustanchor URL with a JWKS also in the classpath (this is in the entity statement, but we rely on the one downloaded in the classpath).

The target OP (= the server we want to use for authentication) is of course the Connect2id and is defined by: federation.setTargetOp("http://127.0.0.1:8080/c2id").

Finally, the entity identifier of our RP pac4j client is http://localhost:8081 (its own base URL) thanks to federation.setEntityId("http://localhost:8081").

As we don't have a clientId, the entityId is used to identify the RP.

It also means we must expose a dedicated OpenID federation endpoint (in the Application class):

@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();
}

b) Connect2id

The Connect2Id server is available on the http://127.0.0.1:8080/c2id URL.

To enable federation, in the tomcat/webapps/c2id/WEB-INF/oidcProvider.properties file, you need to change:

### 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:8081/trustanchor

# 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:8081/trustanchor
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

# The enabled methods for authenticating OpenID Federation 1.0 automatic client
# registration requests at the OAuth 2.0 authorisation endpoint.
#
# Supported methods:
#
#     * request_object
#
op.federation.autoClientAuthMethods.ar=request_object

The parameters are quite obvious: op.federation.enable=true to enable the federation.

The trust anchor is defined twice:

op.federation.trustAnchors.1=http://localhost:8081/trustanchor
op.federation.authorityHints.1=http://localhost:8081/trustanchor

And we use the automatic registration mode (the simplest way): op.federation.clientRegistrationTypes=automatic.

Stop and start again the Connect2id server. You should see this welcome page on http://127.0.0.1:8080/c2id:

Meaning the federation is properly enabled.

c) Simulated TA

For the simulated trust anchor, let's not enter into the details to limit the size of this article.

We expose a few endpoints to simulate its behavior and the contract it must respect (in the Application class):

@GetMapping(value = "/trustanchor/.well-known/openid-federation", produces = DefaultEntityConfigurationGenerator.CONTENT_TYPE)
@ResponseBody
public String trustAnchorWellKnown() throws Exception {
    return "eyJraWQiOiJ0YS1rZX...vBabK4L897BynKoyihoUHj4Q";
}

@GetMapping(value = "/trustanchor/fetch", produces = DefaultEntityConfigurationGenerator.CONTENT_TYPE)
@ResponseBody
public String trustAnchorFetch(final HttpServletRequest request) throws Exception {
    final var sub = request.getParameter("sub");
    if (sub.contains("127.0.0.1")) { // OP
        return "eyJraWQiOiJ0YS1rZX...ldEVZd49QyZRnENUCP4hOMCWiQ";
    } else { // RP
        return "eyJraWQiOiJ0YS1rZX...n94DBmi3m158dbEO2ZWyM_9YdWtxjerAl1Zh-bgzA6H17tRGlk-oYd-7g";
    }
}

And add the trustanchor.jwks to the src/main/resources directory.

This simulated TA depends on your Connect2id server keys so you won't be able to reproduce it locally until we move to a real trust anchor. We will do this in a future article.

3) Let's log in

Now we run our pac4j Spring Boot RP and our Connect2id OP server.

Let's add more logs on the pac4j side via: logging.level.org.pac4j.oidc=DEBUG (in the application.properties file).

Open the http://localhost:8081/ URL in your browser and click on the Protected area link:

Ta-da! It works: the Connect2id login page is displayed and we can log in with the default alice/ secret user/password:

The pac4j logs:

DEBUG o.p.o.m.OidcFederationOpMetadataResolver : Blocking load of the provider metadata via federation
 INFO o.p.o.m.chain.FederationChainResolver    : Resolving federation chain for RP: http://localhost:8081
DEBUG o.p.o.m.chain.FederationChainResolver    : Loaded 1 trust anchor(s)
DEBUG o.p.o.m.chain.FederationChainResolver    : OP target issuer: http://127.0.0.1:8080/c2id
DEBUG o.p.o.m.chain.FederationChainResolver    : OP chain: com.nimbusds.openid.connect.sdk.federation.trust.TrustChain@14c16574
DEBUG o.p.o.m.chain.FederationChainResolver    : rawMetadataJson: {"request_parameter_supported":true,"pushed_authorization_...
DEBUG o.p.o.m.chain.FederationChainResolver    : combinedPolicy: {}
DEBUG o.p.o.m.chain.FederationChainResolver    : resolvedJson: {"request_parameter_supported":true,"pushed_authorization_...
DEBUG o.p.o.m.r.FederationClientRegister       : ClientID is not defined
DEBUG o.p.o.m.r.FederationClientRegister       : Automatic registration by OP (supported by RP) ->
setting clientId as entityId for further operation
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Algorithm used for request object signing: RS256
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Request Object claim names: [iss, aud, iat, exp, jti, scope,
response_type, redirect_uri, state, code_challenge_method, client_id, code_challenge, response_mode]
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Authz parameter names: [response_type, request, client_id, scope]
DEBUG o.p.o.r.OidcRedirectionActionBuilder     : Authentication request URL: http://127.0.0.1:8080/c2id-login?response_type=code
&request=eyJraW...KLjkrVw&client_id=http%3A%2F%2Flocalhost%3A8081&scope=openid%20profile%20email
 INFO .f.e.DefaultEntityConfigurationGenerator : Generating entity configuration for: http://localhost:8081

The Connect2id logs:

INFO FED-REG - [OP8025] Resolved 1 trust chains (automatic client):
INFO FED-REG - [OP8026] Trust chain [1] anchor (automatic client): http://localhost:8081/trustanchor
INFO FED-REG - [OP8026] Trust chain [1][1] entity (automatic client): http://localhost:8081
INFO FED-REG - [OP8026] Trust chain [1][1] statement (automatic client): {"sub":"http:\/\/localhost:8081","metadata":{"openid_relying_party":...
INFO FED-REG - [OP8026] Trust chain [1][2] entity (automatic client): http://localhost:8081
INFO FED-REG - [OP8026] Trust chain [1][2] statement (automatic client): {"sub":"http:\/\/localhost:8081","metadata":{"openid_relying_party":...
INFO FED-REG - [OP8013] Selected trust chain for entity http://localhost:8081 (automatic client) with anchor
http://localhost:8081/trustanchor and exp 2026-06-25T20:52:26.000+0200
INFO FED-REG - [OP8018] Received automatic registration request from http://localhost:8081 with authorities [http://localhost:8081/trustanchor]
INFO FED-REG - [OP8051] Effective metadata RP policy for entity http://localhost:8081: {}
INFO FED-REG - [OP8014] Registered entity http://localhost:8081 as automatic client with client_id=http://localhost:8081 exp=1782413546
INFO AUTHZ-SESSION - [OP2101] Created new auth session: sid=0r61vms5vYcodERRslQNMT0QqFRQsjw2Jr33YL4de5s client_id=http://localhost:8081 scope=...

Without going too deep in the logs, we can see that both sides are checking federation endpoints and entity statements to establish the trust chain.

So here is the magic of federation:

The pac4j RP and the Connect2id OP only know and rely on the trust anchor, they don't know each other.
But nonetheless the RP can perform the authentication process on the OP!