The <authentication> element

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

Used in:

Contained by:

Attributes:

Attribute Description
trust
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 should run under an different identity, the asserted identity, without the trusted user having the credentials 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, and the identity token holds the asserted identity, that is, the user ID under which the request is executed.

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 the these attributes, and their meanings, are described in Table 1 and Table 2.

mode
Table 1. The mode and trust attributes in a service requester pipeline
trust mode Meaning
none none No credentials are added to the message
basic Invalid combination of attribute values
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.
basic (any) Invalid combination of attribute values
signature none Invalid combination of attribute values
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 username with no password.
The certificate 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 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 will check that any signed elements have been correctly signed.
basic Inbound messages must contain a username security token with a password. CICS puts the username in container DFHWS-USERID.
signature Inbound messages must contain an X.509 security token.
basic none Invalid combination of attribute values
basic Inbound messages must use asserted identity:
  • The trust token is a username token with a password
  • The identity token is a second username token without a password. CICS puts this username in container DFHWS-USERID, and this user ID is used to run transactions in CICS.
signature Inbound messages must use asserted identity:
  • The trust token is a username 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, and this user ID is used to run transactions in CICS.
signature none Invalid combination of attribute values
basic Inbound messages must use asserted identity:
  • The trust token is an X.509 certificate
  • The identity token is a username token without a password. CICS puts the username in container DFHWS-USERID, and this user ID is used to run transactions in CICS.
The identity token and the body must be signed with the X.509 certificate.
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, and this user ID is used to run transactions in CICS.
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 resource is installed. The installation fails if the attributes are incorrectly coded.

Contains:

  1. An optional <certificate_label> element that specifies the label associated with an X.509 digital certificate installed in RACF®. If this element is specified 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. The certificate label should not contain any of the following characters:
    < > : ! =

    This element is ignored in a service provider pipeline.

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

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

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

  3. Start of changeAn <algorithm> element that specifies the URI of the algorithm used to sign the body of the SOAP message.
    You can specify the following algorithms:
    Algorithm URI
    Digital Signature Algorithm with Secure Hash Algorithm 1 (DSA with SHA1) http://www.w3.org/2000/09/xmldsig#dsa-sha1
    Rivest-Shamir-Adleman algorithm with Secure Hash Algorithm 1 (RSA with SHA1) http://www.w3.org/2000/09/xmldsig#rsa-sha1

    The DSA with SHA1 signature algorithm is supported on inbound SOAP messages only. If you are using basic authentication on inbound SOAP messages, you must still specify the <algorithm> element.

    End of change

Example

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