The <authentication> element

Specifies the use of security tokens in the headers of inbound and outbound SOAP messages.

Used in:

  • Service provider
  • Service requester

Contained by:

Attributes:

Attribute Description
trust and mode
Taken together, the trust and mode attributes specify:
  • whether asserted identity is used
  • the combination of security tokens that are used in SOAP messages.
Asserted identity allows a trusted user to assert that work must run under a different identity, the asserted identity, without the trusted user having the credentials that are associated with that identity.

When asserted identity is used, messages contain a trust token and an identity token. The trust token is used to check that the sender has the correct permissions to assert identities. The identity token holds the asserted identity, that is, the user ID under which the request is run.

Use of asserted identity requires that a service provider trusts the requester to make this assertion. In CICS®, the trust relationship is established with security manager surrogate definitions: the requesting identity must have the correct authority to start work on behalf of the asserted identity.

The allowable combinations of these attributes, and their meanings, are described in Table 1 and Table 2.
Table 1. The mode and trust attributes in a service requester pipeline
trust mode Meaning
none none No credentials are added to the message
none basic Invalid combination of attribute values
none signature Asserted identity is not used. CICS uses a single X.509 security token, which is added to the message, and used to sign the message body. The certificate is identified with the <certificate_label> element, and the algorithm is specified in the <algorithm> element.
blind none Invalid combination of attribute values
blind basic Asserted identity is not used. CICS adds an identity token to the message, but does not provide a trust token. The identity token is a user name with no password. The user ID placed in the identity token is the contents of the DFHWS-USERID container (which, by default, contains the running task's user ID).
blind signature Invalid combination of attribute values
basic none Invalid combination of attribute values
basic basic Invalid combination of attribute values
basic signature Invalid combination of attribute values
signature none Invalid combination of attribute values
signature basic Asserted identity is used. CICS adds the following tokens to the message:
  • The trust token is an X.509 security token.
  • The identity token is a user name with no password.
The certificate that is used to sign the identity token and message body is specified by the <certificate_label>. The user ID placed in the identity token is the contents of the DFHWS-USERID container (which, by default, contains the running task's user ID).
signature signature Invalid combination of attribute values
Table 2. The mode and trust attributes in a service provider pipeline
trust mode Meaning
none none Inbound messages need not contain any credentials, and CICS does not attempt to extract or verify any credentials that are found in a message. However, CICS checks that any signed elements are correctly signed.
none basic Inbound messages must contain a user name security token with a password. CICS puts the user name in the DFHWS-USERID container.
none basic-ICRX Invalid combination of attribute values
Start of changenoneEnd of change Start of changebasic-kerberosEnd of change Start of changeInvalid combination of attribute valuesEnd of change
none signature Inbound messages must contain an X.509 security token that has been used to sign the message body.
blind none Invalid combination of attribute values
blind basic Inbound messages must contain an identity token, where the identity token contains a user ID and optionally a password. CICS puts the user ID in the DFHWS-USERID container. If no password is included, CICS uses the user ID without verifying it. If a password is included, the security handler DFHWSSE1 verifies it.
blind basic-ICRX Inbound messages must contain an ICRX identity token. CICS resolves the identity, puts the user ID in the DFHWS-USERID container, and puts the ICRX in container DFHWS-ICRX. Authentication, if required, uses client-certified SSL or another security protocol.
Start of changeblindEnd of change Start of changebasic-kerberosEnd of change Start of changeInvalid combination of attribute valuesEnd of change
blind signature Inbound messages must contain an identity token, where the identity token is the first X.509 certificate in the SOAP message header. The certificate does not need to have signed the message. The security handler extracts the matching user ID and places it in the DFHWS-USERID container.
basic none Invalid combination of attribute values
basic basic Inbound messages must use asserted identity:
  • The trust token is a user name token with a password
  • The identity token is a second user name token without a password. CICS puts this user name in container DFHWS-USERID.
basic basic-ICRX Inbound messages must use asserted identity:
  • The trust token is a user name token with a password.

    CICS establishes whether the user ID and password combination are valid, and, if they are valid, CICS resolves the asserted ICRX-based identity to a user ID. CICS then performs a surrogate security check from the authenticated identity to the asserted identity.

  • The identity token is an ICRX, which identifies the specific client user. CICS puts the user name in container DFHWS-USERID and the ICRX in container DFHWS-ICRX.
Start of changebasicEnd of change Start of changebasic-kerberosEnd of change Start of change

Inbound messages must use asserted identity.

One token is required, a Kerberos Version 5 token with one of the following format types:

  • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ1510
  • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ1510
  • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ4120
  • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ4120
The token must be Base-64 encoded. CICS validates the token by using Network Authentication Service for z/OS and puts the user ID associated with the token in container DFHWS-USERID.End of change
basic signature Inbound messages must use asserted identity:
  • The trust token is a user name token with a password
  • The identity token is an X.509 certificate. CICS puts the user ID associated with the certificate in container DFHWS-USERID.
signature none Invalid combination of attribute values
signature basic Inbound messages must use asserted identity:
  • The trust token is an X.509 certificate
  • The identity token is a user name token without a password. CICS puts the user name in container DFHWS-USERID.
The identity token and the body must be signed with the X.509 certificate.
signature basic-ICRX Inbound messages must use asserted identity.
  • The trust token is an ICRX signed with an X.509 certificate.

    CICS resolves the X.509 certificate to a user ID and ensures that the XML signature is valid. CICS resolves the asserted ICRX-based identity to a user ID. CICS then performs a surrogate security check from the authenticated X.509 identity to the asserted ICRX identity.

  • The identity token is a user name token without a password. CICS puts the user name in container DFHWS-USERID and the ICRX in container DFHWS-ICRX.
Start of changesignatureEnd of change Start of changebasic-kerberosEnd of change Start of changeInvalid combination of attribute valuesEnd of change
signature signature Inbound messages must use asserted identity:
  • The trust token is an X.509 certificate
  • The identity token is a second X.509 certificate. CICS puts the user ID associated with this certificate in container DFHWS-USERID.
The identity token and the body must be signed with the first X.509 certificate (the trust token).
Notes:
  1. The combinations of the trust and mode attribute values are checked when the PIPELINE is installed. The installation fails if the attributes are incorrectly coded.
  2. CICS uses password verification to verify a user ID during the processes described here. By default, password verification does not cause RACF® to record that the user ID has been used for a sign-on. If you require this information for audit purposes, or if your system is set up to revoke unused user IDs, specify the system initialization parameter SECVFYFREQ=USRDELAY for the CICS region. When you set this system initialization parameter, CICS enforces a full verification request at least once a day for each user ID that is used to log on to the CICS region. The full verification request makes RACF record the date and time of last access for the user ID, and write user statistics.

Contains:

  1. An optional, empty <suppress/> element.

    If this element is specified in a service provider pipeline, the handler does not attempt to use any security tokens in the message to determine under which user ID the work runs.

    If this element is specified in a service requester pipeline, the handler does not attempt to add to the outbound SOAP message any of the security tokens that are required for authentication.

  2. In a requester pipeline, an optional <algorithm> element that specifies the URI of the algorithm that is used to sign the body of the SOAP message. You must specify this element if the combination of trust and mode attribute values indicate that the messages are signed. You can specify only the RSA with SHA1 algorithm in this element. The URI is http://www.w3.org/2000/09/xmldsig#rsa-sha1.
  3. An optional <certificate_label> element that specifies the label that is associated with an X.509 digital certificate installed in RACF. If you specify this element in a service requester pipeline and the <suppress> element is not specified, the certificate is added to the security header in the SOAP message. If you do not specify a <certificate_label> element, CICS uses the default certificate in the RACF key ring.

    This element is ignored in a service provider pipeline.

Example

<authentication trust="signature" mode="basic">
  <suppress/>
  <algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</algorithm>
  <certificate_label>AUTHCERT03</certificate_label>
</authentication>