Configuring a provider pipeline to use SAML tokens

Configure a provider pipeline that enables the validation and extraction of SAML token assertions and make them available to the CICS® application.

Before you begin

If you are adding SAML support to an existing pipeline, identify the pipeline configuration file. If you are creating a new pipeline, create a new pipeline configuration file. CICS provides two sample configuration files, samlprovider.xml and propagatesamlprovider.xml. The latter contains the tran_channel attribute.

Procedure

Code an <sts_authentication> element in your pipeline configuration file.
This element specifies that a Security Token Service (STS) is used for authentication and determines the type of request that is sent. Do not code an <authentication> element.
1. Code the action="validate" attribute to specify that the STS verifies a security token.
  If you do not specify this attribute, CICS assumes that the action is to request an identity token.
2. Optional: Code the token_signature="ignored" attribute to specify that CICS ignores the signature.
  If you do not specify this attribute, the default value is required, which means that a valid signature must be supplied.
3. Optional: Code the extract="no" attribute to specify that the elements of the SAML token are not put into containers.
  If you do not specify this attribute, the default value is yes, which means that CICS creates containers with the main elements of the SAML token. For full details of these containers, see SAML support containers.
4. Optional: Code the tran_channel="yes" attribute to specify that the SAML assertions are copied into containers in the DFHTRANSACTION channel to allow propagation of SAML information through a CICS application.
  If you do not specify this attribute, the default value is no, which means that the assertions are made available in containers in the channel that is passed from the pipeline.
5. Within the <sts_authentication> element, code an <auth_token_type> element.
  Within the <auth_token_type> element, code the following elements:
  
  <namespace>
  
  Set the content of this element to either urn:oasis:names:tc:SAML:1.0:assertion or urn:oasis:names:tc:SAML:2.0:assertion, depending on the version of SAML you are using.
  
  <element>
  
  Set the content of this element to Assertion.
Code an <sts_endpoint> element.
1. In the <sts_endpoint> element, code an <endpoint> element.
  This element contains a URI that points to the location of the Security Token Service (STS) on the network.
  To use the CICS Security Token Service to process SAML tokens, set the endpoint to cics://PROGRAM/DFHSAML.
  
  The CICS Security Token Service is called by the security handler. If extract="yes" is configured in the <sts_authentication> element, containers prefixed with DFHSAML are copied to the pipeline channel and are therefore available to later pipeline handlers and the target application.
2. Optional: In the <sts_endpoint> element, code a <jvmserver> element.
  This element identifies the server on which to run. If this element is not included, the default sample resource JVM server DFHXSTS is assumed.

Example

<?xml version="1.0" encoding="EBCDIC-CP-US"?> 
<provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline">
  <service>
    <service_handler_list>
      <wsse_handler>
        <dfhwsse_configuration version="1">
          <sts_authentication action="validate" token_signature="required" extract="yes" tran_channel="yes">
            <auth_token_type>
              <namespace>urn:oasis:names:tc:SAML:2.0:assertion</namespace>
              <element>Assertion</element>
            </auth_token_type>
          </sts_authentication>
          <sts_endpoint>
            <endpoint>cics://PROGRAM/DFHSAML</endpoint>
            <jvmserver>DFHXSTS</jvmserver>
          </sts_endpoint>
        </dfhwsse_configuration>
      </wsse_handler>
    </service_handler_list>
    <terminal_handler>
      <cics_soap_1.1_handler/>
    </terminal_handler>
  </service>
  <apphandler>DFHPITP</apphandler>
</provider_pipeline>