/
Security Token Service

Security Token Service

Owned by Shaun Morris
Last updated: Aug 20, 2013 by Matthew RameyVersion comment

Description

The STS provides a DDF  that a system can request a SAML v2.0 assertion from.

The STS is an extension of Apache CXF-STS.  It is a SOAP web service that utilizes WS-Security policies. The generated SAML assertions contain attributes about a user and is used by the Policy Enforcement Point (PEP) in the Secure Endpoints. Specific configuration details on the bundles that come with DDF can be found on the Security STS application page. This page details all of the STS components that come out of the box with DDF along with configuration options, installation help, and which services they import and export.

Using the STS

Once installed the STS can be used to request SAML v2.0 assertions via a SOAP web service request. Out of the box it supports authentication from existing SAML tokens, CAS Proxy tickets, Username/Password, and x509 certificates. It also supports retrieving claims using LDAP.

Standalone Installation

The STS cannot currently be installed on a kernel distribution of DDF. To run a STS-only DDF installation, uninstall the catalog components that are not being used. The list below shows features which can be uninstalled to minimize the runtime size of DDF in an STS-only mode. This list is not a comprehensive list of every feature that can be uninstalled but rather a list of the larger components that can be uninstalled without impacting the STS functionality.  

Unneeded Features
catalog-core-standardframework
catalog-solr-embedded-provider
catalog-opensearch-endpoint
catalog-opensearch-souce
catalog-rest-endpoint

 

STS Claims Handlers

Claims handlers are classes that convert the incoming user credentials into a set of attribute claims that will be populated in the SAML assertion. An example in action would be the LDAPClaimsHandler that takes in the user's credentials and retrieves the user's attributes from a backend LDAP server. This attributes are then mapped and adding to the SAML assertion being created. Integrators and developers can add in additional claims handlers that can handler other types of external services that store user attributes.

Adding a Custom Claims Handler

Description:

A claim is an additional piece of data about a principal that can be included in a token along with basic token data. A claims manager provides hooks for a developer to plug in claims handlers to ensure that the STS includes the specified claims in the issued token.

Motivation:

One may want to add a custom claims handler to retrieve attributes from an external attribute store. 

Steps:

The following outlines the steps required to add a custom claims handler to the STS:

  • The new claims handler must implement the org.apache.cxf.sts.claims.ClaimsHander interface.

    /**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

package org.apache.cxf.sts.claims;

import java.net.URI;
import java.util.List;

/**
 * This interface provides a pluggable way to handle Claims.
 */
public interface ClaimsHandler {

    List<URI> getSupportedClaimTypes();

    ClaimCollection retrieveClaimValues(RequestClaimCollection claims, ClaimsParameters parameters);

}

  • Expose the new claims handler as an OSGi service under the org.apache.cxf.sts.claims.ClaimsHandler interface.

    <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <bean id="CustomClaimsHandler" class="security.sts.claimsHandler.CustomClaimsHandler" />
    
    <service ref="customClaimsHandler" interface="org.apache.cxf.sts.claims.ClaimsHandler"/>
  
</blueprint>
  • Deploy the bundle.

 

If the new claims handler is hitting an external service that is secured with SSL you may have to add the root CA of the external site to the DDF trustStore and add a valid certificate into the DDF keyStore so that it can encrypt messages that will be accepted by the external service. For more information on certificates, check out the Configuring a Java Keystore for Secure Communications page.

STS WS-Trust WSDL Document

This XML file is found inside of the STS bundle and is named ws-trust-1.4-service.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/">
	<wsdl:types>
		<xs:schema elementFormDefault="qualified" targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
			<xs:element name="RequestSecurityToken" type="wst:AbstractRequestSecurityTokenType"/>
			<xs:element name="RequestSecurityTokenResponse" type="wst:AbstractRequestSecurityTokenType"/>
			<xs:complexType name="AbstractRequestSecurityTokenType">
				<xs:sequence>
					<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
				</xs:sequence>
				<xs:attribute name="Context" type="xs:anyURI" use="optional"/>
				<xs:anyAttribute namespace="##other" processContents="lax"/>
			</xs:complexType>
			<xs:element name="RequestSecurityTokenCollection" type="wst:RequestSecurityTokenCollectionType"/>
			<xs:complexType name="RequestSecurityTokenCollectionType">
				<xs:sequence>
					<xs:element name="RequestSecurityToken" type="wst:AbstractRequestSecurityTokenType" minOccurs="2" maxOccurs="unbounded"/>
				</xs:sequence>
			</xs:complexType>
			<xs:element name="RequestSecurityTokenResponseCollection" type="wst:RequestSecurityTokenResponseCollectionType"/>
			<xs:complexType name="RequestSecurityTokenResponseCollectionType">
				<xs:sequence>
					<xs:element ref="wst:RequestSecurityTokenResponse" minOccurs="1" maxOccurs="unbounded"/>
				</xs:sequence>
				<xs:anyAttribute namespace="##other" processContents="lax"/>
			</xs:complexType>
		</xs:schema>
	</wsdl:types>
	<!-- WS-Trust defines the following GEDs -->
	<wsdl:message name="RequestSecurityTokenMsg">
		<wsdl:part name="request" element="wst:RequestSecurityToken"/>
	</wsdl:message>
	<wsdl:message name="RequestSecurityTokenResponseMsg">
		<wsdl:part name="response" element="wst:RequestSecurityTokenResponse"/>
	</wsdl:message>
	<wsdl:message name="RequestSecurityTokenCollectionMsg">
		<wsdl:part name="requestCollection" element="wst:RequestSecurityTokenCollection"/>
	</wsdl:message>
	<wsdl:message name="RequestSecurityTokenResponseCollectionMsg">
		<wsdl:part name="responseCollection" element="wst:RequestSecurityTokenResponseCollection"/>
	</wsdl:message>
	<!-- This portType an example of a Requestor (or other) endpoint that 
         Accepts SOAP-based challenges from a Security Token Service -->
	<wsdl:portType name="WSSecurityRequestor">
		<wsdl:operation name="Challenge">
			<wsdl:input message="tns:RequestSecurityTokenResponseMsg"/>
			<wsdl:output message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
	</wsdl:portType>
	<!-- This portType is an example of an STS supporting full protocol -->
	<wsdl:portType name="STS">
		<wsdl:operation name="Cancel">
			<wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel" message="tns:RequestSecurityTokenMsg"/>
			<wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/CancelFinal" message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
		<wsdl:operation name="Issue">
			<wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" message="tns:RequestSecurityTokenMsg"/>
			<wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal" message="tns:RequestSecurityTokenResponseCollectionMsg"/>
		</wsdl:operation>
		<wsdl:operation name="Renew">
			<wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Renew" message="tns:RequestSecurityTokenMsg"/>
			<wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/RenewFinal" message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
		<wsdl:operation name="Validate">
			<wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Validate" message="tns:RequestSecurityTokenMsg"/>
			<wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/ValidateFinal" message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
		<wsdl:operation name="KeyExchangeToken">
			<wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KET" message="tns:RequestSecurityTokenMsg"/>
			<wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/KETFinal" message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
		<wsdl:operation name="RequestCollection">
			<wsdl:input message="tns:RequestSecurityTokenCollectionMsg"/>
			<wsdl:output message="tns:RequestSecurityTokenResponseCollectionMsg"/>
		</wsdl:operation>
	</wsdl:portType>
	<!-- This portType is an example of an endpoint that accepts 
         Unsolicited RequestSecurityTokenResponse messages -->
	<wsdl:portType name="SecurityTokenResponseService">
		<wsdl:operation name="RequestSecurityTokenResponse">
			<wsdl:input message="tns:RequestSecurityTokenResponseMsg"/>
		</wsdl:operation>
	</wsdl:portType>
	<wsdl:binding name="STS_Binding" type="wstrust:STS">
		<wsp:PolicyReference URI="#STS_policy"/>
		<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
		<wsdl:operation name="Issue">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="Validate">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Validate"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="Cancel">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="Renew">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Renew"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="KeyExchangeToken">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KeyExchangeToken"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="RequestCollection">
			<soap:operation soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/RequestCollection"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>
	<wsp:Policy wsu:Id="STS_policy">
		<wsp:ExactlyOne>
			<wsp:All>
				<wsap10:UsingAddressing/>
				<wsp:ExactlyOne>
					<sp:TransportBinding xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
						<wsp:Policy>
							<sp:TransportToken>
								<wsp:Policy>
									<sp:HttpsToken>
										<wsp:Policy/>
									</sp:HttpsToken>
								</wsp:Policy>
							</sp:TransportToken>
							<sp:AlgorithmSuite>
								<wsp:Policy>
									<sp:Basic128/>
								</wsp:Policy>
							</sp:AlgorithmSuite>
							<sp:Layout>
								<wsp:Policy>
									<sp:Lax/>
								</wsp:Policy>
							</sp:Layout>
							<sp:IncludeTimestamp/>
						</wsp:Policy>
					</sp:TransportBinding>
				</wsp:ExactlyOne>
				<sp:Wss11 xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<wsp:Policy>
						<sp:MustSupportRefKeyIdentifier/>
						<sp:MustSupportRefIssuerSerial/>
						<sp:MustSupportRefThumbprint/>
						<sp:MustSupportRefEncryptedKey/>
					</wsp:Policy>
				</sp:Wss11>
				<sp:Trust13 xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<wsp:Policy>
						<sp:MustSupportIssuedTokens/>
						<sp:RequireClientEntropy/>
						<sp:RequireServerEntropy/>
					</wsp:Policy>
				</sp:Trust13>
			</wsp:All>
		</wsp:ExactlyOne>
	</wsp:Policy>
	<wsp:Policy wsu:Id="Input_policy">
		<wsp:ExactlyOne>
			<wsp:All>
				<sp:SignedParts xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<sp:Body/>
					<sp:Header Name="To" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="From" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="FaultTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="ReplyTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="MessageID" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="RelatesTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="Action" Namespace="http://www.w3.org/2005/08/addressing"/>
				</sp:SignedParts>
				<sp:EncryptedParts xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<sp:Body/>
				</sp:EncryptedParts>
			</wsp:All>
		</wsp:ExactlyOne>
	</wsp:Policy>
	<wsp:Policy wsu:Id="Output_policy">
		<wsp:ExactlyOne>
			<wsp:All>
				<sp:SignedParts xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<sp:Body/>
					<sp:Header Name="To" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="From" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="FaultTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="ReplyTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="MessageID" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="RelatesTo" Namespace="http://www.w3.org/2005/08/addressing"/>
					<sp:Header Name="Action" Namespace="http://www.w3.org/2005/08/addressing"/>
				</sp:SignedParts>
				<sp:EncryptedParts xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
					<sp:Body/>
				</sp:EncryptedParts>
			</wsp:All>
		</wsp:ExactlyOne>
	</wsp:Policy>
	<wsdl:service name="SecurityTokenService">
		<wsdl:port name="STS_Port" binding="tns:STS_Binding">
			<soap:address location="http://localhost:8181/services/SecurityTokenService"/>
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Example Request & Responses for a SAML Assertion

The DDF STS offers many different ways to requesting a SAML assertion. For help in understanding the various request and response formats, samples have been provided. The samples are divided out into different request token types.

RequestSecurityToken

UsernameToken Sample Request/Response

X.509 Token Sample Request/Response

BinarySecurityToken (CAS) Sample Request/Response

Known Issues