Skip to main content
Version: 7.2405.x.x LTS

WS-Trust authentication AuthStates

SecurityTokenServiceClient​

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

The SecurityTokenServiceClient is an AuthState that requests a security token at a remote WS-Trust Security Token Service. It can be configured to send different types of credentials and to request various token types.

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.wstrust.SecurityTokenServiceClient
Loggingwstrust
Auditingnone
Methodsauthenticate, stepup, unlock, logout

Markers​

  • WS-Trust(Kerberos):token
  • WS-Trust(SAML):token
  • WS-Trust(username):extern
  • WS-Trust(username/password):username-password
  • WS-Trust(Binary)

Which marker is valid depends on the used profile.

Properties​

  • profile ({saml,kerberos,username,binary} , "saml")

    The WS-Security authentication profile to use to authenticate towards the STS. The source of the credential (or username/password) must be configured according to the chosen profile.

  • version ({1.2,1.3,1.4}, "1.4"}

    Version of the WS-Trust protocol to use. This setting only changes the namespace URIs.

  • binding ({header,header-mustUnderstand, onbehalfof}, "onbehalfof")

    Method of transmission of the authentication credentials. Set the property to "header"/"header-mustUnderstand" to send the credential as a WS-Security header. Set the property to "onbehalfof" to insert the credentials in an OnBehalfOf statement within the request body. The value "header-mustUnderstand" causes the MustUnderstand attribute to be set for the generated WSS header.

  • requestType (URI or {validate, issue, cancel}, "issue")

    Defines the WS-Trust request type to request from the STS. The shortcuts "validate", "issue" and "cancel" stand for:

    • "validate"
    • "issue"
    • "cancel"

  • action (string, default depending on requestType)

    The SOAP action HTTP header value to use. The default values depend on the configured request type in the property requestType:

    • Request type "validate"
    • Request type "issue"
    • Request type "cancel"

  • tokenType (URI or {sectoken, x509, saml}, - )

    The WS-Security token type to request from the STS. The shortcuts "sectoken", "x509" and "saml" stand for:

    • "sectoken"
    • "x509"
    • "saml"

  • operationMode ({jaxb, dispatch}, "dispatch")

    The SecurityTokenServiceClient AuthState implements two modes of operation. The operation mode "jaxb" uses the regular JAX-WS API with JAXB un/marshalling. The operation mode "dispatch" uses the JAX-WS Dispatch API that operates directly on the DOM tree of the request and response. As automatic JAXB marshalling may interfere with signature integrity and thus invalidate received tokens, it is advised to use dispatch mode when sending or receiving plain signed XML structures such as SAML assertions.

  • decodeToken (boolean, "true")

    This property defines whether to decode received encoded binary tokens.

  • tokenEncoding (string, "UTF-8")

    If token decoding is activated, this property defines the character encoding used in the decoding.

  • keyType (URI or {bearer, publickey, symmetrickey}, -)

    The WS-Trust key type to send to the STS. The shortcuts "bearer", "publickey" and "symmetrickey" stand for:

    • "bearer"
    • "publickey"
    • "symmetrickey"

  • appliesToURI (URI, -)

    An AppliesTo URI to send to the STS.

  • claimsDialect (URI, http://schemas.xmlsoap.org/ws/2005/05/identity)

    The dialect used to specify requested claims to the STS. Only the default is currently supported.

  • claims (whitespace separated list of strings, -)

    List of (optional) claims to request from the STS. An "*" (asterisk) appended to a claim marks it as non-optional.

  • mandatoryClaims (whitespace separated list of strings, -)

    List of mandatory claims to request from the STS. Same as if all claims had had an "*" appended. If a claim is present in both the optional and the mandatory list, it is found to be mandatory.

  • lifetime (time in seconds, -)

    If set, the element wst:Lifetime including the elements wsu:Created and wsu:Expires are added to the request for the STS.

  • ttl (time in seconds, "5")

    Maximum lifetime of the request sent to the STS, in seconds. This will be indicated by adding a wsu:Timestamp SOAP header to the request. Set this property to "0" (zero) to disable sending wsu:Timestamps.

  • connection (whitespace separated list of URLs, required)

    A list of URLs of the STS. This property is mandatory.

  • maxAge (time in seconds, -)

    Maximal age of response as indicated by wst:Lifetime structure. This property is only evaluated if a wst:Lifetime element is found in STS response.

  • tolerance (time in seconds, "10")

    Tolerance of time lag between client and server when validating wst:Lifetime element in STS response.

Connectivity​

  • service.maintainSession (boolean, "false")

    Whether to maintain the HTTP session from one request to another in a bound service client.

  • service.poolingMode ({load balancing,failover}, "failover")

    This property sets the handling of multiple connection URLs. Load balancing is sticky in for a bound service client.

  • service.binding ({thread, none}, "thread")

    Whether and how to bind a service client. None will create the client for every request. The thread option will store the client in the ThreadLocal therefore it can be reused for subsequent outgoing requests in the same nevisAuth request processing.

  • service.discardInterval (time in seconds, "10")

    Time in seconds to disregard URLs when communication resulted in a non-application error (that is, an error that indicated a system problem at the service).

  • ervice.retryDiscardedResources (boolean, "false")

    If all services are marked as discarded, then this property defines whether to nevertheless retry a service. If activated, this forms an "emergency mode" where services are accessed despite the discard interval. The next service to be retried will be selected according to the configured pooling mode.

  • service.retries (number, defaults to number of connection URLs)

    Number of retries to attempt when experiencing connectivity errors before assuming all services are unavailable.

  • service.httpclient.tls.trustStoreRef

  • service.httpclient.tls.keyObjectRef

  • service.httpclient.tls.hostnameVerification

  • service.httpclient.proxy.host

  • service.httpclient.proxy.port

    info

    HttpClient properties work the same as described here, however this AuthState uses a JAX-WS soap client. So only the configuration options specified above are applicable.

SAML Profile​

  • credential (string, "${ourargs:saml.SAMLAssertion}")

    Source of the SAML assertion to send to the STS as authenticating credential. The default source matches the configuration of an IdentityProviderState (see chapter IdentityProviderState)) with the property out.binding set to "internal-assertion".

Kerberos Profile​

  • credential (string, -)

    Source of the Kerberos AP-REQ token to send to the STS as authentication credential. This should be configured to ${outargs:kerberos.apreq.<SERVICE-SPI>}, assuming that the previous AuthState is a FrontendKerberosAuthState AuthState, or a BackendKerberosAuthState AuthState, with the property TicketFormat set to "apreq". For more information on these AuthState, see chapter Kerberos authentication AuthStates.

Username Profile​

  • username (string, "${inargs:isiwebuserid}")

    The username to be sent to the STS in a WS-Security Username Profile construct.

  • password (string, -)

    The password to be sent to the STS in a WS-Security Username Profile construct. Can be left undefined to send a Username construct without password.

  • digest (boolean, "true")

    This property defines whether to send the password in clear text or as a nonce-enriched hash value.

Binary Profile​

  • credential (string, -)

    Source of generic binary token to send to the STS as authentication credential.

  • valueType (string, -)

    The value type identifier for the binary token. This value is required.

  • encodingType (string, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary)

    The encoding type of the binary token.

  • tokenId (string, "reqBinaryToken")

    The token ID of the binary token.

Input​

Depending on configured profile

Transitions​

  • ok

    Back end returned a token.

Output​

  • ws-trust.token

    Received security token, not validated

Errors​

  • lasterror=1

    lasterrorinfo=No status in validation response

  • lasterror=1

    lasterrorinfo=No token in response

  • lasterror=1

    lasterrorinfo=Multiple tokens in response

  • lasterror=1

    lasterrorinfo=No RequestSecurityTokenResponseType in response

  • lasterror=1

    lasterrorinfo=Return state not valid

  • lasterror=99

    lasterrorinfo=Exception from back end or client side transport.

Notes​

  • ws-trust.token

    Received security token, not validated.

  • ws-trust.response

    The complete response, as received from the STS.

Example​

<AuthState name="STSClientUserName" final="false"
  class="ch.nevis.esauth.auth.states.wstrust.SecurityTokenServiceClient">
  <ResultCond name="ok" next="STSConsumer"/>
  <Response value="AUTH_CONTINUE">
    <Gui name="AuthUidPwDialog" label="login.label">
      <GuiElem name="lasterror" type="error" label="${notes:lasterrorinfo}"
        value="${notes:lasterror}"/>
      <GuiElem name="info" type="info" label="login.test.text"/>
      <GuiElem name="isiwebuserid" type="text" label="userid.label"
        value="${request:loginId}"/>
      <GuiElem name="isiwebpasswd" type="pw-text" label="password.label"/>
      <GuiElem name="submit" type="button" label="submit.button.label" value="Login"/>
    </Gui>
  </Response>
  <property name="binding" value="header" />
  <property name="requestType" value="issue"/>
  <property name="keyType" value="bearer"/>
  <property name="connection" value="https://sts.exampl.org:8443/STS/STSServiceUT"/>
  <property name="profile" value="username"/>
  <property name="username" value="${inargs:isiwebuserid}"/>
  <property name="password" value="${inargs:isiwebpasswd}"/>
  <property name="tokenType" value="SAML"/>
  <property name="appliesToURI" value="${request:resource}"/>
  <property name="claims" value="
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname*
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname*
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  "/>
</AuthState>