> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-company IP allowlist

> Restrict authenticated access to Woku to a list of trusted CIDR blocks

Some companies require that access to their Woku panel be allowed only
from **specific IPs**, the corporate network, a VPN, or an office
range. Woku supports this via a per-company allowlist of **CIDR
blocks**, configurable and opt-in.

## Concepts

* **CIDR**: standard notation for describing a range of IPs.
  Examples: `10.0.0.0/8` (the entire 10.x.x.x network), `203.0.113.5/32`
  (only that exact IP), `2001:db8::/32` (an IPv6 prefix).
* **Per-company opt-in**: each company decides whether to enable the
  control. By default it is **disabled** and all authenticated traffic
  passes without restriction.
* **Fail-closed**: if the company cannot be resolved or the request IP
  is unknown (no `x-forwarded-for` and no direct IP), the guard
  responds 403.
* **IPv4 + IPv6**: the matcher supports both.

## Enabling the allowlist

To enable the control for your company:

1. Go to **Company → Security → IP allowlist**.
2. Load the CIDR blocks you can access from. Typical examples:
   * Corporate network: `192.168.0.0/16`
   * VPN: `10.0.0.0/8`
   * Single IP (office): `203.0.113.5/32`
3. Check **Enabled**.
4. Save.

> ⚠️ **You cannot enable the allowlist with an empty list**: the
> server rejects the operation because it would leave the entire team
> without access.

## What happens when someone tries to enter from outside the allowlist

The server responds `403 Forbidden` with the message
"Request IP not in company allowlist". The user:

* **Cannot sign in** from that IP, even with valid credentials.
* **Loses access to their current session** if that session makes a
  request from a disallowed IP.

All blocked actions are recorded in the
[audit log](/docs/en/seguridad/audit-log) as `403 Forbidden`
with `company.ip-allowlist.enforce`.

## IP detection

The guard prioritizes the `x-forwarded-for` header (needed because
behind a load balancer like ALB, the socket IP is the LB's):

1. If `x-forwarded-for: <ip1>, <ip2>, ...` is present, it uses the
   first IP.
2. Otherwise, it uses `request.ip` (direct socket).
3. If neither is available and the allowlist is active: 403.

> For this to work in production, the reverse proxy must be configured
> to inject `x-forwarded-for` with the client's real IP. Woku's current
> infrastructure (AWS Copilot/ALB) already does this.

## Guarantees

* **Server-side validation**: CIDRs are validated with `ip-cidr`
  before saving. An invalid entry is rejected with 400.
* **Deduplication**: the list is trimmed and duplicates are removed on
  save.
* **Immediate**: the change applies to the next request. There is no cache.
* **Auditable**: every update is recorded.

## Known limitations

* The guard is applied **per endpoint** (`@UseGuards(IpAllowlistGuard)`).
  In this first release it is NOT automatically applied to all
  company-scoped endpoints: teams that need strict enforcement must
  request it in a specific change per sensitive endpoint (or wait for
  the global rollout in the next release).
* It only applies to endpoints that carry `companyId` in the route. If
  a company has endpoints that are not scope-by-path, the allowlist
  does not gate them.

## What if I lock myself out by mistake?

If you configure an incorrect allowlist and lose access, **contact
support** (`team@woku.app`). An internal administrator can clear the
allowlist via a backoffice endpoint. The action is recorded in the
audit log.