Security tokens and encryption

The WS-Security specification lets you place security credentials in the actual SOAP message. You accomplish this by instructing a client to obtain security credentials from a source that is trusted by both the sender and receiver. When a SOAP message sender sends a request, those security credentials, known as security tokens, are placed in the SOAP message. When the web server receives the SOAP request, it does not need to send additional requests to verify the integrity of the sender. The server verifies that the credentials are authentic before letting the Web Service execute the application. By not having to go back to the source of the credentials, this significantly improves the application's scalability.

To further secure Web Services, it is common to use digital signatures or encryption for the SOAP messages. Digitally signing a SOAP message verifies that the message has not been altered during transmission. Encrypting a SOAP message helps secure a Web Service by making it difficult for anyone other than the intended recipient to read the contents of the message.

The Web Services security mechanism associates security tokens with messages. This mechanism supports several security token formats to accommodate a variety of authentication requirements. For example, a client might need to provide a proof of identity or a security certificate.

To support WS-Security, VuGen allows you to create security tokens for your script. You can create multiple tokens and set their properties. After creating a token, you use it to sign or encrypt a SOAP message.

In certain instances, you do not send the token explicitly—you use the token for the purpose of signatures or encryption, without including the actual token in the SOAP envelope header. Using the Security Token option, you can indicate whether to send the actual token explicitly.

Available Security Tokens

The available tokens are Username and Password, X.509 Certificate, Kerberos, Kerberos2, and PFX File. The information you need to provide differs for each token.

  • UserName Token. The UserNametoken contains user identification information for the purpose of authentication: User Name and Password.

    You can also specify Password Options, indicating how to send the password to the server for authentication: SendPlainText, SendNone, or SendHashed.

  • X.509 Certificate Token. This security token is a token based on an X.509 certificate. To obtain a certificate, you can either purchase it from a certificate authority, such as VeriSign, Inc. or set up your own certificate service to issue a certificate. Most Windows servers support the public key infrastructure (PKI) which enable you to create certificates. You can then have it signed by a certificate authority or use an unsigned certificate.

    When you add an X.509 token to the Vuser script, you specify the Token Name, Certificate, and Reference type. The Browse button opens the Select Certificate dialog box which allows you to find a certificate from a Windows store.

  • Kerberos / Kerberos2 Tokens. (for Windows 2003 or XP SP1 and later) The Kerberos protocol is used to mutually authenticate users and services on an open and unsecured network. Using shared secret keys, it encrypts and signs user credentials. A third party, known as a KDC (Kerberos Key Distribution Center), authenticates the credentials. After authentication, the user may request a service ticket to access one or more services on the network. The ticket includes the encrypted, authenticated identity of the user. The tickets are obtained using the current user's credentials.

    VuGen supports tokens based on both Kerberos and Kerberos2 security tokens. The primary difference between the Kerberos and Kerberos2 tokens is that Kerberos2 uses the Security Support Provider Interface (SSPI), so it does not require elevated privileges to impersonate the client's identity. In addition, the Kerberos2 security token can be used to secure SOAP messages sent to a Web Service running in a web farm.

    When you add a Kerberos token to the Vuser script, you specify a logical Token Name for the token along with the Host and Domain names of the Web Services machine.

  • PFX File Token. These Personal Information Exchange token files (with .pfx or .p12 extensions) contain all of the token information, including the server certificate, intermediate certificates, and the private key in a single file. This file uses the PKCS#12 (Personal Information Exchange Syntax) standard. Click the Browse button to locate the file.

    Tip: If you have a JKS keystore (.jks file), VuGen automatically converts it to a .p12 file.

For details about the token attribute in the script, see the Function Reference (select the relevant version).

Adding the Security Policy

To add a security policy to a section of your script, you enclose the relevant steps with Web Service Set Security and Web Service Cancel Security steps.

When you add a Web Services Set Security step to your script, VuGen adds a web_service_set_security function that contains arguments with the tokens, message signatures, and encryption that you defined.

web_service_set_security(
   SECURITY_TOKEN, "Type=USERNAME", "TokenName=mytoken1",    "UserName=bob", "Password=123", "PasswordOptions=SendNone",    "Add=True", LAST);

Parameterization is not supported for the following arguments: Token Type, Logical Name, Base Token, Issuer Token or Derive From arguments.

Working with Message Signatures and Encrypted Data

When you add a security token to a SOAP message, it is added to the SOAP message in the form of an XML element in the WS-Security SOAP header.

The message, however, is exposed and therefore requires additional security. This is especially true when the credentials, including the password, are sent in plain text as it is with role-based security.

The two methods used to secure the data are digital signatures and encryption.

  • Digital Signatures. Digital Signatures are used by message recipients to verify that messages were not altered since their signing. The digital signature is usually in the form of XML within the SOAP message. The recipient checks the signature to make sure it is valid. Certain environments, such as WSE, automatically verify the signature on the SOAP recipient's computer.

  • Encryption. Although the XML digital signature offers a mechanism for verifying that the message has not been altered since it was signed, it does not encrypt the SOAP message—the message is still plain text in XML format. To secure the message in order that it should not be exposed, you encrypt it, making it difficult for an intruder to view and obtain a user's password.

Parameterization is not supported for message signatures and encryption arguments. For details on adding message signatures and encryption to your script, see Add security to a Web Service script.

Back to top