Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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.


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


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.


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.


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

The asynchronous operation is still pending.



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.


Minimum supported client

Windows 7 [desktop apps | UWP apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | UWP apps]









© 2018 Microsoft