Salesforce Docs Portal

WS-Security Policy

Policy Name

WS-Security

Summary

Validates Web Services Security (WS-Security) UsernameToken credentials, XML signatures, or both on inbound SOAP requests

Category

Security

First Omni Gateway version available

v1.14.0

Release Notes

WS-Security Policy

Returned Status Codes

400 - SOAP 1.2 sender fault: malformed request, unsupported or untrusted signature, or failed authentication

500 - SOAP 1.1 sender fault: malformed request, unsupported or untrusted signature, or failed authentication

500 - Server fault: API contracts aren’t available yet, so Omni Gateway can’t authenticate the UsernameToken

Summary

The WS-Security Policy policy supports only WSDL (SOAP 1.1 and 1.2) APIs.

The Web Services Security (WS-Security) policy protects a SOAP service by validating the <wsse:Security> header of each inbound request. You can enable either or both of these controls:

  • UsernameToken validation: Authenticates the <wsse:UsernameToken> against the client applications that have contracts with the API. The username is the client ID, and the password is the client secret.

  • XML signature validation: Verifies the <ds:Signature> in the Security header and confirms that the signing X.509 certificate chains to a certificate authority (CA) that you trust.

The WS-Security Policy policy is fail-closed. Every enabled control must succeed before Omni Gateway forwards the request to the upstream service. Omni Gateway forwards the original headers and body unchanged, and doesn’t modify responses. When a check fails, Omni Gateway returns a WS-Security SOAP fault, and the request never reaches the upstream service.

The policy accepts plain SOAP requests with a text/xml or application/soap+xml content type, and multipart SOAP requests with a multipart/related content type, such as MTOM/XOP and SOAP with Attachments (SwA).

  • To validate UsernameTokens, client applications must have a contract with the API. For more information, see Approve or Reject Access Requests.

  • To validate XML signatures, get the PEM-encoded certificates of the CAs that issue your client signing certificates.

Configure WS-Security Policy Parameters

Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

Because UsernameToken validation requires API contracts that are only available for Managed Gateway or Connected Mode, Local Mode only supports XML signature validation. To use the policy in local mode, you must set validateUsernameToken to false.

- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: <boolean> // REQUIRED, set to false in Local Mode
    validateSignature: <boolean> // OPTIONAL, default: true
    trustAnchors: <string> // REQUIRED when validateSignature is true
Parameter Required or Optional Default Value Description

validateUsernameToken

Required

false

Authenticates the UsernameToken username and PasswordText password against Anypoint Platform API contracts. Set to false in Local Mode, which doesn’t have API contracts.

validateSignature

Optional

true

Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires trustAnchors.

trustAnchors

Required when validateSignature is true

None

One to sixteen PEM-encoded X.509 CA certificates that the signing certificate must chain to. To specify more than one CA, concatenate the PEM blocks. Omni Gateway doesn’t use the operating system trust store.

Omni Gateway rejects a trustAnchors value that is empty, is malformed PEM, contains more than sixteen certificates, contains a certificate larger than 16 KiB, or has trailing data after a certificate.

Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

Field Description Default Value Required

Validate UsernameToken

Authenticates the UsernameToken username and PasswordText password against Anypoint Platform API contracts. Enable either this field or Validate XML Signature.

Enabled

No

Validate XML Signature

Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires Trust Anchors (PEM).

Enabled

No

Trust Anchors (PEM)

One or more PEM-encoded X.509 CA certificates that the signing certificate must chain to.

None

Required when Validate XML Signature is enabled

WS-Security Policy Configuration Examples

Examples that enable validateUsernameToken are only valid for Managed Gateway or Connected Mode.

This example enables both controls:

- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: true
    validateSignature: true
    trustAnchors: |
      -----BEGIN CERTIFICATE-----
      MIID...issuing-or-root-CA...
      -----END CERTIFICATE-----

This example enables only UsernameToken validation. The policy doesn’t require, inspect, or trust an XML signature:

- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: true
    validateSignature: false

This example enables only XML Signature validation. The signature must cover the Timestamp. The policy doesn’t require or authenticate a UsernameToken:

- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: false
    validateSignature: true
    trustAnchors: |
      -----BEGIN CERTIFICATE-----
      MIID...issuing-or-root-CA...
      -----END CERTIFICATE-----

How the WS-Security Policy Works

Omni Gateway applies these checks in order. The first check that fails determines the fault that Omni Gateway returns:

  1. Content type: The request must use text/xml, application/soap+xml, or multipart/related. For a multipart request, Omni Gateway selects the root part, which is the part whose Content-ID matches the start parameter, or the first part when start is absent. The root part must use 7bit, 8bit, or binary Content-Transfer-Encoding, or omit the header. The policy validates only the SOAP envelope in the root part and forwards attachments to the upstream service without inspecting them.

  2. SOAP envelope: The envelope must be a single well-formed SOAP 1.1 or SOAP 1.2 document with no <!DOCTYPE> declaration.

  3. Security header: The SOAP <Header> must contain exactly one direct <wsse:Security> child. The policy ignores the SOAP 1.1 actor and SOAP 1.2 role attributes.

  4. Required elements: The Security header must contain exactly one of each element that the enabled controls require. The Security header must not contain XML Encryption elements.

  5. Signature algorithms: If XML Signature validation is enabled, the signature must use the supported algorithms, and its KeyInfo must reference an X.509 <wsse:BinarySecurityToken> in the same Security header.

  6. Certificate trust: If XML Signature validation is enabled, the signing certificate must chain to a configured trust anchor.

  7. Signature verification: If XML Signature validation is enabled, the signature and every reference digest must verify, and the signed references must cover the Timestamp. When UsernameToken validation is also enabled, the signed references must also cover the UsernameToken. The SOAP Body doesn’t need to be signed, but if the signature references the Body, Omni Gateway verifies it.

  8. UsernameToken authentication: If UsernameToken validation is enabled, the username and password must match the client ID and client secret of an API contract. Omni Gateway applies Unicode NFC normalization to the username before the lookup.

    The password must be PasswordText. If the <wsse:Password> element has no Type attribute, Omni Gateway treats the password as PasswordText. Omni Gateway always rejects PasswordDigest, because it can’t recompute the digest without the client secret in clear text.

Supported Algorithms

The WS-Security Policy supports only these algorithms. It rejects a signature that uses any other algorithm:

Purpose Algorithm

Signature

RSA-SHA256 (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256)

Canonicalization

Exclusive XML Canonicalization without comments (http://www.w3.org/2001/10/xml-exc-c14n#)

Reference digest

SHA-256 (http://www.w3.org/2001/04/xmlenc#sha256)

The <ds:KeyInfo> element must reference the signing <wsse:BinarySecurityToken> by its wsu:Id. The policy rejects other KeyInfo forms, X509PKIPathv1 and PKCS7 tokens, external references, and attachment signature transforms.

WS-Security Policy Certificate Requirements

The signing certificate must meet these requirements:

  • It’s a base64-encoded DER X.509 v3 certificate of up to 16 KiB, with an RSA key of 2048 to 4096 bits.

  • It chains to a configured trust anchor through at most eight issuer certificates. The request can include intermediate CA certificates as additional <wsse:BinarySecurityToken> elements in the same Security header.

  • Every certificate in the chain is valid at the time of the request, and every issuer is a CA certificate.

The policy doesn’t check certificate revocation or key usage.

Principal Propagation

When UsernameToken validation is enabled and every enabled check succeeds, the WS-Security Policy publishes the matched contract identity so that policies later in the chain can use it:

  • principal and client_id: The client ID of the matched contract.

  • client_name: The name of the client application.

  • sla-tier-id and sla-tier-name properties: The SLA tier of the contract, when the contract has one.

The policy doesn’t publish the client secret or any certificate or signature data. Rejected requests don’t change the authentication data.

When only XML Signature validation is enabled, the policy doesn’t publish an identity.

When both controls are enabled, a valid signature proves that a trusted signer protected the UsernameToken, but it doesn’t bind the signing certificate to the client. Any certificate that chains to a configured trust anchor can sign a UsernameToken for any client ID. The policy authenticates the client ID and client secret separately against Anypoint API contracts.

Request Example

This SOAP 1.1 request carries a signing certificate, a signed Timestamp, a UsernameToken, and a signature that covers both the Timestamp and the UsernameToken:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
               xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
               xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <soap:Header>
    <wsse:Security>
      <wsse:BinarySecurityToken wsu:Id="X509-signing-cert"
          ValueType="...#X509v3" EncodingType="...#Base64Binary">MIIB...leaf-cert...</wsse:BinarySecurityToken>
      <wsu:Timestamp wsu:Id="TS-1">
        <wsu:Created>2026-09-30T12:00:00Z</wsu:Created>
        <wsu:Expires>2026-09-30T12:05:00Z</wsu:Expires>
      </wsu:Timestamp>
      <wsse:UsernameToken wsu:Id="UT-1">
        <wsse:Username>contract-client-id</wsse:Username>
        <wsse:Password Type="...#PasswordText">contract-client-secret</wsse:Password>
      </wsse:UsernameToken>
      <ds:Signature><!-- RSA-SHA256 signature that references #TS-1 and #UT-1 --></ds:Signature>
    </wsse:Security>
  </soap:Header>
  <soap:Body><!-- application payload --></soap:Body>
</soap:Envelope>

With both controls enabled, Omni Gateway forwards this request when the certificate chains to a configured trust anchor, the signature verifies over TS-1 and UT-1, and the UsernameToken matches an API contract.

See Also