The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →PicketLink can provide SAML 2.0 browser single sign-on for a legacy WildFly service provider (SP): an identity provider (IdP) authenticates the user and sends a SAML assertion, and the SP consumes it to establish a local identity and roles. A legacy SP configuration uses a SAML login module, a web security-domain reference, an Undertow servlet extension, and WEB-INF/picketlink.xml. This is a legacy integration path: the WildFly project says the PicketLink subsystem has been removed from WildFly and points users to the Keycloak SAML Elytron adapter and migration guide. Confirm your exact WildFly or JBoss EAP version before implementing the configuration below.
How PicketLink SAML SSO is organized
A SAML federation is a circle of trust: it has one identity provider and can have many service providers. The IdP authenticates users and issues assertions; each SP validates and consumes assertions to establish the application’s local identity and authorization. PicketLink’s reference documentation describes trust and SAML-specific configuration at the federation level, rather than as a separate trust relationship for every SP.
For the application team, the important distinction is that SAML authentication and application authorization are related but separate. The assertion supplies user information, while the SP’s configured handlers process it and map role information for the application. PicketLink documentation also describes IdP-side identity stores such as databases, LDAP, and properties files; those are IdP account sources, not replacements for configuring the SP.
What a legacy WildFly SP needs
PicketLink’s getting-started example uses four pieces on the SP side. The exact server configuration mechanism can vary by WildFly or JBoss EAP release, so treat the snippets as legacy examples and verify that the target runtime still supports the PicketLink classes and subsystem.
- A security domain with the PicketLink
SAML2LoginModule, markedrequired. - A web application reference in
WEB-INF/jboss-web.xmlthat points to that security domain. - An Undertow servlet extension registration at
WEB-INF/classes/META-INF/services/io.undertow.servlet.ServletExtension, containing the SP servlet extension class name. - A PicketLink configuration file at
WEB-INF/picketlink.xml, with the IdP URL, SP URL, SAML binding, and handler chain.
Configure the legacy security domain
The example security-domain definition is:
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>Here, sp is the domain name that the web application must reference. The example shows a login module and flag; it does not establish that this legacy subsystem syntax is valid for every WildFly or EAP release.
Reference the domain and register Undertow integration
In WEB-INF/jboss-web.xml, set the application’s security-domain reference to sp, matching the name configured on the server. For Undertow, create the service-provider registration file at WEB-INF/classes/META-INF/services/io.undertow.servlet.ServletExtension and put this fully qualified class name in it:
Rank #2
org.picketlink.identity.federation.bindings.wildfly.sp.SPServletExtensionThe registration file is a service-provider declaration, not an XML file. Preserve its exact path and class name for a legacy deployment that supports this integration.
Set the IdP, SP, binding, and handlers
A representative PicketLink SP configuration from the official example is:
<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
<PicketLinkSP BindingType="POST">
<IdentityURL>https://idp.example/</IdentityURL>
<ServiceURL>https://app.example/</ServiceURL>
</PicketLinkSP>
<Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
<Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
</Handlers>
</PicketLink>Replace the example URLs with the deployment’s actual IdP and SP endpoints, aligned with the IdP’s SAML configuration or metadata. The sample establishes the configuration shape; it does not provide deployment-specific endpoint paths or certificate settings.
Choose a browser flow and SAML binding
The Red Hat JBoss EAP SAML v2 guide documents SP-initiated browser SSO and shows POST in its normal example. It also documents REDIRECT by changing the PicketLink setting to BindingType="REDIRECT", while labeling its REDIRECT example as not recommended. Confirm what the IdP supports and test behavior through the deployment’s proxies before choosing.
Rank #4
| Choice | What it means | Practical decision |
|---|---|---|
| POST binding | Documented in the Red Hat guide’s normal example. | Use when it is supported by both sides and suits the deployment. |
| REDIRECT binding | Selected with BindingType="REDIRECT"; the Red Hat example labels it not recommended. |
Use only after checking IdP compatibility, message-size constraints, proxy behavior, and operational observability. |
| SP-initiated flow | The documented browser flow begins at the service provider. | Follow the documented path when users enter through the application. |
| IdP-initiated flow | Not established as the flow shown in the cited Red Hat example. | Verify support and expected behavior with the exact IdP and legacy integration rather than assuming it works from the SP example. |
Configure signatures and encryption carefully
For signed assertions, the Red Hat guide shows SupportsSignatures="true" and the signature-generation and signature-validation handlers as appropriate. Encryption uses SAML2EncryptionHandler and a KeyProvider backed by a Java keystore. The guide’s handler chain processes requests and responses in configured order, so order is part of the security configuration, not cosmetic XML formatting.
Red Hat specifically warns against configuring signature generation and encryption in the same handler chain because messages could be signed multiple times. Do not combine them by copying handler lists without considering their documented order and behavior.
Best Value
Keystore configuration involves values such as KeyStoreURL, KeyStorePass, SigningKeyPass, SigningKeyAlias, and validating aliases. The guide’s values are examples, not production secrets. Protect passwords and key material with the deployment’s secret-management process, and plan certificate rollover and validation-alias updates as part of operating the federation.
Map SAML identity and roles to the application
The PicketLink SP login module processes the SAML assertion so user information can be authenticated locally. The RolesGenerationHandler maps role information from the assertion into application authorization. Check that the IdP actually emits the role attributes the application expects and that the SP maps them to the application’s role names; successful SAML authentication alone does not establish that authorization is correct.
Keep IdP account storage distinct from this SP mapping. PicketLink describes database, LDAP, and properties-file identity stores for the IdP side, while the SP consumes assertion data. If the IdP’s identity store changes, verify the emitted user and role attributes as well as the SP’s local role mapping.
Decide whether to maintain PicketLink or migrate
This setup is appropriate only where the target legacy runtime still supports the PicketLink integration. The WildFly project proposal WFLY-14922 states that the PicketLink extension and subsystem were removed from WildFly and directs users to the Keycloak SAML Elytron adapter and migration guide. Do not assume a PicketLink subsystem configuration can be installed on a current WildFly release.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches| Path | What to expect | What to verify |
|---|---|---|
| Maintain a legacy PicketLink deployment | Use the legacy login module, web-domain reference, Undertow extension, and PicketLink XML only on a compatible WildFly or EAP release. | Exact runtime version, subsystem and class availability, IdP/SP endpoints, role mapping, handler chain, and certificate lifecycle. |
| Migrate toward Keycloak SAML Elytron | WildFly’s project guidance points to the Keycloak SAML Elytron adapter and migration documentation. | Metadata and endpoints, role mapping, signatures, logout behavior, and certificate rollover against the existing federation. |
Migration is not just a change of XML file. Compare the old and target configurations for endpoint metadata, the roles the application authorizes, signature and encryption requirements, logout behavior, and trust certificates before cutover. The cited WildFly guidance identifies the migration direction but does not specify a universal conversion procedure for every PicketLink deployment.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
