Share via

How to: Obtain a Security Token From a Custom Security Token Service

  • Article

If you already have a Web service client project, added references to the Microsoft.Web.Services2 and System.Web.Services assemblies, added a Web reference to your Web service, modified the proxy class to derive from WebServicesClientProtocol, and added the appropriate using or Imports directives, skip to step 4.

To obtain a security context token from a security token service

  1. Open the Web service client project in Visual Studio .NET 2003.

  2. Add references to the Micrsosoft.Web.Services and System.Web.Services assemblies.

    1. In Solution Explorer, right-click References, and then click Add Reference.
    2. Click the .NET tab, select Microsoft.Web.Services2.dll, and then click Select.
    3. On the .NET tab, select System.Web.Services.dll, and then click Select.
    4. Click OK.

  3. Add the following Imports or using directives to the top of the file that communicates with the Web service.

    1. In Solution Explorer, right-click the file that contains the client code, and then click View Code.

    2. At the top of the file, add the following Imports or using directives:

      Imports Microsoft.Web.Services2
Imports Microsoft.Web.Services2.Security
Imports Microsoft.Web.Services2.Security.Tokens
Imports Microsoft.Web.Services2.Security.X509

      using Microsoft.Web.Services2;
using Microsoft.Web.Services2.Security;
using Microsoft.Web.Services2.Security.Tokens;
using Microsoft.Web.Services2.Security.X509;

  4. Get a security token to sign the security token request, which is known as a Request Security Token (RST).

    The security token used to sign the RST must also have the capability to encrypt SOAP messages. Because the security token used to sign the RST is also used by the security token service to encrypt the part of the response to the security token request that contains the key or entropy value that is used to construct the key for the issued security token.

    Exactly how to obtain the security token depends on the type of security token used to sign the RST.

    The following code example creates a new instance of a UsernameToken security token.

    Dim username as String = Environment.UserName
Dim passwordBytes As Byte() = GetPassword()
Dim passwordEquivalent As String = Convert.ToBase64String( _
  passwordBytes )
Dim token As SecurityToken = New UsernameToken(username, _
  passwordEquivalent, PasswordOption.SendHashed)

    string username = Environment.UserName;
byte[] passwordBytes = GetPassword();
string passwordEquivalent = Convert.ToBase64String( passwordBytes );
SecurityToken token = new UsernameToken( username, passwordEquivalent, PasswordOption.SendHashed );

  5. Create a new instance of the proxy class for security token services.

    In the constructor, specify the endpoint of the custom security token service. This is the same URI specified in the <add> Element for <httpHandlers> (WSE for Microsoft .NET) element within the Web.config file of the security token service that specifies the custom security token service.

    The following code example creates a new instance of the SecurityTokenServiceClient proxy class.

    Dim client As SecurityTokenServiceClient
client = New SecurityTokenServiceClient(New _
  Uri("http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx")

    SecurityTokenServiceClient client = new
  SecurityTokenServiceClient(new 
  Uri( "http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx"));

  6. Get the security token that is used to encrypt the client's entropy value. This security token, which is supplied by the custom security token service, typically contains the public key of an asymmetric key pair.

    The proxy classes that request a security token from a security token service have several overloads that specify whether to use entropy values or a proof token. By default, WSE uses entropy values. If entropy values are not used, this step is optional.

    The following code example calls a user-defined GetSecurityToken method to obtain an X.509 certificate. To implement the GetSecurityToken method, see How to: Sign a SOAP Message Using an X.509 Certificate.

    Dim issuerToken As X509SecurityToken = GetSecurityToken()
If (issuerToken Is Nothing) Then
   Throw New ApplicationException("No key provided for signature.")
End If

    X509SecurityToken issuerToken = GetSecurityToken();
if (issuerToken == null)
   throw new ApplicationException("No key provided for signature.");

  7. Request a security token from the custom security token service by calling the IssueSecurityToken method.

    Because the SecurityTokenServiceClient class can request multiple types of security tokens, you must specify the type of security token you are requesting. The token type is specified by a URI, which is the same URI that is used to specify the security token type in a SOAP message and that is specified in the <binarySecurityTokenManager> Element or <securityTokenManager> Element elements, when the custom security token is a custom binary or custom XML security token, respectively. This URI is passed to the constructor for the RequestSecurityToken class, which is the only parameter for the IssueSecurityToken method.

    The following code example requests that an XmlToken be issued from the http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx security token service.

    ' Create a new instance of the RequestSecurityToken class
' specifying the type of security token to request, the security
' token to sign the request, and the endpoint of the 
' security token service.
Dim rst As RequestSecurityToken
rst = New RequestSecurityToken( _
    "https://www.contoso.com/tokens/customXml#Token", _
    token, _
    "http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx")
client.RequestSigningToken = token
Dim response As RequestSecurityTokenResponse

' Request the security token.
response =client.IssueSecurityToken( rst )

' Get the issued security token from the response.
Dim issuedToken As XmlToken
issuedToken = response.RequestedSecurityToken.SecurityToken

    // Create a new instance of the ReqeustSecurityToken clas
// specifying the type of security token to request, the security
// token to sign the request, and the endpoint of the 
// security token service.
RequestSecurityToken rst;
rst = new RequestSecurityToken(
    "https://www.contoso.com/tokens/customXml#Token",
    token,
    "http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx");
client.RequestSigningToken = token;
RequestSecurityTokenResponse response;

// Request the security token.
response =client.IssueSecurityToken( rst );

// Get the issued security token from the response.
XmlToken issuedToken = response.RequestedSecurityToken.SecurityToken as XmlToken;

Example

The following code example demonstrates how to request a security context token from a security token service.

' Get a security token to sign the security token request sent to the
' security token service. 
Dim username as String = Environment.UserName
Dim passwordBytes As Byte() = GetPassword()
Dim passwordEquivalent As String = Convert.ToBase64String( _
  passwordBytes )
Dim token As SecurityToken = New UsernameToken(username, _
  passwordEquivalent, PasswordOption.SendHashed)

' Get the security token supplied by the security token service to
' encrypt the client's entropy value. The client's entropy value is 
' automatically generated by WSE.
' NOTE: The GetSecurityToken method is a user-defined method. This
' section of code uses the GetSecurityToken method defined in the 
' How to: Sign a SOAP Message By Using an X.509 Certificate topic.
Dim issuerToken As X509SecurityToken = GetSecurityToken()
If (issuerToken Is Nothing) Then
   Throw New ApplicationException("No key provided for signature.")
End If

' Create a new instance of the proxy class for the security token 
' service that issues security tokens.
Dim client As SecurityTokenServiceClient
client = New SecurityTokenServiceClient(New _
  Uri("http://www.cohowinery/TokenIssuingService/secureConversation.asmx")

' Create a new instance of the ReqeustSecurityToken clas
' specifying the type of security token to request, the security
' token to sign the request, and the endpoint of the 
' security token service.
Dim rst As RequestSecurityToken
rst = New RequestSecurityToken( _
    "https://www.contoso.com/tokens/customXml#Token", _
    token, _
    "http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx")
client.RequestSigningToken = token
Dim response As RequestSecurityTokenResponse

' Request the security token.
response =client.IssueSecurityToken( rst )

' Get the issued security token from the response.
Dim issuedToken As XmlToken
issuedToken = response.RequestedSecurityToken.SecurityToken

// Get a security token to sign the SOAP message sent to the
// security token service. 
string username = Environment.UserName;
byte[] passwordBytes = GetPassword();
string passwordEquivalent = Convert.ToBase64String( passwordBytes );
SecurityToken token = new UsernameToken( username, passwordEquivalent, PasswordOption.SendHashed );

// Get the security token supplied by the security token service to
// encrypt the client's entropy value. The client's entropy value is 
// automatically generated by WSE.
// NOTE: The GetSecurityToken method is a user-defined method. This
// section of code uses the GetSecurityToken method defined in the 
// How to: Sign a SOAP Message By Using an X.509 Certificate topic.
X509SecurityToken issuerToken = GetSecurityToken();
if (issuerToken == null)
   throw new ApplicationException("No key provided for signature.");

// Create a new instance of the proxy class for the security token 
// service.
SecurityTokenServiceClient client = new
  SecurityTokenServiceClient(new 
  Uri( "http://www.cohowinery/TokenIssuingService/secureConversation.asmx"));

// Create a new instance of the ReqeustSecurityToken clas
// specifying the type of security token to request, the security
// token to sign the request, and the endpoint of the 
// security token service.
RequestSecurityToken rst;
rst = new RequestSecurityToken(
    "https://www.contoso.com/tokens/customXml#Token",
    token,
    "http://www.cohowinery/TokenIssuingService/customSecurityTokenService.ashx");
client.RequestSigningToken = token;
RequestSecurityTokenResponse response;

// Request the security token.
response =client.IssueSecurityToken( rst );

// Get the issued security token from the response.
XmlToken issuedToken = response.RequestedSecurityToken.SecurityToken as XmlToken;

See Also

Tasks

How to: Configure a Custom Security Token Service

Reference

SecurityTokenServiceClient Class
RequestSecurityToken Class

Other Resources

Issuing Security Tokens