The SAML linkable interface, DFHSAML
The input and output containers, copybooks, DSECTs, and response codes that are used by CICS® SAML support.
Container names and DSECTs are available in a copybook for
each programming language, as listed in the following table:
| Language | Copybook name | Data set name |
|---|---|---|
| COBOL | DFHSAMLO | SDFHCOB |
| PL/I | DFHSAMLP | SDFHPL1 |
| C | DFHSAMLH | SDFHC370 |
| Assembler | DFHSAMLD | SDFHMAC |
The following table lists the input containers.
In this table, nnn means that there might be more than one container. Containers are distinguished by the string nnn. This string contains an alphanumeric value, unlike the corresponding input containers, where nnn is always numeric.
| Name | Type | Description |
|---|---|---|
| DFHSAML-TOKEN | CHAR | The SAML assertion. It is the responsibility of the application to specify the CCSID of the data if it is not the region default. |
| DFHSAML-FUNCTION | CHAR | OPTIONAL
|
| DFHSAML-JVMSERVR | CHAR | OPTIONAL The name of the JVMSERVER used to run the secure token server.
|
| DFHSAML-FILTER | CHAR | OPTIONAL Specifies which containers are returned for the SAML-EXTRACT function. If this container is omitted, CICS SAML support returns all the containers. See the following tables for the DSECT DFHSAML-FILTER DSECT. |
| DFHSAML-SIGNED | CHAR | OPTIONAL Must the SAML token be signed?
|
| DFHSAML-OUTTOKEN | CHAR | Read-only container obtained from token validation. Contains the previously validated token, which is being routed to another service provider, or extended and then routed. |
| DFHSAML-ATTRNnnn | CHAR | Attribute Name for attribute nnn, where nnn is a string of three alphanumeric characters.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRSnnn | CHAR | Attribute Name Space for attribute nnn, where nnn is a string of three alphanumeric characters.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRYnnn | CHAR | Attribute Friendly name for attribute nnn, where nnn is a string of three alphanumeric characters.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRFnnn | CHAR | Attribute name format for attribute nnn, where nnn is a string of three alphanumeric characters.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRAnnn | BIT | BIN(31) field, containing the number of values for attribute nnn. The maximum number of values is 999. Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-AnnnVmmm | CHAR | Attribute Value mmm for attribute nnn, where nnn and mmm are strings of three alphanumeric characters.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. The number of values for this attribute is in DFHSAML-ATTRAnnn. |
SAML-FILTER DSECT
The filter DSECT has a series of fields for each of the containers.
The name of the field is based on the name of the container, for example: SAMLI-CONFMETH to include container DFHSAML-CONFMETH.
Set the field to SAML-YES for each container that you want to be returned and SAML-NO for the containers that you do not want.
DFHSAML response container is always returned.
| Variable | Type | Description |
|---|---|---|
| SAMLI-COUNTS | CHAR (1) | DFHSAML-COUNTS container |
| SAMLI-TIMES | CHAR (1) | DFHSAML-TIMES container |
| SAMLI-FLAGS | CHAR (1) | DFHSAML-FLAGS container |
| SAMLI-ASSQNAME | CHAR (1) | DFHSAML-ASSQNAME container |
| SAMLI-AUDNR | CHAR (1) | DFHSAML-AUDNR* containers |
| SAMLI-AUTHMETH | CHAR (1) | DFHSAML-AUTHMETH container |
| SAMLI-CONFMETH | CHAR (1) | DFHSAML-CONFMETH container |
| SAMLI-CERT | CHAR (1) | DFHSAML-CERT* containers |
| SAMLI-PROXY | CHAR (1) | DFHSAML-PROXY* container |
| SAMLI-ATTR | CHAR (1) | All attributes and values |
| SAMLI-ID | CHAR (1) | DFHSAML-ID container |
| SAMLI-ISSUER | CHAR (1) | DFHSAML-ISSUER container |
| SAMLI-NAMEID | CHAR (1) | DFHSAML-NAMEID* containers |
| SAMLI-CERTIDN | CHAR (1) | DFHSAML-CERTIDN container |
| SAMLI-CERTSDN | CHAR (1) | DFHSAML-CERTSDN container |
| SAMLI-SUBJLOC | CHAR (1) | DFHSAML-SUBJ* containers |
Containers output
The following containers are output and are all read only.
The WebSphere® Application Server methods are described in Package com.ibm.websphere.wssecurity.wssapi.token.
This list is a subset of the full SAML assertion schema.
In the following table, nnn means that there might be more than one container. Containers are numbered 001 to nnn (the number of containers of this type returned). More than 999 containers of a particular type are not supported and the data in the SAML assertion that relates to them is ignored. Containers that are not mapped to a DSECT are variable length.
| Name | Type | Description |
|---|---|---|
| DFHSAML-RESPONSE | BIT | Response Code |
| DFHSAML-OUTTOKEN | CHAR | SAML token output by DFHSAML processing. Depending on the processing performed, this can be a validated. extracted, or modified and resigned token. |
| DFHSAML-COUNTS | BIT | Number of variable length containers DFHSAML-COUNTS DSECT |
| DFHSAML-TIMES | CHAR | Time values DFHSAML-TIMES DSECT |
| DFHSAML-FLAGS | CHAR | Flags bytes DFHSAML-FLAGS DSECT |
| DFHSAML-ASSQNAME | CHAR | SAML Assertion namespace:
|
| DFHSAML-AUDNRnnn | CHAR | AudienceRestriction name.
Number of containers returns is AUDNRNUM. |
| DFHSAML-AUTHMETH | CHAR | The method that is used to authenticate the token holder. For example, password, Kerberos, ltpa. |
| DFHSAML-CONFMETH | CHAR | SubjectConfirmation Method that is used in this
SAML token. Valid methods are holder-of-key, bearer, or sender-vouches.
The returned string is based on the OASIS SAML token profile 1.1 and
2.0. Note: SAML tokens that have more than one confirmation method
are not supported. If there is more than one confirmation method,
the results are unpredictable.
|
| DFHSAML-PROXYnnn | CHAR | ProxyRestriction Audience name |
| DFHSAML-ATTRSnnn | CHAR | Attribute Name Space for attribute nnn, where nnn is a 3-digit number.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRYnnn | CHAR | Attribute Friendly name for attribute nnn, where nnn is a 3-digit number.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRNnnn | CHAR | Attribute Name for attribute nnn, where nnn is a 3-digit number.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRFnnn | CHAR | Attribute name format for attribute nnn, where nnn is a 3-digit number.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-ATTRAnnn | BIT | BIN(31) field with number of values for attribute nnn (the maximum number of values is 999).
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. |
| DFHSAML-AnnnVmmm | CHAR | Attribute Value mmm for attribute nnn, where nnn and mmm are 3-digit numbers.
Number of attributes is SAMLC-ATTRNUM in DFHSAML-COUNTS container. Number of values for this attribute is in DFHSAML-ATTRAnnn. |
| DFHSAML-SAMLID | CHAR | A string that represents the ID for SAML 2.0, or AssertionID for SAML 1.1. |
| DFHSAML-ISSUER | CHAR | Name of issuer |
| DFHSAML-NAMIDF | CHAR | URI reference that represents the classification of string-based identifier information |
| DFHSAML-NAMIDQ | CHAR | Security or administrative domain that qualifies the name. |
| DFHSAML-NAMIDSPQ | CHAR | Name of a service provider or affiliation of providers. |
| DFHSAML-NAMIDSP | CHAR | Name identifier that is established by a service provider or affiliation of providers of the entity. |
| DFHSAML-NAMID | CHAR | Value of the name format property |
| DFHSAML-CERTSNUM | CHAR | An eight-character field that contains the SAML signer's X.509 Certificate serial number |
| DFHSAML-CERTIDN | CHAR | Issuer's distinguished name of SAML signer's X.509 Certificate |
| DFHSAML-CERTSDN | CHAR | Subject's distinguished name of SAML signer's X.509 Certificate |
| DFHSAML-SUBJDNS | CHAR | DNSAddress in SubjectLocality |
| DFHSAML-SUBJADDR | CHAR | IP address in SubjectLocality. Restriction: This container is not returned for SAML 2.0.
|
| Value | Description |
|---|---|
| 0 | OK |
| 1 | Invalid token |
| 2 | Container error |
| 3 | Missing required input container |
| 6 | JVM server is not enabled |
| 7 | JVM server is not found |
| 9 | DFHSAML-FUNCTION container is not CHAR |
| 10 | DFHSAML-TOKEN container is not found |
| 11 | DFHSAML-TOKEN container is not CHAR |
| 12 | DFHSAML-JVM container is not CHAR |
| 13 | DFHSAML-FILTER container is not CHAR |
| 14 | DFHSAML-SIGNED container is not CHAR |
| 15 | An error occurred in parsing the token. The DFHSJ-ERROR container contains further details. See DFHSJ-ERROR container. |
| 16 | The DFHSAML-FILTER container has invalid data |
| 17 | The DFHSAML-FUNCTION container has invalid data |
| 18 | The DFHSAML-SIGNED container has invalid data |
| 19 | The DFHSAML-OUTTOKEN container is not found |
| 21 | The certificate in the token has expired |
| 22 | The token is no longer valid |
| 23 | The certificate in the token is not trusted |
| 24 | A container is not read-only |
| 25 | A signature is not configured in the STS configuration file |
| 26 | Add attribute error |
| 27 | Attribute input containers are not CHAR |
| 28 | An attribute value is missing or empty |
| 29 | An attribute name is missing or empty |
| 30 | No key ring is specified |
| 31 | The certificate was not found in the keyring |
| 33 | The JVM server is not configured for SAML |
| Name | Type | Description |
|---|---|---|
| SAMLC-AUDRNUM | Signed fullword binary value | Number of audience restriction values |
| SAMLC-ATTRNUM | Signed fullword binary value | Number of attributes |
| SAMLC-PROXYNUM | Signed fullword binary value | Number of ProxyRestriction counts |
| Name | Type | Description |
|---|---|---|
| SAMLT-NOTBEFORE | CHAR(20) | Not before time |
| SAMLT-EXPIRES | CHAR(20) | Not on or after time |
| SAMLT-AUTHTIME | CHAR(20) | Time SAML token authorized |
| SAMLT-CERTNAFT | CHAR(20) | Certificate not valid after |
| SAMLT-CERTNBEF | CHAR(20) | Certificate not valid before |
| Name | Type | Description |
|---|---|---|
| SAMLB-PROXYRST | CHAR(1) | 'Y'/'N' flag to indicate ProxyRestriction |
| SAMLB-ONETIME | CHAR(1) | 'Y'/'N' flag to indicate OneTimeUse |