Fediz 1.1 introduces Federation across Security Domains (Part 2)

In the first blog on this topic I explained how to add security domains to the Fediz STS which is based on the Apache CXF STS. This blog focuses on how to set up the Fediz IDP thus you can access an application but authenticate either against the requestor IDP of realm A or realm B.

I posted a blog some time back about WS-Federation across several companies and explained the benefits and key requirements here. I recommend to read that blog first.

Here a quick summary of the goals and requirements by introducing WS-Federation for Web Application Single-Sign-On:

• Application doesn't care about authentication
• Application doesn't care against which authentication system the user has been authenticated
• Application doesn't care where the user attributes are coming from
• Application has got a trusted relationship with a single IDP/STS instance which ensures the user is authenticated and the user attributes are provided in one syntax and semantic independent from which source they are coming from
• Application must be able to enforce certain authentication methods (ex. strong authentication)
• Application must be able to enforce certain user attributes in the security token

In the last blog, we've prepared the STS which is responsible to issue tokens for the two realms REALMA and REALMB. Further, the STS is able to federate between the two realms by mapping the identities (attribute type of Relationship bean configuration. This means, a person must have an identity in realm A (ex. bob) and an identity in realm B (ex. BOB). To keep it simple, the mapping is based to lowercase the username. Another option is to federate/map the claims which doesn't require that a person must have an identity in both realms. This requires more effort to set up a demo and might be provided in the future for illustration purposes, but all required functionality and extension points are available.

Notes:

• The Fediz IDP doesn't support yet to host several realms in one WAR file. Therefore, two Servlet Containers must be set up to deploy the IDP war file.

  In B2B scenarios this won't be required anyway as the B2B partner has got an IDP attached to its realm as well as the application service provider has got an IDP attached to its realm. It might make sense in scenarios where the company itself has got more than one authentication systems in place.

• For ease of use, the Fediz IDP and Fediz STS are deployed into the same Serlvet Container and therefore accessed with the same TCP port. Due to the fact, that the Fediz STS supports both realms in one WAR file, the Fediz STS WAR fediz-idp-sts.war is just deployed twice.

Install Apache CXF Fediz IDP

The Fediz IDP is provided as part of the subproject Fediz in Apache CXF. The new version provides the Apache Maven profile realm-a (Default) and realm-b which packages the IDP either for security domain REALM A and REALM B.

You can either download the sources of the Fediz IDP from the following location

git clone git://git.apache.org/cxf-fediz.git

or

svn co https://svn.apache.org/repos/asf/cxf/fediz/trunk

You can build the IDP for realm A with the following Maven command

mvn clean install -Prealm-a

The IDP is packaged as a WAR file at services/idp/target/fediz-idp.war

You can build the IDP for realm B with the following Maven command

mvn clean install -Prealm-b

The IDP is packaged as a WAR file at services/idp/target/fediz-idp-remote.war

Note: The WAR file and therefore the servlet context name is not fediz-idp but fediz-idp-remote. This is required because cookies are bound to the hostname (ex. localhost) and the path (ex. fediz-idp). If the servlet context is the same, cookies are overwritten between the two IDP instances. There are also other options to bound the WAR file with a specific servlet context name but this relies on the Servlet Container provider.

Last option is to download the archive from the snapshot maven repository. Keep in mind that this IDP is built with the profile realm-a. Only the following files must be updated for realm B:

• WEB-INF/applicationContext.xml

  Change

  <import resource="idp-config-realma.xml" />

  to

  <import resource="idp-config-realmb.xml" />

• WEB-INF/classes/realm.properties

  Change

  realm.STS_URI=REALMA

  to

  realm.STS_URI=REALMB

• WEB-INF/web.xml

  Change

  <param-value>urn:org:apache:cxf:fediz:idp:realm-A</param-value>

  to

  <param-value>urn:org:apache:cxf:fediz:idp:realm-B</param-value>

Note: The built WAR files require that IDP Realm A is deployed into a Servlet Container running on port 9443 and IDP Realm B is deployed into a Servlet Container running on port 12443. If you want to change that then you must update the file WEB-INF/classes/realm.properties or at source location services/idp/src/main/resources/.

Update Relying Party (Application)

I assume you have installed fedizhellworld example into a supported Serlvet Container. If not, install the fedizhellworld example based on the README.txt.

The following steps must be processed to establish the trust with the IDP Realm A:

• Issuer URL must be Realm A (ex. https://localhost:9443/fediz-idp/federation )
• Signer certificate of Realm A must be imported into the truststore because new certificates are used for realm A and realm B
  You can either copy the file stsstore.jks from the STS archive within WEB-INF/classes or copy the file realma.cert from the STS archive from the same location.

Run the demo

You have now deployed the IDP realm A (fediz-idp.war) into a Servlet Container listening on port 9443 and IDP realm B (fediz-idp-remote.war) into a Servlet Container listening on port 12443. Finally, the Relying Party has been updated to trust the IDP Realm A.

When you now access the fedizhelloworld application (ex. https://localhost:8443/fedizhelloworld/secure/fedservlet) you get redirected to the IDP Realm A and the following web page is shown

You can now choose in which domain you would like to authenticate. Choose the IDP in the list and click Select Home Realm. If you choose Realm B you get redirected to IDP Realm B and username/password popup is shown (use uppercase username and passwords) or IDP Realm A shows username/password popup (use lowercase username and passwords).

If you choose Realm B and enter the user ALICE and the password ECILA you finally see the user alice (lowercase) shown in the application. You know why? Exactly, the STS does the identity mapping when the REALM A is requested a SAML token for the application fedizhelloworld on-behalf-of the SAML token issued by Realm B.

Notes

• The IDP will ask you only once to choose your home realm. The choice is stored in the cookie FEDIZ_HOME_REALM
• If your home realm is realm B and you're successfully authenticated, the IDP realm A won't redirect you to realm B the next time, as the original SAML token of realm B is cached in realm A.

IDP Configurations

The design of the IDP changed (Spring Web Flow and Spring Security), new features are implemented and thus the configuration is completely different to version 1.0. I don't want to go into too much details in this blog, instead I'll update the Apache CXF Fediz Wiki soon.

Use form based login

Change the spring security configuration in WEB-INF/security-config.xml and set the following configuration:

    <!--<security:http-basic />-->
    <security:form-login />

Configure an additional Relying Party

The main configuration file of the IDP is idp-config-realma.xml. This file contains configurations for the IDP, trusted IDPs and Relying Parties.

If you want to configure an additional application add a ServiceConfig bean and add it to the map services in the IDP configuration bean.

  <bean id="idp-realmA" class="org.apache.cxf.fediz.service.idp.model.IDPConfig">
    ...
    <property name="services">
      <util:map>
        <entry key="urn:org:apache:cxf:fediz:fedizhelloworld" value-ref="srv-fedizhelloworld" />
      </util:map>
    </property>
    ...

  <bean id="srv-fedizhelloworld" class="org.apache.cxf.fediz.service.idp.model.ServiceConfig">
    <property name="realm" value="urn:org:apache:cxf:fediz:fedizhelloworld" />
    <property name="protocol" value="http://docs.oasis-open.org/wsfed/federation/200706" />
    <property name="serviceDisplayName" value="Fedizhelloworld" />
    <property name="serviceDescription" value="Web Application to illustrate WS-Federation" />
    <property name="role" value="ApplicationServiceType" />
    <property name="tokenType" value="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" />
    <property name="lifeTime" value="3600" />
    <property name="requestedClaims">
      <util:list>
        <bean class="org.apache.cxf.fediz.service.idp.model.RequestClaim">
          <property name="claimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
          <property name="optional" value="false" />
        </bean>
        <bean class="org.apache.cxf.fediz.service.idp.model.RequestClaim">
          <property name="claimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" />
          <property name="optional" value="false" />
        </bean>
        <bean class="org.apache.cxf.fediz.service.idp.model.RequestClaim">
          <property name="claimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
          <property name="optional" value="false" />
        </bean>
        <bean class="org.apache.cxf.fediz.service.idp.model.RequestClaim">
          <property name="claimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role" />
          <property name="optional" value="true" />
        </bean>
      </util:list>
    </property>
  </bean>

It's important that the attribute realm matches with the realm configured in the application (fediz-config.xml). The attributes tokenType, lifeTime and requestedClaims are optional. Only the protocol defined in the above bean is supported by the IDP and therefore the default value. The remaining attributes are ignored but used in the future like the Web GUI.

Configure an additional Trusted IDP

If you want to configure an additional trusted IDP add a TrustedIDPConfig bean and add it to the map trustedIDPs in the IDP configuration bean.

  <bean id="idp-realmA" class="org.apache.cxf.fediz.service.idp.model.IDPConfig">
    ...
    <property name="trustedIDPs">
      <util:map>
        <entry key="urn:org:apache:cxf:fediz:idp:realm-B" value-ref="trusted-idp-realmB" />
      </util:map>
    </property>
    ...

  <bean id="trusted-idp-realmB" class="org.apache.cxf.fediz.service.idp.model.TrustedIDPConfig">
    <property name="realm" value="urn:org:apache:cxf:fediz:idp:realm-B" />
    <property name="cacheTokens" value="true" />
    <property name="url" value="https://localhost:${realmB.port}/fediz-idp-remote/federation" />
    <property name="certificate" value="realmb.cert" />
    <property name="trustType" value="PEER_TRUST" />  <!-- Required for Fediz Core, Process SignInResponse -->
    <property name="protocol" value="http://docs.oasis-open.org/wsfed/federation/200706" />
    <property name="federationType" value="FederateIdentity" /> <!-- Required for STS Relationship -->
    <property name="name" value="REALM B" />
    <property name="description" value="IDP of Realm B" />
  </bean>

It's important that the filename of the PEM encoded certificate is configured which has been used to sign the SAML token by the trusted IDP. The attribute name is required for informational purposes whereas the remaining attributes are ignored but used in the future like the Web GUI.

Even there is much more to say I finish this post and write about other features of the new Fediz IDP in the near future.

Please post feedback and ideas to the CXF mailing list.

Thank you for all support and feedback!

Fediz 1.1 introduces Federation across Security Domains (Part 1)

Fediz 1.1 introduces a bunch of new features like support for Jetty, Spring Security and Websphere. But a lot of effort has been put into the Fediz IDP. I'd like to thank Thierry Beucher for his valuable contributions to the new release of the Fediz IDP.

The new features are:

• Federation Metadata

  The IDP supports publishing the WS-Federation Metadata document which allows to more easily integrate the IDP into platforms which support referencing a Metadata document. Metadata consists of the signing certificate, the provided claims, etc.

• Spring Web Flow support

  The IDP has been refactored to use Spring Web Flow to manage the federation flow. This provides flexibility to be able to customize the IDP to company's specific requirements. The IDP is secured by Spring Security to get the benefits and flexibility of Spring Security.

• Resource IDP and Home Realm Discovery

  This is the major new feature. The IDP is able to figure out from which security domain/realm the browser request is coming from to redirect the sign-in request to the requestor IDP which does the authentication and issues a token which is sent to the Resource IDP. The Resource IDP will then either map the principal from one security domain to the target security domain and get claims information of the mapped principal or transform the claims information and finally issue a new token for the relying party (application).

  More complex scenarios described in this blog are now possible.

In this post, I'd like to focus on the last feature which I splitted in two posts. The first one focuses on extending the STS to support more than one security domain/realm and the second on the IDP.

Install Apache CXF Fediz IDP

The Fediz STS is provided as part of the subproject Fediz in Apache CXF. The new version provides the Apache Maven profile realms which packages an STS with two security domains called REALM A and REALM B.

You can either download the sources of the Fediz STS from the following location

git clone git://git.apache.org/cxf-fediz.git

or

svn co https://svn.apache.org/repos/asf/cxf/fediz/trunk

You can build the whole project with the following Maven command

mvn clean install

The STS is packaged as a WAR file at services/sts/target/fediz-idp-sts.war

or download the archive from the snapshot maven repository.

The URL of the STS has the following syntax depending on the hostname and port of your servlet engine. https://localhost:port/fediz-idp-sts/?wsdl The page will list the different URL's for the web service endpoints of the STS:

• https://localhost:9443/fediz-idp-sts/REALMA/STSServiceTransportUT
  STS endpoint for REALM A which requires username/password authentication
• https://localhost:9443/fediz-idp-sts/REALMA/STSServiceTransport
  STS endpoint for REALM A with requires on-behalf-of saml token (implicit identiy mapping is done)
• https://localhost:9443/fediz-idp-sts/REALMB/STSServiceTransportUT
  STS endpoint for REALM B which requires username/password authentication
• https://localhost:9443/fediz-idp-sts/REALMB/STSServiceTransport
  STS endpoint for REALM B with requires on-behalf-of saml token (implicit identiy mapping is done)

In the context of federation, you request a token from your requestor STS/IDP. In this example, either REALM-A or REALM-B with username/password (.../fediz-idp-sts/<realm>/STSServiceTransportUT). After authentication, you request (implicitly as part of the federation protocol) a specific token of the security domain/realm where the application is conntected to. This use case makes use of the on-behalf-of feature of the STS (.../fediz-idp-sts/<realm>/STSServiceTransport).

The following users are set up in realm A and realm B:

User	Password
Realm A
alice	eclia
bob	bob
ted	det
Realm B
ALICE	ECLIA
BOB	BOB
TED	DET

As you might imagine, the identity mapping implementation is fairly easy as you just lower- or uppercase the principal name. More information about how to plug in different identity mappings see below in Identity Mapper.

How to add a new security domain to the STS

If you customize the realms or add an additional realm, the following steps are required. You can either customize the deployed WAR fediz-idp-sts.war of the downloaded archive or make updates to the sources
Note: You could also make use of the Overlay feature of Apache Maven.

• Define a new realm C

  Some beans must be updated and added to the Spring configuration file cxf-transport.xml. The changes for a new realm are highlighted in bold.

  Source location: src/realms/webapps/WEB-INF/
  Deploy location: /WEB-INF/

    <util:map id="realms">
      <entry key="REALMA" value-ref="realmA"/>
      <entry key="REALMB" value-ref="realmB"/>
      <entry key="REALMC" value-ref="realmC"/>
    </util:map>
  
    <bean id="realmA" class="org.apache.cxf.sts.token.realm.SAMLRealm">
      <property name="issuer" value="STS Realm A"/>
      <property name="signaturePropertiesFile" value="stsKeystoreA.properties" />
      <property name="callbackHandlerClass" value="org.apache.cxf.fediz.service.sts.PasswordCallbackHandler" />
    </bean>
  
    <bean id="realmB" class="org.apache.cxf.sts.token.realm.SAMLRealm">
      <property name="issuer" value="STS Realm B"/>
      <property name="signaturePropertiesFile" value="stsKeystoreB.properties" />
      <property name="callbackHandlerClass" value="org.apache.cxf.fediz.service.sts.PasswordCallbackHandler" />
    </bean>
  
    <bean id="realmC" class="org.apache.cxf.sts.token.realm.SAMLRealm">
      <property name="issuer" value="STS Realm C"/>
      <property name="signaturePropertiesFile" value="stsKeystoreC.properties" />
      <property name="callbackHandlerClass" value="org.apache.cxf.fediz.service.sts.PasswordCallbackHandler" />
    </bean>
  
  
    <util:list id="relationships">
      <bean class="org.apache.cxf.sts.token.realm.Relationship">
        <property name="sourceRealm" value="REALMA" />
        <property name="targetRealm" value="REALMB"/>
        <property name="identityMapper" ref="identityMapper" />
        <property name="type" value="FederatedIdentity" />
      </bean>
      <bean class="org.apache.cxf.sts.token.realm.Relationship">
        <property name="sourceRealm" value="REALMB" />
        <property name="targetRealm" value="REALMA"/>
        <property name="identityMapper" ref="identityMapper" />
        <property name="type" value="FederatedIdentity" />
      </bean>
  
      <bean class="org.apache.cxf.sts.token.realm.Relationship">
        <property name="sourceRealm" value="REALMA" />
        <property name="targetRealm" value="REALMC"/>
        <property name="identityMapper" ref="identityMapper" />
        <property name="type" value="FederatedIdentity" />
      </bean>
  
    </util:list>
  
  

  In this case, only a trust relationship from realm A to realm C is established and it's based on identity mapping.
• Generate signing certificate

  The new realm signs the SAML assertion with a different signer certificate.

  keytool -genkeypair -keyalg RSA -validity 3600 -alias realmc -keystore stsrealm_c.jks -dname "cn=REALMC" -keypass realmc -storepass storepass
  keytool -export -keystore stsrealm_c.jks -storepass storepass -export -alias realmc -file realmc.cert
  

  The keystore has to be added
  Source location: src/realms/resources
  Deploy location: /WEB-INF/classes
• Import certificate into truststore ststrust.jks

  The certificate must be added to the truststore thus another realm is able to validate the SAML assertion signed by realm C.

  Note: The above federation relationship definitions do not cover the use case that another realm must trust realm C but I recommend to add the certificate for completeness reasons.

  keytool -import -trustcacerts -keystore ststrust.jks -storepass storepass -alias realmc -file realmc.cert -noprompt
  

  The truststore has to be updated at
  Source location: src/realms/resources
  Deploy location: /WEB-INF/classes
• Configure signer certificate

  Above, the signer certificate is configured for the SAML Realm C in the attribute signaturePropertiesFile of the bean realmC. The properties file has to look like this:

  org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
  org.apache.ws.security.crypto.merlin.keystore.type=jks
  org.apache.ws.security.crypto.merlin.keystore.password=storepass
  org.apache.ws.security.crypto.merlin.keystore.alias=realmc
  org.apache.ws.security.crypto.merlin.file=stsrealm_c.jks
  

  Note: Copy&paste an existing stsKeystore properties file.

  The properties file has to be added here:
  Source location: src/realms/resources
  Deploy location: /WEB-INF/classes

• Define JAX-WS endpoint in STS

  Two JAX-WS endpoints are required depending on whether you need to support username/password authentication in the STS (WSDL Port TransportUT_Port) and/or issue a SAML token on-behalf-of another SAML token (WSDL Port Transport_Port).

  The former requires an authentication backend which is file based in the Fediz STS. The file based authentication backend relies on the UsernamePasswordCallbackHandler which uses a spring map with user name and password entries (see beans upCallBackHandlerRealmC and REALMC).

    <jaxws:endpoint id="transportSTSRealmC" implementor="#transportSTSProviderBean"
      address="/REALMC/STSServiceTransport" wsdlLocation="/WEB-INF/wsdl/ws-trust-1.4-service.wsdl"
      xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
      serviceName="ns1:SecurityTokenService" endpointName="ns1:Transport_Port">
      <jaxws:properties>
      </jaxws:properties>
    </jaxws:endpoint>
  
    <jaxws:endpoint id="transportSTSRealmCUT" implementor="#transportSTSProviderBean"
      address="/REALMC/STSServiceTransportUT" wsdlLocation="/WEB-INF/wsdl/ws-trust-1.4-service.wsdl"
      xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
      serviceName="ns1:SecurityTokenService" endpointName="ns1:TransportUT_Port">
      <jaxws:properties>
        <entry key="ws-security.callback-handler" value-ref="upCallBackHandlerRealmC" />
      </jaxws:properties>
    </jaxws:endpoint>
    
    <bean id="upCallBackHandlerRealmC"
      class="org.apache.cxf.fediz.service.sts.UsernamePasswordCallbackHandler">
      <property name="passwords" ref="REALMC" />
    </bean>
    
    <util:map id="REALMC">
      <entry key="user1"
        value="pw1" />
    </util:map>
  

  The bean which defines the username and passwords is defined in the imported spring configuration file passwords.xml. The claims of the users in the two realms are defined in userClaims.xml. You can find more information about managing the claims in an older blog.

  If you want to configure an LDAP backend check the following blog post:

  • LDAP support enhanced in CXF 2.7.5
  • Configure LDAP backend in STS
• Identity mapper

  If you add a new realm, the Identity Mapper provided in org.apache.cxf.fediz.service.sts.realms.IdentityMapperImpl must be enhanced. In practise, you access a database, LDAP or web service to get the mapping. You must implement the interface org.apache.cxf.sts.IdentityMapper to customize the identity mapping to your needs.

Customize realm concept

• The Fediz STS is based on the Apache CXF STS. The STS supports several realms where each realm is connected to an authentication server like LDAP, file (Testing), database or a custom authentication server. The service consumer must know from which STS realm he requests a token from by choosing the appropriate URL. The distinction is based on the syntax in the URL.

  The syntax in the Fediz STS is https://:/fediz-idp-sts/<REALM>/.... The distinction is after the servlet context fediz-idp-sts. This behaviour is implemented in org.apache.cxf.fediz.service.sts.realms.UriRealmParser and configured in the bean customRealmParser.

  You can implement a different distinction based on the machine name, http port or servlet context. Maybe you prefer to deploy the realms in different JVMs. You just have to implement the interface org.apache.cxf.sts.RealmParser.

• When you request a token on-behalf-of another SAML token, the STS must be able to figure out from which realm the token has been issued. As above, the STS provides an interface which must be implement to change the default behaviour of the Fediz STS. The default behaviour is implemented in org.apache.cxf.fediz.service.sts.realms.SamlRealmCodec and expects the realm encoded in the CN (Common Name) of the signer certificate. This class implements the interface org.apache.cxf.sts.token.realm.SAMLRealmCodec and can be customized. You have to update the bean samlRealmCodec or update the bean which references this bean.

Please post feedback and ideas to the CXF mailing list.

Thank you for all support and feedback!