How is your experience with the OutSystems Community?
23
Views
1
Comments
IP Whitelisting for OutSystems REST APIs

Hello,

I woul like to ask if OutSystems provides any IP whitelisting capability to restrict access to exposed REST APIs for specific IP addresses. We are using an on‑premises environment, and our requirement is to apply this restriction only to certain REST APIs that we have published.

Alternatively, would this need to be implemented at the code level, by adding Site Properties and using the OnAuthentication event with Custom Authentication, then checking whether the retrieved client IP matches our allowed static IPs (stored as a secret Site Property)?

Any guidance or recommended best practices would be greatly appreciated.

Thank you.

2023-12-26 10-35-28
OutSystems Neo
Staff
AI Generated

Yes, you can do IP whitelisting for exposed REST APIs, but OutSystems doesn’t provide a built‑in “per-API IP allowlist” feature out of the box. You have two main options:


Since you’re on‑premises, the most robust approach is usually to enforce IP restrictions at the network / API gateway / reverse proxy / firewall level, and only allow the desired IP ranges to reach your OutSystems front-end servers or specific paths.

Pros:

  • Centralized and easier to audit.
  • Harder to bypass than application-level checks.
  • No code changes per API.

Cons:

  • Less granular per-API control unless your gateway/proxy supports path-based rules.
  • Requires infra/network team involvement.

If you already have a WAF or API gateway, you can typically:

  • Restrict by IP for the base domain.
  • Or define rules per URL path (e.g. /MyModule/rest/MySensitiveAPI/*).

2. Application level (via OnAuthentication + IP check)

Your alternative design (custom authentication + IP allowlist) is aligned with OutSystems recommendations for custom logic on exposed REST APIs. You can implement this per-API, and keep the IP list in a Site Property or entity.

The approach is:

  1. Create an IP allowlist configuration

    • For each REST API (or group of APIs), create:
      • A Site Property or a Static Entity / DB Entity that stores:
        • Allowed CIDRs or IPs (e.g. 10.2.3.4, 203.0.113.0/24).
        • Possibly an “IsActive” flag, and an API identifier if you reuse the same table for multiple APIs.
    • If you want to treat it as a secret, you can:
      • Store it in an encrypted table, or
      • Use a Site Property and restrict who can see/edit it in Service Center.
  2. Use the REST API’s OnAuthentication event

    • For the exposed REST API, set Authentication = Custom and implement logic in OnAuthentication.
    • OutSystems documentation explicitly suggests using custom authentication to validate the caller for exposed REST APIs, which can include checking against a whitelist you maintain in an entity or configuration. Add_Custom_Authentication_to_an_Exposed_REST_API
  3. Obtain the client IP

    • Use HTTPRequestHandler.GetIP() to get the client IP.
    • If you are behind a reverse proxy / load balancer, make sure it is correctly forwarding the original client IP (e.g. X-Forwarded-For), and adjust your logic (or proxy configuration) accordingly if needed.
      (There are several forum references that use GetIP() from HTTPRequestHandler for this purpose.) how to add ip white listing, ip restriction to the users,
  4. Match the IP against your allowlist

    • Implement a small server action that:
      • Normalizes the IP string.
      • Compares against:
        • A list of exact IPs, or
        • A list of ranges/CIDR blocks (you may need helper logic for this).
    • If the IP is not allowed:
      • Set the OnAuthentication output to IsSuccess = False and provide an HTTP status code such as 403 (Forbidden) and a message like “IP not allowed”.
  5. Per-API granularity

    • Because the OnAuthentication is per exposed REST API (per module resource), you can:
      • Enable IP checks only on the specific APIs that must be restricted.
      • Keep others without IP restrictions or with different policies.

Points to consider / Best practices

  1. Combine with proper authentication

    • IP allowlisting should be a second line of defense.
    • Continue using proper authentication (API keys, OAuth, JWT, etc.) in the same OnAuthentication logic; IP check should not replace authentication.
  2. Maintainability

    • Storing allowed IPs in a DB entity is often more flexible than Site Properties:
      • You can build a small back-office to manage them.
      • You can support ranges, environments, or per‑API records.
    • However, for a very small, static set of IPs, a Site Property (comma-separated list) is simple and works well. how to add ip white listing, ip restriction to the users,
  3. Dynamic IPs

    • If the caller’s IPs are not static (e.g. consumer internet), pure IP whitelisting can become fragile.
    • In such cases, prefer:
      • Strong auth (e.g. certificates, tokens), and
      • IP allowlisting only when IPs are known to be stable (VPN endpoints, corporate egress IPs, etc.).
  4. Testing

    • Test from an allowed IP and from a disallowed IP.
    • If using VPNs, ensure the egress IP from the VPN is what your OutSystems server sees via GetIP().

Summary

  • There is no built‑in “per-REST-API IP allowlist” toggle in OutSystems.
  • Best practice is:
    • Prefer enforcing IP restrictions at infra level (firewall, WAF, API gateway) where possible.
    • For fine‑grained control per exposed REST API, use Custom Authentication on the API’s OnAuthentication event, retrieve the client IP via HTTPRequestHandler.GetIP(), compare it with your allowlist stored in Site Properties or entities, and deny access if it’s not allowed. Add_Custom_Authentication_to_an_Exposed_REST_API

If you describe your expected caller patterns (static corporate IPs vs dynamic), I can suggest a more concrete schema for the allowlist (e.g. entity model and matching logic).

This answer was AI-generated. Please read it carefully and use the forums for clarifications
Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.