Configuring the CICS Security Token Service

To control the behavior of the CICS® STS, update your STS configuration file and perhaps your java.policy file and system initialization parameters.

About this task

CICS uses a file referred to as the STS configuration file to control the behavior of the CICS STS. By default, CICS uses a file called sts.xml in the directory that is identified by the JVMPROFILEDIR SIT parameter. If that file does not exist, CICS uses the file specified by the JVM property com.ibm.cics.sts.config in the JVM server profile. For example: -Dcom.ibm.cics.sts.config=/var/security/sts/sts-config.xml. A sample file sts-config.xml is provided.

Procedure

Update the STS configuration file according to your requirements.
1. If you want to update the issuer of the SAML token when you add attributes to the token, specify an issuer.
  1. Code an <issuer> element in your STS configuration file.
  2. Within the <issuer> element, code a <format> element.
  3. Within the <issuer> element, code a <uri> element.
2. To allow for any time difference in system clocks on different computers, you can specify a tolerance value or clock skew.
  If you find that SAML tokens are regularly being rejected as expired, or as not yet valid, it might be caused by a discrepancy in clock time between the issuing and receiving systems. Setting a skew time can prevent SAML tokens from appearing to arrive before they are issued, or arriving already expired when they have, in reality, recently been issued. However, if you set too large a value, you might accept tokens that have genuinely expired.
  1. Code a <clock_skew> element in your STS configuration file. The value is set in milliseconds, so to set a time of 90 seconds, code <clock_skew>90000</clock_skew>.
3. If you intend to re-sign a SAML token, specify the certificate label.
  1. Code a <signature> element in your STS configuration file. Set the hash_algorithm attribute to sha-1 or sha-2 according to the hash algorithm you want to use.
    Note: The hash algorithm sha-3 is not supported.
  2. Optional: Within the <signature> element, code a <certificate> element.
  3. Optional: Within the <certificate> element, code a <label> element. Set it to the value of the RACF® certificate label.
4. If you intend to verify signatures or to re-sign SAML tokens, you can specify the keystore type.
  1. Code a <keystore> element in the STS configuration file.
  2. Within the <keystore> element, code a <type> element. If you want to use cryptographic hardware to validate signatures, give it the value JCECCARACFKS. Otherwise, use the value JCERACFKS, which is the default value.
Optional: If you intend to verify signatures or to re-sign SAML tokens, update the java.policy file and set the KEYRING SIT parameter.
1. Update the java.policy file to give the CICS user permission to alter the list of Java™ security providers.
  A sample file, sts-java.policy, is provided.
  1. To use the sample file, edit it to change /&USSHOME/ to the appropriate value for your installation, and set the JVM property java.security.policy in the JVM server profile to specify its path and file name.
  2. If you use an existing java.policy file, update it to include the following rule:
```
// All permissions granted to CICS codesource protection domain
grant codeBase "file:///&USSHOME///-" { 
permission java.security.AllPermission; 
};
```
    where USSHOME is the name and path of the root directory for CICS Transaction Server files on z/OS® UNIX.
2. Set the SIT parameter KEYRING to specify the RACF keyring that contains the set of certificates you want to use.