# SOAP Authentication

Configure authentication for SOAP (Simple Object Access Protocol) API connectors. SOAP APIs often include credentials directly in the request payload rather than using HTTP headers.

## When to Use SOAP Auth

Use when the provider is a **SOAP/XML web service**:

- ✅ WSDL (Web Services Description Language) file available
- ✅ XML-based request/response format
- ✅ SOAP envelope structure required
- ✅ Credentials embedded in SOAP body
- ❌ REST JSON API → Use `auth-custom` or `auth-oauth2` instead

## SOAP Auth Patterns

### Pattern 1: Credentials in Every Request

Most common pattern: Include credentials in each SOAP request body.

```yaml
authentication:
  - custom:
      type: custom
      label: API Credentials
      authorization:
        type: none              # No HTTP Authorization header
      configFields:
        - key: username
          label: Username
          type: text
          required: true
          secret: false

        - key: password
          label: Password
          type: password
          required: true
          secret: true

        - key: companyId
          label: Company ID
          type: text
          required: true
          secret: false
      testActions:
        - action: get_employees
          required: true
```

**In actions**, include credentials in SOAP body:

```yaml
steps:
  - stepId: fetch_data
    description: Fetch data with credentials
    stepFunction:
      functionName: soap_request
      parameters:
        url: /EmployeeService
        method: post
        soapOperation: GetEmployees
        soapAction: http://api.provider.com/GetEmployees
        namespaces:
          - namespaceIdentifier: emp
            namespace: http://api.provider.com/employees
        args:
          # Credentials in SOAP body
          - name: Credentials
            in: body
            value:
              Username: $.credentials.username
              Password: $.credentials.password
              CompanyId: $.credentials.companyId

          # Other parameters
          - name: EmployeeFilter
            in: body
            value:
              Status: ${inputs.status}
```

### Pattern 2: WS-Security Header

Some SOAP APIs use WS-Security (UsernameToken) in SOAP headers:

```yaml
authentication:
  - custom:
      type: custom
      label: WS-Security
      authorization:
        type: none
      configFields:
        - key: username
          label: Username
          type: text
          required: true
          secret: false

        - key: password
          label: Password
          type: password
          required: true
          secret: true
```

**In actions**, use WS-Security via `useSoapContext`:

```yaml
stepFunction:
  functionName: soap_request
  parameters:
    url: /Service
    method: post
    soapOperation: GetData
    useSoapContext: true            # Default: true. Passes credentials.username/password as WS-Security context to SOAP client. Set false when auth is via HTTP headers instead.
```

> **Note:** `useSoapContext` automatically reads `username` and `password` from the connector's credentials (`block.credentials`). No separate `wsSecurity` block is needed — just ensure the `configFields` above include `username` and `password` keys.

### Pattern 3: Static Token in Header

If SOAP API uses HTTP Authorization header:

```yaml
authentication:
  - custom:
      type: custom
      label: API Token
      authorization:
        type: bearer
        token: $.credentials.apiToken
        includeBearer: false        # Omit "Bearer" prefix — check provider docs for expected format
      configFields:
        - key: apiToken
          label: API Token
          type: password
          required: true
          secret: true
```

## SOAP Request Configuration

See the SOAP Request and SOAP Paginated Request sections (`soap_request` / `soap_paginated_request`) in the repo's `connector-guide.md` for complete SOAP request configuration including:
- SOAP operation names
- SOAP action URIs
- XML namespace definitions
- Request/response mapping
- Credential placement

## Dynamic Base URLs for SOAP

Some SOAP APIs require company-specific endpoints:

```yaml
# In main connector config
baseUrl: https://${credentials.companyId}.api.provider.com/soap

authentication:
  - custom:
      type: custom
      label: Company Credentials
      authorization:
        type: none
      configFields:
        - key: username
          label: Username
          type: text
          required: true

        - key: password
          label: Password
          type: password
          required: true
          secret: true

        - key: companyId
          label: Company ID
          type: text
          required: true
          description: Your company identifier in the URL
```

## Complete Examples

### Credentials in SOAP Body (Most Common)

```yaml
# Main connector
StackOne: 1.0.0
info:
  title: SOAP Provider
  key: soapprovider
  version: 1.0.0
  assets:
    icon: https://stackone-logos.com/api/soapprovider/filled/svg
  description: SOAP API connector
baseUrl: https://api.provider.com/soap/v1
releaseStage: preview

authentication:
  - custom:
      type: custom
      label: API Credentials
      authorization:
        type: none
      configFields:
        - key: username
          label: Username
          type: text
          required: true
          secret: false

        - key: password
          label: Password
          type: password
          required: true
          secret: true

        - key: companyId
          label: Company ID
          type: text
          required: true
          secret: false
      testActions:
        - action: test_connection
          required: true

actions:
  $ref: soapprovider.employees
```

### WS-Security Authentication

```yaml
authentication:
  - custom:
      type: custom
      label: WS-Security
      authorization:
        type: none
      configFields:
        - key: username
          label: Username
          type: text
          required: true
          description: WS-Security username

        - key: password
          label: Password
          type: password
          required: true
          secret: true
          description: WS-Security password
      testActions:
        - action: validate_credentials
          required: true
```

## SOAP-Specific Considerations

### 1. WSDL Discovery

Many SOAP services provide WSDL files describing operations:

```
WSDL URL: https://api.provider.com/soap?wsdl
```

Use WSDL to discover:
- Available operations
- Required parameters
- Namespace definitions
- Authentication requirements

### 2. Credential Persistence

**⚠️ IMPORTANT**: Keep credential blocks in SOAP request if provider requires them on EVERY call.

**Don't extract credentials** to connector-level auth if they must be in request body.

### 3. Namespace Management

SOAP APIs use XML namespaces. Define once, reference in all actions:

```yaml
namespaces:
  - namespaceIdentifier: soapenv
    namespace: http://schemas.xmlsoap.org/soap/envelope/
  - namespaceIdentifier: api
    namespace: http://api.provider.com/v1
```

### 4. Testing Strategy

SOAP APIs often require complex payloads. Start with simplest operation:

```yaml
testActions:
  - action: ping              # Simple connectivity test
    required: true
  - action: get_version       # Service version check
    required: false
```

## Related Skills

- **connector-patterns**: Base connector structure and corpus-mined conventions
- **`connector-guide.md`** (`soap_request` / `soap_paginated_request` sections): Complete SOAP request configuration
- **auth-custom**: Alternative for SOAP with HTTP headers
- **connector-patterns/references/schema-vs-corpus.md**: Credential references in SOAP bodies

## Critical Rules

### MUST DO:
- ✅ Use `type: custom` with `authorization.type: none` for SOAP
- ✅ Include credentials in SOAP body if required by provider
- ✅ Test with simplest operation first
- ✅ Document WSDL location in connector resources
- ✅ Define all required namespaces
- ✅ Mark sensitive fields with `secret: true`

### MUST NOT:
- ❌ Extract credentials from SOAP body if provider requires them there
- ⚠️ Avoid OAuth 2.0 patterns for SOAP unless provider docs explicitly require it (rare but possible)
- ❌ Skip namespace definitions
- ❌ Leave `useSoapContext` as default `true` when auth is via HTTP headers only (bearer/API key) — set it to `false` to avoid injecting empty WS-Security credentials

---

**Remember**: SOAP authentication usually embeds credentials in the request payload. See the `soap_request` / `soap_paginated_request` sections of the repo's `connector-guide.md` for complete request configuration.