Adding a Username Token

Adding a Username Token

To add a username token, do the following in your web client:

1. Optionally include the %soap.inc include file, which defines macros you might need to use.

2. Call the Create() class method of %SOAP.Security.UsernameTokenOpens in a new tab. For example:

    set user="SYSTEM"
    set pwd="_SYS" 
    set utoken=##class(%SOAP.Security.UsernameToken).Create(user,pwd)

   

   The method has an optional third argument (type), which specifies how to include the password in the username token. This must be one of the following:

   • $$$SOAPWSPasswordText — Include the password in plain text. This is the default.

   • $$$SOAPWSPasswordDigest — Do not include the password but instead include its digest. The digest, Nonce, and Created timestamp are derived as specified by WS-Security 1.1.

     Important:

     This option is available only for SOAP clients interacting with third-party servers that support it. PasswordDigest authentication requires the server to store the plain-text password, which is not acceptable in a modern security environment. The PasswordDigest algorithm should be considered a legacy feature. To protect the password in a <UsernameToken>, you should use SSL/TLS, encrypt the <UsernameToken>, or use some combination of these techniques.

   • $$$SOAPWSPasswordNone — Do not include the password.

   This method creates an instance of %SOAP.Security.UsernameTokenOpens in a new tab, sets its Username and Password properties, and returns the instance. This object represents the <UsernameToken> header element.

   Note:

   If you are using this procedure to create a <UsernameToken> needed by a policy created by the Studio wizard, you must use the default type, $$$SOAPWSPasswordText, because the wizard does not generate policies that use other token types. You can, however, manually create a policy that uses the HashPassword assertion (which would use the type $$$SOAPWSPasswordDigest).

3. Call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the %SOAP.Security.UsernameTokenOpens in a new tab instance you created. For example:

    do client.SecurityOut.AddSecurityElement(utoken)

   

4. Send the SOAP message. See the general comments in Adding Security Header Elements.