The <sts_authentication> element

Specifies that a Security Token Service (STS) must be used for authentication and determines what type of request is sent.

Used in:

  • Service provider
  • Service requester

Attributes:

Name Description
action Specifies what type of request CICS® sends to the STS when a message is received in the service provider pipeline. Valid values are as follows:
issue
The STS issues an identity token for the SOAP message. This value is not valid for SAML in a provider pipeline.
validate
The STS validates the provided identity token and returns whether the token is valid to the security handler.
If you do not specify this attribute, CICS assumes that the action is to request an identity token.

In a service requester pipeline, you cannot specify this attribute because CICS always requests that the STS issues a token.

extract This attribute is valid only when you are using SAML. Are the elements of the SAML token to be extracted? Valid values are as follows:
no
The elements of the SAML token are not extracted into containers.
yes
The main elements of the SAML token are extracted and placed in containers that are created by CICS.
token_signature This attribute is valid only when you are using SAML. Must a token signature be supplied? Valid values are as follows:
ignored
Any signature that is supplied is ignored.
required
A valid signature must be supplied. This is the default value.
tran_channel
This attribute is valid only when you are using SAML. In a service provider pipeline, this attribute specifies whether SAML assertions contained in a message that is received in the pipeline are made available to the target application program in containers in the transaction channel DFHTRANSACTION. Valid values are as follows:
yes
The SAML assertions are copied into containers in the DFHTRANSACTION channel to be made available to the program. For more information about container names and types, see .
no
SAML assertions are not made available to the program via the DFHTRANSACTION channel, but in containers in the channel that is passed to the program by the pipeline. This is the default value.
If you do not specify this attribute for a service provider, the assertions are made available only in containers in the channel that is passed to the program from the SOAP pipeline.
In a service requester pipeline, this attribute specifies whether the SAML token contained in the DFHSAML-OUTTOKEN container of the transaction channel DFHTRANSACTION is used on the request. Valid values are as follows:
yes
The contents of the DFHTRANSACTION channel's DFHSAML-OUTTOKEN container are used as the SAML token for the request.
no
The contents of the DFHSAML-OUTTOKEN container in the channel that is passed to the pipeline are used as the request's SAML token. This is the default value.
If you do not specify this attribute for a service requester, the SAML token is taken from the DFHSAML-OUTTOKEN container in the channel that is passed to the SOAP pipeline.

Contains:

  1. An <auth_token_type> element. This element is required when you specify a <sts_authentication> element in a service requester pipeline and is optional in a service provider pipeline. For more information, see <auth_token_type>.
    • In a service requester pipeline, the <auth_token_type> element indicates the type of token that STS issues when CICS sends it the user ID contained in the DFHWS-USERID container. The token that CICS receives from the STS is placed in the header of the outbound message.
    • In a service provider pipeline, the <auth_token_type> element is used to determine the identity token that CICS takes from the message header and sends to the STS to exchange or validate. CICS uses the first identity token of the specified type in the message header. If you do not specify this element, CICS uses the first identity token that it finds in the message header. CICS does not consider the following as identity tokens:
      • wsu:Timestamp
      • xenc:ReferenceList
      • xenc:EncryptedKey
      • ds:Signature
  2. In a service provider pipeline only, an optional, empty <suppress/> element. If this element is specified, the handler does not attempt to use any security tokens in the message to determine the user ID that the work runs under. The <suppress/> element includes the identity token that is returned by the STS.

Example

The following example shows a service provider pipeline, where the security handler requests a token from the STS.

<sts_authentication action="issue">
   <auth_token_type>
      <namespace>http://example.org.tokens</namespace>
      <element>UsernameToken</element>
   </auth_token_type>
   <suppress/>
</sts_authentication>


dfhws_sts_authentication.html | Timestamp icon Last updated: Sunday, 4 June 2017