WS-Federation AuthStates

PassiveRequestorProfileIDP

The PassiveRequestorProfileIDP AuthState acts as an Identity Provider for the WS-Federation's WebSSO profile. The AuthState is configured in a dispatcher position, typically as the first state in the processing chain.

The AuthState analyses incoming messages and selects the configured transition that best matches the requested action (e.g., "wsignin1.0", "wsignout1.0" or any other action requested in the wa parameter). From there, the state engine can be configured as usual, including displaying GUI screens to the user. Once the status AUTH_DONE is reached, the AuthEngine will hand control back to the PassiveRequestorProfileIDP AuthState, where the correct WS-Federation response is generated.

info

The actions "wsignin1.0", "wsignout1.0" and "wsignoutcleanup1.0" are fully implemented.

Single logout scenario

Whenever a sign-in request is completed, the wreply (if available) or wtrealm request parameter is stored in a list of participating service providers (relying parties). If a sign-out request is received, a list of signout URLs to call is generated by appending the request parameter wa=signoutcleanup1.0 to all the URLs in the list of participating service providers. The resulting comma-separated list of signout URLs is then written to the output argument (outArg) wsfed.cleanupURLs. To complete sign-out at the Relying Parties, the outArg cleanup URLs will have to be propagated as a field (e.g., as a hidden field) in the GUI descriptor to nevisLogRend. There it may be evaluated and a list of links to trigger the signout at the Relying Parties may be generated.

Description

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

Topic	Description
Class	ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileIDP
Logging	wsfed
Auditing	none
Marker	none
Methods	process (all events)

Properties

• tokenType ({x509v3, kerberos, saml, plain, response}, "saml")

  The token type sent back to the requestor. The AuthState sends "plain" tokens as-is to the requestor; "response"-type tokens are sent as-is instead of embedded into a wst:RequestSecurityTokenResponse structure.

• result (string, default depends on the value of the tokenType property)

  The source of the authentication token to be sent to the requestor.

  • For the token types "x509v3" and "saml", the result property defaults to ${outargs:dyncert.cert} and ${outargs:saml.SAMLAssertion}, respectively. Thus, the Dynamic X.509 certificate generation AuthState DynCert (see chapter Dynamic X.509 certificate generation AuthState) and the AuthState IdentityProviderState AuthState (see chapter IdentityProviderState) can be used to issue these tokens with the default value.
  • For the token types "kerberos" and "plain", the source of the authentication token has to be configured explicitly. To have the AuthStates FrontendKerberosAuthState or BackendKerberosAuthState (see chapter Kerberos authentication AuthStates) fetch a Kerberos ticket for usage as authentication token, you have to configure the following properties:
    • AuthState FrontendKerberosAuthState or BackendKerberosAuthState: Set the TicketFormat property to "apreq".
    • This AuthState (PassiveRequestorProfileIDP):
      • Set the tokenType property to "kerberos".
      • Set the result property to ${outargs:kerberos.apreq.<service SPN>}.
  • For token type "response", the default value for the result property is ${notes:ws-trust.response}. Thus is the location where the SecurityTokenServiceClient AuthState (see chapter WS-Trust authentication AuthStates) propagates the response it receives from a security token service.

• reply (string, ${sess: <AuthState-Name>-wsfed.in.wreply})

  Source for the reply URL where the WS-Federation response is sent to. Some service providers do not send the wreply parameter with the initiating request. In such cases, the correct URL must be configured.

• defaultReply (string, ${notes:<AuthState-Name>-wsfed.in.default.reply})

  The wreply request parameter is optional. Configure the defaultReply property if WS-Federation SPs are sending requests without a wreply parameter.

• maxAge (time in seconds, -)

  Maximum age of incoming requests, as determined by the wct parameter, in seconds. If the maxAge property is configured, a wct parameter must be sent.

• validateWreplyMode ({none, domain}, none)

  • "none" is the WS-Federation 1.2 compliant mode. Any wtrealm string is accepted.
  • "domain" restricts the wtrealm to a subdomain of wreply: Both input parameters must exist and must be valid URLs. This prevents simple token stealing attacks.

• cleanupReply (string, -)

  Defines to what value the wreply parameter in the cleanup URLs generates in case a wsignout1.0 request should be set. The single sign-out request generated by the PassiveRequestorIDP AuthState may contain a wreply query parameter when a redirect from the relying party is required. This is an optional parameter and not required when concurrent logout is performed.

Input

Various parameters of the PassiveRequestorProfile AuthState.

Transitions

• <action>(<reply-URL>), <action>, <reply-URL>

  Notations for transitions based on action requested and reply URL (if provided).

• ok

  Fallback transition, selected if no transition matching the notation above is configured.

Output

• wsfed.cleanupURLs (string)

  Comma-separated list of signout URLs to call in single signout scenario.

Errors

• lasterror=wa.unknown

  lasterrorinfo=The resource redirected the client to the IP/STS with a bad request. The wa action is unknown.

Notes

none

Example

Example (Fetching a token from STS)

<AuthState name="WsFedSAML" final="false" class="ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileIDP">
   <ResultCond name="ok" next="FetchSAMLAssertionAtSTS"/>
   <Response value="AUTH_ERROR">
      <Gui name="AuthErrorDialog"/>
   </Response>
   <property name="tokenType" value="saml" />
   <property name="result" value="${notes:ws-trust.token}" />
</AuthState>

Example(Kerberos ticket as token)

<AuthState name="WsFedKerberos" final="false" class="ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileIDP">
   <ResultCond name="ok" next="FetchKerberosTicket"/>
   <Response value="AUTH_ERROR">
      <Gui name="AuthErrorDialog"/>
   </Response>
   <property name="tokenType" value="kerberos" />
   <property name="result"
      value="${outargs:kerberos.apreq.HTTP/kerberos.service.host.com@DOMAIN}" />
</AuthState>

PassiveRequestorProfileSP

The PassiveRequestorProfileSP AuthState sends WS-Federation requests and consumes their responses. Typically, in an initial request, a security token is requested using WS-Federation by redirecting the client to the IDP. The handling of the secure token response is similar to that of the SecurityTokenServiceClient AuthState.

Description

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

Topic	Description
Class	ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileSP
Logging	wsfed
Auditing	none
Marker	EXTERNAL:WS-Federation
Methods	process (all events)

Properties

• idp (URL, -)

  URL of the trusted IDP, where the client is redirected to in an initial request.

• maxAge (integer, -1)

  Maximum age of a WS-Federation response in seconds. The wct parameter is validated against this parameter. A negative value disables this check.

• relayFromIdP (boolean, false)

  Set to true to propagate all WS-Federation input parameters received by a PassiveRequestorProfileIDP AuthState to the new WS-Federation request. This is used if a relying party IDP dispatches requests to the correct HomeRealm IDP of the user, so a PassiveRequestorProfileIDP AuthState and a PassiveRequestorProfileSP AuthState are configured in sequence.

• cleanup (boolean, false)

  Removes wa and wresult inargs after processing them. This is necessary if multiple PassiveRequestorProfileSP AuthStates are used in one configuration.

• passIfAuthenticated (boolean, false)

  If set to true, requests from users that are already authenticated are ignored if passIfAuthenticated="true". Thus, no redirect to the IDP is issued in this case.

• <any WS-Federation passive requestor profile property> (string, -)

  If the property relayFromIdP is true, the default is: "${sess:wsfed.in.<key>}" As with WS-Federation 1.2, the following properties may be used:

  • Basic parameters: "wa","wreply","wres","wctx","wp","wct","wfed","wencoding"
  • Request ST: "wtrealm","wfresh","wauth","wreq","whr","wreqptr"
  • Attribute and Pseudonym Request: "wattr","wattrptr","wresult","wresultptr","wpseudo","wpseudoptr"

  Output parameters are always UTF-8 URL-encoded. Note that many special properties of each of these parameters must be provided by other means, i.e., a correct wreqptr must be generated outside this AuthState.

• wa (string, "wsignin1.0")

  Mandatory WS-Federation action parameter, defaults to sign-in.

• wct (string, -)

  This must be an XML date. If set to "auto", the current time of the request is used.

Token

If the wa property has the value "wsignin1.0", and a wreply parameter is present, the token is processed. For a list of SecurityToken parameters, see chapter SecurityTokenServiceClient.

Input

• wa
• wreply
• wct

Possibly more via substitution as configured.

Transitions

• ContinueResponse

  Internal use only to render a redirect.

• wsignin1.0

  When a signin request (wa=wsignin1.0) is received.

• wsignoutcleanup1.0

  When a signout cleanup request (wa=wsignoutcleanup1.0) is received.

Output

The following OutArgs are used to render a redirect:

• nevis.transfer.type "redirect"
• nevis.transfer.destination target IDP

Errors

• lasterror=1

  lasterrorinfo=

Notes

none