Developing a program that creates or augments SAML tokens

You can develop a CICS® application or a web service application to create a SAML token or to add attributes to a SAML token and to re-sign it.

About this task

You can use CICS SAML support to add attributes to SAML tokens and re-sign the request with the certificate specified in the CICS STS configuration file. The SAML token might be received from an external sender or created from a template. The application that you develop can be either a CICS application or a web service application.

Attention: Create, augment, and re-sign tokens only on a region where all application code that participates in the augmenting of the token is trusted by other members of the federation.

Procedure

Add the attributes by creating the following containers in the same channel that was used to validate the original SAML token.

Note: You must have validated the token before you can modify it. The validated token is contained in the DFHSAML-OUTTOKEN container.
1. Put the attribute name into container DFHSAML-ATTRNaaa, where aaa are three uppercase alphanumeric characters.
  For example:
```
EXEC CICS PUT CONTAINER('DFHSAML-ATTRNORG') CHANNEL('SAML-CHANNEL') FROM('title')
```
2. Optional: Put the attribute name space into container DFHSAML-ATTRSaaa, where aaa are the same characters as you used for the attribute name container.
  This step is not required for SAML version 2.0.
3. Optional: Put the attribute friendly name into container DFHSAML-ATTRYaaa, where aaa are the same characters as you used for the attribute name container.
  For example:
```
EXEC CICS PUT CONTAINER('DFHSAML-ATTRYORG') CHANNEL('SAML-CHANNEL') FROM('eduPersonAffiliation')
```
4. Optional: Put the attribute format into container DFHSAML-ATTRFaaa, where aaa are the same characters as you used for the attribute name container.
  For example:
```
EXEC CICS PUT CONTAINER('DFHSAML-ATTRNORG') CHANNEL('SAML-CHANNEL') FROM('urn:oasis:names:tc:SAML:2.0:attrname-format:uri')
```
5. Optional: Put one or more attribute values into containers DFHSAML-AaaaNbbb, where aaa are the same characters as you used for the attribute name container and bbb are three uppercase alphanumeric characters.
  For example:
```
EXEC CICS PUT CONTAINER('DFHSAML-AORGV001') CHANNEL('SAML-CHANNEL') FROM('staff')
EXEC CICS PUT CONTAINER('DFHSAML-AORGV002') CHANNEL('SAML-CHANNEL') FROM('employee')
```
Create the token in either of the following ways:
- Put the SAML-ISSUE value in the DFHSAML-FUNCTION container and link to the linkable interface DFHSAML, which creates the new token. By default, the token is re-signed using the signature options that are specified in the STS configuration file. If no signature is required, the application can create a DFHSAML-SIGNED container with the SAML-IGNORED option specified before it calls DFHSAML. If an <issuer> is specified in the STS configuration file, its value is used in the new SAML token.
- Invoke a web service. If the requester pipeline associated with the web service is configured for SAML, it automatically adds attributes to the original token and creates a new one. By default, the pipeline re-signs the SAML token by using the signature options that are specified in the STS configuration file. If no signature is required, set the requester pipeline configuration option token_signature to no. If an <issuer> is specified in the STS configuration file, its value is used in the new SAML token. In addition to creating a new SAML token, the requester pipeline also inserts the SAML token in the outbound web service request.