Fediz Plugin configuration

This page describes the Fediz configuration file referenced by the security interceptor of the Servlet Container (eg. authenticator in Tomcat/Jetty).

The Fediz configuration information is used to publish the federation Metadata document which is described here

Example

The following example shows the minimum configuration for Fediz.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FedizConfig>
    <contextConfig name="/fedizhelloworld">
        <audienceUris>
            <audienceItem>https://localhost:8443/fedizhelloworld</audienceItem>
        </audienceUris>
        <certificateStores>
            <trustManager>
                <keyStore file="conf/stsstore.jks" password="stsspass" type="JKS" />
            </trustManager>
        </certificateStores>
        <trustedIssuers>
            <issuer name="issuer 1" certificateValidation="ChainTrust" subject=".*CN=www.sts.com.*" />
        </trustedIssuers>
        <protocol xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="federationProtocolType" version="1.2">
            <issuer>https://localhost:9443/fediz-idp/</issuer>
        </protocol>
    </contextConfig>
</FedizConfig>

The protocol element declares that the WS-Federation protocol is being used. The issuer element shows the URL to which authenticated requests will be redirected with a SignIn request.

The IDP issues a SAML token which must be validated by the plugin. The validation requires the certificate store of the Certificate Authority(ies) of the certificate which signed the SAML token. This is defined in certificateStore. The signing certificate itself is not required because certificateValidation is set to ChainTrust. The subject defines the trusted signing certificate using the subject as a regular expression.
Finally, the audience URI is validated against the audience restriction in the SAML token.

Configuration reference

XML element Name Use Description
audienceUris Audience URI Required The values of the list of audience URIs are verified against the element AudienceRestriction in the SAML token
certificateStores Trusted certificate store Required The list of keystores (JKS, PEM) includes at least the certificate of the Certificate Authorities (CA) which signed the certificate which is used to sign the SAML token.
If the file location is not fully qualified it needs to be relative to the Container home directory
trustedIssuers Trusted Issuers Required There are two ways to configure a trusted issuer (IDP). Either you configure the subject name and the CA(s) who signed the certificate of the IDP (certificateValidation=ChainTrust) or you configure the certificate of the IDP and the CA(s) who signed it (certificateValidation=PeerTrust)
maximumClockSkew Maximum Clock Skew Optional Maximum allowable time difference between the system clocks of the IDP and RP.
Default 5 seconds.
tokenReplayCache Token Replay Cache Optional The TokenReplayCache implementation to use to cache tokens. The default is an implementation based on EHCache.
signingKey Key for Signature Optional If configured, the published (WS-Federation) Metadata document is signed by this key. Otherwise, not signed.
tokenDecryptionKey Decryption Key Optional A Keystore used to decrypt an encrypted token.
WS-Federation protocol configuration reference
XML element Name Use Metadata Description
issuer Issuer URL Required PassiveRequestorEndpoint This URL defines the location of the IDP to whom unauthenticated requests are redirected
realm Realm Optional TargetScope Security realm of the Relying Party / Application. This value is part of the SignIn request as the wtrealm parameter.
Default: URL including the Servlet Context
authenticationType Authentication Type Optional NA The authentication type defines what kind of authentication is required. This information is provided in the SignInRequest to the IDP (parameter wauth)
The WS-Federation standard defines a list of predefined URIs for wauth here.
roleURI Role Claim URI Optional NA Defines the attribute name of the SAML token which contains the roles.
Required for Role Based Access Control.
roleDelimiter Role Value Delimiter Optional NA There are different ways to encode multi value attributes in SAML.
  • Single attribute with multiple values
  • Several attributes with the same name but only one value
  • Single attribute with single value. Roles are delimited by roleDelimiter
claimTypesRequested Requested claims Optional ClaimTypesRequested The claims required by the Relying Party are listed here. Claims can be optional. If a mandatory claim can't be provided by the IDP the issuance of the token should fail
homeRealm Home Realm Optional NA Indicates the Resource IDP the home realm of the requestor. This may be an URL or an identifier like urn: or uuid: and depends on the Resource IDP implementation. This value is part of the SignIn request as the whr parameter
freshness Freshness Optional NA The desired "freshness" of the token from the IdP. This information is provided in the SignInRequest to the IdP (paramater wfresh)
tokenValidators TokenValidators Optional NA Custom Token validator classes can be configured here. The SAML Token validator is enabled by default.
See example here
Attributes resolved at runtime

The following attributes can be either configured statically at deployment time or dynamically when the initial request is received:

  • authenticationType
  • homeRealm
  • issuer

These configuration elements allows for configuring a CallbackHandler which gets a Callback object where the appropriate value must be set. The CallbackHandler implementation has access to the HttpServletRequest. The XML attribute type must be set to Class.

For more information see Fediz Extensions.

Advanced example

The following example defines the required claims and configures a custom callback handler to define some configuration values at runtime.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FedizConfig>
    <contextConfig name="/fedizhelloworld">
        <audienceUris>
            <audienceItem>https://localhost:8443/fedizhelloworld</audienceItem>
        </audienceUris>
        <certificateStores>
            <keyStore file="conf/stsstore.jks" password="stsspass" type="file" />
        </certificateStores>
        <maximumClockSkew>10</maximumClockSkew>
        <trustedIssuers>
            <issuer name="issuer 1" certificateValidation="ChainTrust" subject=".*CN=www.sts.com.*" />
        </trustedIssuers>
        <signingKey keyPassword="tompass">
            <keyStore file="tomcatKeystore.jks" password="tompass" type="JKS" />
        </signingKey>
        <protocol xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="federationProtocolType" version="1.2">
            <issuer>https://localhost:9443/fediz-idp/</issuer>
            <roleDelimiter>,</roleDelimiter>
            <roleURI>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role</roleURI>
            <claimTypesRequested>
                <claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role" optional="true" />
            </claimTypesRequested>
            <authenticationType type="String" value="http://docs.oasis-open.org/wsfed/authorization/200706/authntypes/smartcard" />
            <homeRealm type="Class" value="example.HomeRealmCallbackHandler" />
            <tokenValidators>
                <validator>org.apache.cxf.fediz.core.CustomValidator</validator>
            </tokenValidators>
        </protocol>
    </contextConfig>
</FedizConfig>