Developing a SAML-aware initial program
You can write a program to extract a SAML token and link to DFHSAML to process the token.
6.3 Support for SAML using the CICS Security Token Service is removed as of CICS TS 6.3.
6.2 If this function is used, the CICS_STABILIZED_FUNCTIONS health check issues message DFHH0955.
As an alternative to using the web services support (see Configuring a provider pipeline to use SAML tokens), you can write your own SAML-aware initial program as a security front end to validate SAML tokens. Such a program can be useful when you are using messages that use HTTP, IBM® MQ, or any other protocol, rather than a SOAP message.
The SAML-aware initial program extracts the SAML token from the message. It then puts the token into a character container, DFHSAML-TOKEN, in a channel. The program then links to the program DFHSAML with the channel to validate the token and extract the containers. For details of the containers, see SAML support containers.
You can use either a user-defined channel or the transaction channel (DFHTRANSACTION). If you are using a user-defined channel, the containers are passed on LINK requests that explicitly pass that channel. If you are using the transaction channel, the containers are available throughout the transaction.
The application can use information in the containers, such as SAML attributes, by using GET CONTAINER commands. For a specific example of how you might use this information, see Pattern: developing a SAML-aware initial program.
Pattern: developing a SAML-aware initial program
SAML-aware programs can conform to common patterns. A typical pattern for an application is for the initial program to be SAML-aware. In this pattern, the program uses the information in the SAML assertion to make decisions before it runs appropriate parts of the application.
The information in the SAML assertion is in read-only containers. These containers are either in the channel that is passed to the program from the SOAP pipeline or, if the program is doing its own message handling and SAML validation, returned from the DFHSAML program.
An example of the processing that the SAML-aware program does is obtaining information from the attribute containers. It looks for an attribute name container (for example, DFHSAML-ATTRN001) and an attribute value in that container (for example, DFHSAML-A001V001). This attribute might be used by the program to represent the role or authority of the user and so allow the application to select which parts of the application are available to the caller.
The application might have to pass on information to other programs in the application. Because the containers are read-only, information can be passed securely by passing the channel to the next program, or transaction that uses the CHANNEL interface, on the LINK, XCTL, RETURN, or START commands.
The application might also have to audit the request so that the transaction can be associated with the original SAML token, and hence the user. To make this association, write a customer logging program, which writes the validated SAML token (in container DFHSAML-OUTTOKEN) or selected containers to a journal.
Pattern: reusing a validated SAML token
You might want to validate a SAML token and later in the same transaction call a web service from a requester program and use the same token.
A validated SAML token is held in the DFHSAML-OUTTOKEN container. As this container is read-only, it cannot be moved between channels. To avoid having to reissue the validation request, and thus to improve performance, you can use the transaction channel, DFHTRANSACTION.
When you validate a SAML token from an incoming web service, code the
tran_channel="yes" attribute in the <sts_authentication>
element in the configuration file for your provider pipeline. This attribute specifies that the SAML
assertions are copied from the output containers into containers in the DFHTRANSACTION channel.
To reuse the validated SAML token in a web service, code the
tran_channel="yes" attribute in the <sts_authentication>
element in the configuration file for the requester pipeline that is used by the web service.