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.

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 describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileIDP
Logging	wsfed
Auditing	none
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 ") 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 AuthStatesFrontendKerberosAuthStateorBackendKerberosAuthState") fetch a Kerberos ticket for usage as authentication token, you have to configure the following properties: For token type "response", the default value for the result property is "${notes:ws-trust.response}". Thus is the location where the SecurityTokenServiceClient AuthState ") 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. Anywtrealmstring 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.
Methods	process (all events)
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.
OutArgs	wsfed.cleanupURLs (string)Comma-separated list of signout URLs to call in single signout scenario.
Output	none
Errors	wa.unknown: The resource redirected the client to the IP/STS with a bad request. The wa action is unknown.
Notes	none

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 describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.wsfed.PassiveRequestorProfileSP
Logging	wsfed
Auditing	none
Marker	EXTERNAL:WS-Federation
Properties (generic)	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.
Properties(parameters)	<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 correctwreqptr* must be generated outside of 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.
Properties".
Methods	process (all events)
Input	wawreplywctPossibly 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>