Fork me on GitHub

SAML (v1.9)

pac4j allows you to login with any SAML identity provider using the SAML v2.0 protocol.

It has been tested with various SAML 2 providers: Okta,, CAS SAML2 IdP, …

1) Dependency

You need to use the following module: pac4j-saml.

Example (Maven dependency):


2) Basic configuration

The SAML2Client must be used to login with a SAML 2 identity provider.

First, optionally you need to generate a keystore for all signature and encryption operations:

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

Alternatively, you can also let pac4j create the keystore for you. If the keystore resource path does not exist, pac4j will attempt to generate a keystore and produce the relevant key pairs inside it.

Then, you must define a SAML2ClientConfiguration:

SAML2ClientConfiguration cfg = new SAML2ClientConfiguration("resource:samlKeystore.jks", 
                                                            "pac4j-demo-passwd", "pac4j-demo-passwd", 

The first parameter (keystorePath) should point to your keystore:

With pac4j-saml v1.9.2, the resource: and classpath: prefixes are not usable for the keystorePath definition in CAS and Vertx. Use a relative or absolute path without any prefix

The second parameter (keystorePassword) is the value of the -storepass option for the keystore generation while the third parameter (privateKeyPassword) is the value of the -keypass option.

The fourth parameter (identityProviderMetadataPath) should point to your IdP metadata, assuming you can use the same syntax than for the keystore.

Finally, you need to declare the SAML2Client based on the previous configuration:

Saml2Client client = new Saml2Client(cfg);

After a successful authentication, a SAML2Profile is returned.

3) Additional configuration:

Since pac4j v1.9.3, you can define the binding type via the setDestinationBindingType method:

// or cfg.setDestinationBindingType(SAMLConstants.SAML2_POST_BINDING_URI);

Once you have an authenticated web session on the Identity Provider, usually it won’t prompt you again to enter your credentials and it will automatically generate a new assertion for you. By default, the SAML client will accept assertions based on a previous authentication for one hour. If you want to change this behaviour, set the `maximumAuthenticationLifetime parameter:

// lifetime in seconds

By default, the entity ID of your application (the Service Provider) will be equals to the callback url. This can lead to problems with some IDP because of the query string not being accepted (like ADFS v2.0). So you can force your own entity ID with the serviceProviderEntityId parameter:

// custom SP entity ID

To configure the supported algorithms and digest methods for the initial authentication request, specify what is supported via the configuration object:


By default, assertions must be signed, but this may be disabled using:


You may also force XML-signing of the authentication requests when using the redirect binding:


The final result will be determined based on the IdP metadata and the configuration above. The IdP metadata will always be chosen in favor of the pac4j configuration, so if you need to purely rely on pac4j, you need to modify the metadata.

You can generate the SP metadata in two ways:

4) ADFS subtilities

You must follow these rules to successfully authenticate using Microsoft ADFS 2.0 / 3.0.

a) Entity ID

You must always specify an explicit Entity ID that does not contain any question mark. By default, pac4j uses the same Entity ID as the AssertionConsumerService location, which contains the client’s name as a parameter after a question mark. Unfortunately ADFS does not work well with such IDs and starts an infinite redirection loop when A SAML message with such a message arrives.

This property is supported since pac4j v1.6.0. Don’t forget to change your metadata accordingly!

b) Maximum authentication time

pac4j has the default maximum time set to 1 hour while ADFS has it set to 8 hours. Therefore it can happen that ADFS sends an assertion which is still valid on ADFS side but evaluated as invalid on pac4j side.

You can see the following error message: org.pac4j.saml.exceptions.SAMLException: Authentication issue instant is too old or in the future

There are two possibilities how to make the values equal:

c) Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

You must install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files into your JRE/JDK running pac4j. If you don’t do it, you may encounter errors like this:

ERROR [org.opensaml.xml.encryption.Decrypter] - <Error decrypting the encrypted data element> Illegal key size
ERROR [org.opensaml.xml.encryption.Decrypter] - <Failed to decrypt EncryptedData using either EncryptedData KeyInfoCredentialResolver or EncryptedKeyResolver + EncryptedKey KeyInfoCredentialResolver>
ERROR [org.opensaml.saml2.encryption.Decrypter] - <SAML Decrypter encountered an error decrypting element content>

Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files can be downloaded from Oracle’s Java Download site.