- Configuring a Identity Provider
- Configuring the web.xml
- The picketlink.xml configuration file
To configure an application as a PicketLink Identity Provider you need to follow this steps:
- Configure the web.xml.
- Configure an Authenticator.
- Configure a Security Domain for your application.
- Configure PicketLink JBoss Module as a dependency.
- Create and configure a file named WEB-INF/picketlink.xml.
Before configuring your application as an Identity Provider you need to add some configurations to your web.xml.
Let's start by defining a security-constraint element to restrict access to resources from unauthenticated users:
As you can see above, we define that only users with a role named manager are allowed to access the protected resources. Make sure to give your users the same role you defined here, otherwise they will get a 403 HTTP status code.
The next step is define your FORM login configuration using the login-config element:
Make sure you have inside your application the pages defined in the elements form-login-page and form-error-page.
|Please, make sure you have a welcome file page in your application. You can define it in your web.xml or simply create an index.jsp at the root directory of your application.|
All the configuration for an especific Identity Provider goes at the WEB-INF/picketlink.xml file. This file is responsible to define the behaviour of the Authenticator. During the identity provider startup, the authenticator parses this file and configures itself.
Bellow is how the picketlink.xml file should looks like:
|The schema for the picketlink.xml file is available here: https://github.com/picketlink/picketlink/blob/master/modules/federation/src/main/resources/schema/config/picketlink_v2.1.xsd.|
This element defines the basic configuration for the identity provider. The table bellow provides more information about the attributes supported by this element:
|AssertionValidity||Defines the timeout for the SAML assertion validity, in miliseconds.||Defaults to 300000. Deprecated. Use the PicketLinkSTS element, instead.|
||Defines the name of the org.picketlink.identity.federation.core.interfaces.RoleGenerator subclass to be used to obtain user roles.|| Defaults to org.picketlink.identity.federation.core.impl.EmptyRoleGenerator.
|| Defines the name of the org.picketlink.identity.federation.core.interfaces.AttributeManager subclass to be used to obtain the SAML assertion attributes.
||Defautls to org.picketlink.identity.federation.core.impl.EmptyAttributeManager.|
|StrictPostBinding||SAML Web Browser SSO Profile has a requirement that the IDP does not respond back in Redirect Binding. Set this to false if you want to force the IDP to respond to SPs using the Redirect Binding.||Values: true|false. Defaults to true, the IDP always respond via POST Binding.|
|| Indicates if digital signature/verification of SAML assertions are enabled. If this attribute is marked to true the Service Providers must support signatures too, otherwise the SAML messages will be considered as invalid.
||Values: true|false. Defaults to false.|
||Indicates if SAML Assertions should be encrypted. If this attribute is marked to true the Service Providers must support signatures too, otherwise the SAML messages will be considered as invalid.|| Values: true|false. Defaults to false
||Defines the name of the org.picketlink.identity.federation.web.core.IdentityParticipantStack subclass to be used to register and deregister participants in the identity federation.||Defaults to org.picketlink.identity.federation.web.core.IdentityServer.STACK.|
|HostedURI||Defines an URI used to redirect users after an IDP-initiated authentication or if you access the IDP root directly with an authenticated user.||Default to /hosted/.|
|SSLClientAuthentication||Indicates if the IDP should authenticate clients when using SSL based on their certificates.||Values true|false. Defaults to false.|
This element value refers to the URL of the Identity Provider.
The Trust and Domains elements defines the hosts trusted by this Identity Provider. You just need to inform a list of comma separated domain names.
To enable digital signatures for the SAML assertions you need to configure:
- Set the SupportsSignature attribute to true;
- Add the SAML2SignatureGenerationHandler and the SAML2SignatureValidationHandler in the handlers chain (Handler Element).
- Configure a KeyProvider* *element.
To enable encryption for SAML assertions you need to configure:
- Set the Encrypt attribute to true;
- Add the SAML2EncryptionHandler and the SAML2SignatureValidationHandler in the handlers chain (Handler Element).
- Configure a KeyProvider* *element.
PicketLink provides some built-in Handlers to help the Identity Provider Authenticator processing the SAML requests and responses.
The handlers are configured through the Handlers element.
|When configuring the IDP, you do not need to specify the PicketLinkSTS element in the configuration. If it is ommited PicketLink will load the default configurations from a file named core-sts inside the picketlink-core-VERSION.jar.
Override this configuration only if you need to. Eg.: change the token timeout or specify a custom Security Token Provider for SAML assertions.
See the documentation at Security Token Service Configuration.