Security groups

A channel with one security definition has one credential. A channel with security groups has as many as the groups hold members - each partner or application keeps its own API key, Basic Auth username or bearer token, and one channel serves them all.

How groups work

A security group is a named set of security definitions. A channel lists one or more groups, and a request is allowed through when its credential matches any member of any of the channel's groups.

Three credential kinds work through groups:

• A bearer token, in the Authorization header
• Basic Auth, in the Authorization header
• An API key, in the header the channel's API key definitions name

Two constraints keep a channel's groups unambiguous:

• All API key definitions across one channel's groups share one header name - members with conflicting headers are refused when the configuration loads
• Usernames and API key values are unique across a channel's groups

A request with both Basic Auth and an API key at once is answered 400 - one credential per request.

Create a group

To create a group, go to Security > Groups in the Dashboard, click Create a new group and fill in the form:

1. Name: Partner Applications
2. Members: pick the Basic Auth and API key definitions that belong to the group
3. Click OK

Assign the group in the channel's create or edit form and any client whose credential is a member of the group can call the channel. To revoke one client's access, remove its definition from the group - the channel and the other clients stay untouched.

In service code, self.channel.security.username names the member whose credential authenticated the request, so you can tell which client made each call.

403, not 401

A channel secured through groups answers failed authentication with 403, both for a wrong credential and for a missing one. Only a channel secured with a directly assigned security definition answers 401 with a WWW-Authenticate challenge - the difference tells a caller which of the two rejected it. The full status map is in the error catalog.

Groups in enmasse

channel_rest:

  - name: api.partner.orders
    service: demo.rest.partner-orders
    url_path: /api/partner/orders
    data_format: json
    groups:
      - Partner Applications
      - Internal Tools

The enmasse reference documents the remaining channel keys.

mTLS channels

A channel requires client certificates by attaching an mTLS security definition. The definition may pin a certificate's SHA-256 fingerprint, its subject DN, or neither - with neither configured, any certificate the TLS layer verified is accepted.

Zato itself never terminates TLS for mTLS channels - the proxy in front of the server does, and it reports the outcome through three headers:

The bundled HAProxy configuration strips all three headers from every incoming request before setting them itself, so a caller can never inject them. A proxy of your own must do the same - the headers are trusted, which is safe only when the proxy is their sole source.

A request whose headers do not verify, or whose certificate matches neither the pinned fingerprint nor the pinned subject DN, is answered 401.

The mTLS page covers creating the definitions and certificates end to end.

See also

Learn more