The WS-Security policy file (WSSE file) defines the security policy applied to the SOAP messages that pass between web services and their clients. Three security mechanisms can be defined in a WSSE file: (1) security tokens, (2) digital signatures, and (3) encryption.
Incoming secured SOAP messages are first processed by WebLogic Workshop in accordance with the WSSE file. If the incoming SOAP message passes the security regimen defined in the WSSE file, then the message is passed to the target web service or control for normal processing.
Outgoing SOAP messages are first secured by WebLogic Workshop according to the policy defined in the WSSE file before they are sent out over the wire. That is, outgoing SOAP messages are enhanced with any security tokens, signatures, and encryption specified in the WSSE file before they are sent.
<wsSecurityPolicy>
<wsSecurityIn>
<token>
<encryptionRequired>
<decryptionKey>
<alias>
<password>
<signatureRequired>
<wsSecurityOut>
<userNameToken>
<userName>
<password>
<encryption>
<encryptionKey>
<alias>
<x509Certificate>
<useInboundSignatureCertificate>
<signatureKey>
<alias>
<password>
<additionalSignedElements>
<secureElement>
<additionalEncryptedElements>
<secureElement>
<keyStore>
<keyStoreLocation>
<keyStorePassword>
The top level element within a Web Service Security file (WSSE file). Describes the web service security policy for a request/response pair.
<wsSecurityPolicy
xmlns="nameSpace" >
Attribute | Description |
---|---|
xmlns |
Specifies the name space for the WSSE policy file. |
Parents: none.
Children: <wsSecurityIn>, <wsSecurityOut>, <keyStore>.<wsSecurityPolicy>
<wsSecurityIn>
<wsSecurityIn>
<!--
Elements that describe the security regimen to be applied to incoming SOAP messages.
--> </wsSecurityIn>
Parents: <wsSecurityPolicy>.
Children: <token>, <signaturedRequired>, <encryptionRequired>.<wsSecurityPolicy>
<wsSecurityIn>
<token>
<token
tokenType="username"
>
Attribute | Description |
---|---|
tokenType |
Required string. It has one valid value: "username". When this element is present, a username/password token must be present in inbound SOAP messages. The username/password must successfully match a principal known to WebLogic Server. |
Parents: <wsSecurityIn>.
Children: none.When this element is present, inbound SOAP messages must be encrypted. This element must be accompanied by a <decryptionKey> child element.
<encryptionRequired>
<!--
Contains information for decrypting the incoming encrypted SOAP message.
--> </encryptionRequired>
Parents: <wsSecurityIn>.
Children: <decryptionKey>.
This element contains information to resolve the decryption key pair. The private key is used to decrypt the incoming message. The public key (contained within the X509 Digital Certificate) is put into the WSDL so that clients of the web service can use it to encrypt SOAP messages.
The child elements, <alias> and <password> are provided for access to the private key.
<wsSecurityPolicy>
<wsSecurityIn>
<encryptionRequired>
<decryptionKey>
<alias>
<password>
<decryptionKey>
<!--
Information for retrieving the private key from the keystore.
-->
</decryptionKey>
Parents: <encryptionRequired>.
Children: <alias>, <password>.Specifies the alias used to look up the private key (or key pair) in the keystore.
<wsSecurityPolicy>
<wsSecurityIn>
<encryptionRequired>
<decryptionKey>
<alias>
<alias> stringAlias </alias>
Parents: <decryptionKey>
Children: none.
This element specifies the password used to look up the private key in the keystore. (Note this element does not have the same syntax as the <password> element used as the child of the <userNameToken> element.)
Note: Passwords appear in plain text in the WSSE policy file. For tools to encrypt these passwords, see Securing WS-Security Passwords.
<wsSecurityPolicy>
<wsSecurityIn>
<encryptionRequired>
<decryptionKey>
<password>
<password> stringPassword </password>
Parents: <decryptionKey>.
Children: none.
Takes boolean values. If this the value of this element is true, then inbound SOAP messages are expected to be signed.
<wsSecurityPolicy>
<wsSecurityIn>
<signatureRequired>
<signaturedRequired> boolean </signaturedRequired>
Parents: <wsSecurityIn>
Children: none.
This element defines how outgoing SOAP messages should be secured before they are sent out over the wire. Three security enhancements can be applied to outgoing messages: (1) security tokens (see the <userNameToken> element), (2) digital signature (see the <signatureKey> element), and (3) encryption (see the <encryption> element).
<wsSecurityPolicy>
<wsSecurityOut>
<userNameToken>
<encryption>
<signatureKey>
<additionalSignedElements>
<additionalEncryptedElements>
<wsSecurityOut> <!-- Children elements that describe how to enhance outbound SOAP messages. --> </wsSecurityOut>
Parents: <wsSecurityPolicy>
Children: <userNameToken>, <encryption>, <signatureKey>, <additionalSignedElements>, <additionalEncryptedElements>
When this element is present, outbound SOAP messages are enhanced with a username and password token. This element must have two children elements: <userName> and <password>.
<wsSecurityPolicy>
<wsSecurityOut>
<userNameToken>
<userNameToken> <!-- Children elements specifying the username and password to include with the outbound SOAP message --> </userNameToken>
Parents: <wsSecurityOut>.
Children: <userName>, <password>.
Takes String values. The String must correspond to a username in the security realm associated with the web service's running WebLogic Server domain.
<wsSecurityPolicy>
<wsSecurityOut>
<userNameToken>
<userName>
<userName> stringUserName </userName>
Parents: <userNameToken>
Children: none.
This password must be the correct password of the user in the security realm associated with the web service's running WebLogic Domain.
Note: Passwords appear in plain text in the WSSE policy file. For tools to encrypt these passwords, see Securing WS-Security Passwords.
<wsSecurityPolicy>
<wsSecurityOut>
<userNameToken>
<password>
Attribute | Description |
---|---|
type |
Required string. There is one valid value: "TEXT". |
<password> stringPassword </password>
Parents: <userNameToken>.
Children: none.
If this element is present then the body of the SOAP message will be encrypted on the way out. The SOAP recipient's public key used for encryption can be designated by directly providing the public key or using the public key that was provided for the inbound Signature (assuming that there is a previous inbound SOAP message containing a digital signature). The <encryption> element must have the child element <encryptionKey> or <useInboundSignatureCertificate>.
To sign elements in the SOAP header, see <additionalEncryptedElements>.
<wsSecurityPolicy>
<wsSecurityOut>
<encryption>
<encryptionKey>
<useInboundSignatureCertificate>
<encryption> <!-- Child elements specifying how to encrypt the outbound SOAP message. --> </encryption>
Parents: <wsSecurityOut>
Children: <encryptionKey>, <useInboundSignatureCertificate>
This is the key used to encrypt the outbound SOAP message. In the case where the web service control is initiating a conversation with another web service the x509Certificate may have been initially created from the target web service's WSDL file.
<wsSecurityPolicy>
<wsSecurityOut>
<encryption>
<encryptionKey>
<encryptionKey>
<!--
Child element specifying either that the public key should be retrieved from the keystore, or from a x509 cert.
-->
</encryptionKey>
Parents: <encryption>
Children: <alias>, <x509Certificate>.
Specifies the alias used to look up the public key in the keystore when retrieving a key for encryption of outbound SOAP messages.
<wsSecurityPolicy>
<wsSecurityOut>
<encryption>
<encryptionKey>
<alias>
<alias> stringAilas </alias>
Parents: <encryptionKey>.
Children: none.
Specifies the base64 encoded X509 certificate for the purpose of the retrieving the public key from it.
<wsSecurityPolicy>
<wsSecurityOut>
<encryption>
<encryptionKey>
<x509Certificate>
<x509Certificate> base64EncodedCert </x509Certificate>
Parents: <encryptionKey>.
Children: none.
Specifies that outbound SOAP message should be encrypted with the public key in the inbound SOAP message's x509 certificate. If this element is omitted the value is false.
<wsSecurityPolicy>
<wsSecurityOut>
<encryption>
<useInboundSignatureCertificate>
<useInboundSignatureCertificate> boolean </useInboundSignatureCertificate>
Parents: <encryption>.
Children: none.
This element is used to designate the private key that will be used for signing. This keypair should also have a certificate associated with so that the validation certificate can be added to the message. If this element is present, only the SOAP body is signed. To sign header elements, see <addtionalSignedElements>.
<wsSecurityPolicy>
<wsSecurityOut>
<signatureKey>
<alias>
<password>
<signatureKey> <!-- Child elements specifying the alias and password used to retrieve the signing private key from the keystore. --> </signatureKey>
Parents: <wsSecurityOut>.
Children: <alias>, <password>.
This alias is used to look up the private key (or key pair) in the keystore.
<wsSecurityPolicy>
<wsSecurityOut>
<signatureKey>
<alias>
<alias> stringAlias </alias>
Parents: <signatureKey>.
Children: none.
The password associated with the alias used to retrieve the private key from the keystore.
Note: Passwords appear in plain text in the WSSE policy file. For tools to encrypt these passwords, see Securing WS-Security Passwords.
<wsSecurityPolicy>
<wsSecurityOut>
<signatureKey>
<password>
<password> stringPassword </password>
Parents: <signatureKey>.
Children: none.
Contains namespace and element pairs that need to be secured. Note that only the SOAP body is signed, if a signature is called for by a <signatureKey> element. <additionalSignedElements> is used to specify SOAP header elements for signing.
<wsSecurityPolicy>
<wsSecurityOut>
<additionalSignedElements>
<secureElement>
<additionalSignedElements> <!-- Child elements listing the elements to be signed. -->
</additionalSignedElements>
Parents: <wsSecurityOut>.
Children: <secureElement>.
Specifies an element to be signed.
Attribute | Description |
---|---|
name | Required string. Names an XML element to be signed. |
nameSpace |
Required string. Any URI value. |
<wsSecurityPolicy>
<wsSecurityOut>
<additionalSignedElements>
<secureElement>
<secureElement name="stringName" nameSpace="stringURI" >
Parents: <additionalSignedElements>.
Children: none.
Specifies an element to be encrypted. Note that the <encryption> element encrypts only the SOAP body by default. Use <additionalEncryptedElements> to encrypt sensitive elements in the SOAP header.
<wsSecurityPolicy>
<wsSecurityOut>
<additionalEncryptedElements>
<secureElement>
<additionalEncryptedElements> <!-- Child elements listing the elements to be encrypted. -->
</additionalEncryptedElements>
Parents: <wsSecurityOut>.
Children: <secureElement>.
Specifies an element to be encrypted.
Attribute | Description |
---|---|
name | Required string. Names an XML element to be encrypted. |
nameSpace |
Required string. Any URI value. |
<wsSecurityPolicy>
<wsSecurityOut>
<additionalEncryptedElements>
<secureElement>
<secureElement name="stringName" nameSpace="stringURI" >
Parents: <additionalEncryptedElements>.
Children: none.
This element is optional. If a keystore is not designated then Weblogic Server's default keystore is used. If present, the <keyStore> element must have the child elements <keyStoreLocation> and <keyStorePassword>.
<wsSecurityPolicy>
<keyStore>
<keyStoreLocation>
<keyStorePassword>
<keyStore> <!-- Child elements specifying the keystore location and password. -->
</keyStore>
Parents: <wsSecurityPolicy>.
Children: <keyStoreLocation>, <keyStorePassword>.
The <keyStoreLocation> element specifies the path to the keystore. An absolute path or relative path can be designated. If a relative path is used then the base directory is the active Weblogic Server domain directory (e.g., BEA_HOME\weblogic81\samples\domains\workshop is the samples domain directory).
<wsSecurityPolicy>
<keyStore>
<keyStoreLocation>
<keyStoreLocation> stringPath </keyStoreLocation>
Parents: <keyStore>.
Children: none.
The <keyStorePassword> specifies the password required to access the keystore.
Note: Passwords appear in plain text in the WSSE policy file. For tools to encrypt these passwords, see Securing WS-Security Passwords.
<wsSecurityPolicy>
<keyStore>
<keyStorePassword>
<keyStorePassword> stringPassword </keyStorePassword>
Parents: <keyStore>.
Children: none.
The following WSSE policy file requires that inbound SOAP messages must be encrypted.
<wsSecurityPolicy xsi:schemaLocation="WSSecurity-policy.xsd" xmlns="http://www.bea.com/2003/03/wsse/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsSecurityIn> <encryptionRequired> <decryptionKey> <alias>companyB</alias> <password>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</password> </decryptionKey> </encryptionRequired> </wsSecurityIn> <keyStore> <keyStoreLocation>wlwwsse.jks</keyStoreLocation> <keyStorePassword>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</keyStorePassword> </keyStore> </wsSecurityPolicy>
The following WSSE policy file requires that inbound SOAP messages include a username token and be encrypted. Outbound messages are encrypted before they are sent out over the wire.
<wsSecurityPolicy xsi:schemaLocation="WSSecurity-policy.xsd" xmlns="http://www.bea.com/2003/03/wsse/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsSecurityIn> <token tokenType="username"/> <encryptionRequired> <decryptionKey> <alias>companyB</alias> <password>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</password> </decryptionKey> </encryptionRequired> <signatureRequired>true</signatureRequired> </wsSecurityIn> <wsSecurityOut> <encryption> <encryptionKey> <alias>companyB</alias> </encryptionKey> </encryption> </wsSecurityOut> <keyStore> <keyStoreLocation>wlwwsse.jks</keyStoreLocation> <keyStorePassword>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</keyStorePassword> </keyStore> </wsSecurityPolicy>
The following WSSE policy file requires that inbound SOAP messages include a (1) username/password token, (2) a signature, and (3) be encrypted.
<wsSecurityPolicy xsi:schemaLocation="WSSecurity-policy.xsd" xmlns="http://www.bea.com/2003/03/wsse/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsSecurityIn> <token tokenType="username"/> <encryptionRequired> <decryptionKey> <alias>companyB</alias> <password>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</password> </decryptionKey> </encryptionRequired> <signatureRequired>true</signatureRequired> </wsSecurityIn> <keyStore> <keyStoreLocation>wlwwsse.jks</keyStoreLocation> <keyStorePassword>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</keyStorePassword> </keyStore> </wsSecurityPolicy>
The <encryption> element directs that the body of outgoing SOAP messages be encrypted and, additionally, the <additionalEncrptedElements> element directs that the <person> element in the SOAP header be encrypted.
<wsSecurityPolicy xsi:schemaLocation="WSSecurity-policy.xsd" xmlns="http://www.bea.com/2003/03/wsse/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsSecurityOut> <encryption> <encryptionKey> <alias>companyB</alias> </encryptionKey> </encryption> <additionalEncryptedElements> <secureElement name="person" namespace="http://www.bea.com/person"/> </additionalEncryptedElements> </wsSecurityOut> <keyStore> <keyStoreLocation>wlwwsse.jks</keyStoreLocation> <keyStorePassword>{3DES}OZyVt5STUU8BMMJLPGSkYQ==</keyStorePassword> </keyStore> </wsSecurityPolicy>