Expand Minimize

WsRequestSecurityToken function

Get a security token from a security token service (STS) that acts as the token issuer in a federation scenario. This function is used on the client side, and performs the WS-Trust based negotiation steps with the STS until the security token is obtained or the negotiation process fails.

Syntax


HRESULT WINAPI  WsRequestSecurityToken(
  _In_      WS_CHANNEL* channel,
  const WS_REQUEST_SECURITY_TOKEN_PROPERTY* properties,
  _In_      ULONG propertyCount,
  WS_SECURITY_TOKEN** token,
  _In_opt_  const WS_ASYNC_CONTEXT* asyncContext,
  _In_opt_  WS_ERROR* error
);

Parameters

channel [in]

The channel on which the negotiation to obtain the security token should take place.

The supplied channel should have been created with the appropriate WS_SECURITY_DESCRIPTION to meet the security requirements of the issuer, and then opened to the WS_ENDPOINT_ADDRESS of the issuer. The caller is also responsible for closing and freeing the channel after the completion of this function.

Thus, the channel must be in state WS_CHANNEL_STATE_OPEN when this function is called. After a successful completion of this function, the channel will be in state WS_CHANNEL_STATE_OPEN. After a failed completion, it will either be in state WS_CHANNEL_STATE_OPEN or state WS_CHANNEL_STATE_FAULTED.

properties

An optional group of settings to be used in the negotiation process with the issuer.

propertyCount [in]

The number of items in the properties array.

token

The XML security token obtained. This is set upon successful completion of the function call, and is unmodified if any failure occurs during the execution of the function.

The returned security token may be used with WS_XML_TOKEN_MESSAGE_SECURITY_BINDING if it is to be presented to a service. The token must be freed using WsFreeSecurityToken when it is no longer needed.

asyncContext [in, optional]

Information on how to invoke the function asynchronously, or NULL if invoking synchronously.

error [in, optional]

Specifies where additional error information should be stored if the function fails.

Return value

This function can return one of these values.

Return codeDescription
WS_S_ASYNC

The asynchronous operation is still pending.

 

Remarks

Windows 7 and Windows Server 2008 R2: WWSAPI only supports Ws-Trust and Ws-SecureConversation as defined by Lightweight Web Services Security Profile (LWSSP). For details regarding Microsoft's implementation please see the MESSAGE Syntax section of LWSSP.

Requirements

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

WebServices.h

Library

WebServices.lib

DLL

WebServices.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft