WsRequestSecurityToken function (webservices.h)
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 WsRequestSecurityToken(
[in] WS_CHANNEL *channel,
const WS_REQUEST_SECURITY_TOKEN_PROPERTY *properties,
[in] ULONG propertyCount,
WS_SECURITY_TOKEN **token,
[in, optional] const WS_ASYNC_CONTEXT *asyncContext,
[in, optional] WS_ERROR *error
);
Parameters
[in] channel
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.
[in] propertyCount
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.
[in, optional] asyncContext
Information on how to invoke the function asynchronously, or NULL if invoking synchronously.
[in, optional] error
Specifies where additional error information should be stored if the function fails.
Return value
This function can return one of these values.
Return code | Description |
---|---|
|
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
Requirement | Value |
---|---|
Minimum supported client | Windows 7 [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2008 R2 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | webservices.h |
Library | WebServices.lib |
DLL | WebServices.dll |