---
schema_version: "1"
id: 1079b7049dc9ac47ff96b0755ae649079ef9f2c8451db669d4a7101accb38f6f
title: WS-Security Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-web-services-security.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-web-services-security
source_site: docs.mulesoft.com
content_type: documentation
content_hash: b50fe0823a51b4d1d5503356fff1f58cc7b18f063cb8b9f44ac8873ad4cbd8cb
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: web services security, ws-security, wss, usernametoken, xml signature, x.509, soap, wsdl, authentication, api gateway, flex gateway, gateway, policy
---

# WS-Security Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>WS-Security</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Web Services Security (WS-Security) UsernameToken credentials, XML signatures, or both on inbound SOAP requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security Policy</a></p></td></tr><tr><td rowspan="3"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - SOAP 1.2 sender fault: malformed request, unsupported or untrusted signature, or failed authentication</p></td></tr><tr><td><p>500 - SOAP 1.1 sender fault: malformed request, unsupported or untrusted signature, or failed authentication</p></td></tr><tr><td><p>500 - Server fault: API contracts aren’t available yet, so Omni Gateway can’t authenticate the UsernameToken</p></td></tr></tbody></table>

## Summary

> [!NOTE] 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](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task).

- 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

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>validateUsernameToken</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Authenticates the UsernameToken username and <code>PasswordText</code> password against Anypoint Platform API contracts. Set to <code>false</code> in Local Mode, which doesn’t have API contracts.</p></div></div></td></tr><tr><td><div><div><p><code>validateSignature</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires <code>trustAnchors</code>.</p></div></div></td></tr><tr><td><div><div><p><code>trustAnchors</code></p></div></div></td><td><div><div><p>Required when <code>validateSignature</code> is <code>true</code></p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>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.</p></div><div><p>Omni Gateway rejects a <code>trustAnchors</code> 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.</p></div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

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

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Validate UsernameToken</p></div></div></td><td><div><div><p>Authenticates the UsernameToken username and <code>PasswordText</code> password against Anypoint Platform API contracts. Enable either this field or <strong>Validate XML Signature</strong>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Validate XML Signature</p></div></div></td><td><div><div><p>Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires <strong>Trust Anchors (PEM)</strong>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Trust Anchors (PEM)</p></div></div></td><td><div><div><p>One or more PEM-encoded X.509 CA certificates that the signing certificate must chain to.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Required when <strong>Validate XML Signature</strong> is enabled</p></div></div></td></tr></tbody></table>

### WS-Security Policy Configuration Examples

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

This example enables both controls:

```yaml
- 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:

```yaml
- 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:

```yaml
- 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Purpose</th><th>Algorithm</th></tr></thead><tbody><tr><td><div><div><p>Signature</p></div></div></td><td><div><div><p>RSA-SHA256 (<code>http://www.w3.org/2001/04/xmldsig-more#rsa-sha256</code>)</p></div></div></td></tr><tr><td><div><div><p>Canonicalization</p></div></div></td><td><div><div><p>Exclusive XML Canonicalization without comments (<code>http://www.w3.org/2001/10/xml-exc-c14n#</code>)</p></div></div></td></tr><tr><td><div><div><p>Reference digest</p></div></div></td><td><div><div><p>SHA-256 (<code>http://www.w3.org/2001/04/xmlenc#sha256</code>)</p></div></div></td></tr></tbody></table>

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:

```xml
<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

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [SOAP Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-soap-schema-validation)

- [XML Threat Protection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-xml-threat-protection)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)