> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/gateway/access-gateway.md).

# How the Access Gateway works

What the OpenIAM Access Gateway is, why an organization deploys one, where it sits between the browser, the application and OpenIAM, and how one protected request travels through it.

## What this is, and when you need it

The **Access Gateway** — historically the **rProxy** — sits in front of a web application, terminates the user's OpenIAM session, asks OpenIAM on every request whether this user may have this URI by this method, and forwards the request upstream with identity attached.

It exists for one situation: **an application that cannot speak a federation protocol**. Legacy internal applications, appliance administration consoles, anything whose only notion of a user is a header, a cookie or a login form. It also fronts OpenIAM's own web tiers in the shipped deployment.

**Your working surface is the content provider in the Webconsole.** Two OpenIAM objects, not a file on the proxy host, decide who gets in and what is injected: a **content provider** (one per domain) and its **URI Patterns** (one per protected path). Installing the proxy, telling it where OpenIAM is, and running it in a container or on a host are deployment work covered by the **Installation and Tuning Guide**.

## Why an organization deploys one

The argument for a gateway is not really about any single application. It is that authentication, authorization, auditing and monitoring end up in **one place** instead of being reimplemented, inconsistently, in each application behind it. A request that never reaches the application unless OpenIAM has already decided who is making it and whether they are entitled to that URI by that method is a request you only have to reason about once, and the record of that decision lands in one audit trail rather than in a dozen application logs of varying quality.

That single control point is what makes the rest of the case work. Application teams stop doing security work that was never theirs to do: no per-application session handling, no per-application password policy, no per-application entitlement check. Internal systems that were never built to face the internet can be published to external users without being changed, because the thing facing the internet is the gateway rather than the application. And a policy written once applies the same way across a hybrid estate, where some applications are cloud-hosted, some are still in the data centre, and none of them agree on how a user should prove who they are.

This is why the gateway usually turns up in the middle of a larger programme rather than on its own. Cloud migrations produce applications that move while their authentication cannot move with them, and identity modernization projects set out to consolidate a decade of one-off logins behind a single identity provider. In both cases the gateway is what buys time for the applications that cannot be changed yet — which is also the reason to treat it as a step on the way to federation rather than a destination.

## Where it sits, and how one request travels

The gateway holds no authorization rules of its own. It asks OpenIAM, on every request, what to do. Two calls carry the whole conversation: one asks whether this user may have this URI by this method, and one asks what should be injected into the upstream request. One or two OpenIAM round trips per protected request is the design, not a misconfiguration.

```mermaid
sequenceDiagram
    autonumber
    participant B as Browser
    participant G as Access Gateway
    participant O as OpenIAM (ESB)
    participant I as IdP / UI tier
    participant A as The application
    B->>G: Request /app/report, with OPENIAM_AUTH_TOKEN if a session exists
    G->>O: May this user have this URI by this method?
    O-->>G: Allow, deny, or authenticate first
    G-->>B: 302 to /idp/login when there is no valid session
    B->>I: The user authenticates; the UI sets OPENIAM_AUTH_TOKEN
    B->>G: /app/report again, now carrying a session
    G->>O: What should I inject for this user on this URI?
    O-->>G: Headers, query parameters, cookies or form fields
    G->>A: The proxied request, with identity attached
    A-->>G: The application's response
    G-->>B: The response, with CSP, CORS and HSTS headers added
```

Three consequences follow from that shape, and all three surprise people.

**OpenIAM is on the request path.** If the ESB is down or slow, every protected request is down or slow. The gateway's health is OpenIAM's health, which is the strongest argument for preferring a federation protocol wherever the application can speak one.

**Changes take effect on a timer, not on save.** OpenIAM refreshes its URI-federation cache every `org.openiam.am.uri.federation.threadsweep` ms, which ships as `30000`, and its content-provider cache every `org.openiam.content.provider.threadsweep` ms, which ships as `300000`. The Webconsole says so on every save: *"URI Pattern for Content Provider was saved successfully. Please allow a few minutes for changes to propagate."* Make one change, wait it out, test — rather than changing three things and guessing afterwards which of them did what. Confirm both values under **Administration → System Configuration**.

**Bootstrapping is chicken-and-egg.** With no content provider, nothing is authorized and nobody can reach the Webconsole to create one. The shipped proxy configuration punches a hole through to `/webconsole/setup` for exactly that reason, and closing that hole again is a deployment setting.

{% hint style="info" %}
**Through the gateway, the proxy owns the session cookie.** On a proxied request the UI returns the cookie exactly as it arrived and logs `Is proxy request - using cookie from proxy`; on a request that reaches the UI tier directly the UI renews the cookie on every request. Either way an idle timeout is a sliding window driven by requests, which matters for clients that hold a session and stop making them — see [Session lifetime and renewal](/administration-guide/gateway/access-gateway-reference.md#session-lifetime-and-renewing-the-session-cookie).
{% endhint %}

## When the gateway is the wrong answer

**If the application supports SAML 2.0, OAuth 2.0 or OpenID Connect, use that instead.** A federation protocol gives the application a signed assertion or token it can validate itself, with a session it controls and a logout it understands. The gateway gives it a header it must trust blindly, and puts OpenIAM on the request path for every single hit. Configure the application as a [SAML service provider](/administration-guide/federation/saml-service-provider.md) or an [OAuth client](/administration-guide/federation/oauth-and-oidc.md) and skip this section.

Two more cases where the gateway is not what you want:

* **An API consumed by a non-browser client.** The gateway's session model assumes a cookie and a redirect to a login page. Use OAuth 2.0 with a bearer token.
* **A single application on a domain you already federate.** Adding a content provider for it means a second place where authentication routing is decided, and content-provider changes propagate on a cache timer rather than immediately.

## Can your application be proxied?

Not every application can be. Before you commit to the gateway for a given application, test it against the three things that are known to defeat a reverse proxy. Each is a go/no-go question rather than a preference, and each is cheaper to answer now than after the content provider exists.

**Does the application emit absolute URLs?** An application that writes its own hostname into the links, form actions, redirects and script sources on its pages sends users straight back to its real address — outside the gateway — the moment they click anything. Those URLs have to be rewritten in the response as it passes through, which the gateway can do, but it is per-URL work that has to be found, fixed and then maintained as the application changes. A page or two is fine. An application that does it everywhere, including in JavaScript that assembles URLs at run time in the browser where no response-body substitution can reach them, is a poor candidate.

**Does the application reject requests that arrive from a different address?** Some applications check the client address, the `Host` header, or a hostname they were configured to answer on, and refuse anything that did not come from where they expect. Behind the gateway every request arrives from the proxy, so a check like that fails for every user rather than for none. Unless it can be switched off, or the expected address reconfigured to the proxy, the application cannot be proxied.

**Is the login form protected by CAPTCHA?** If it is, form fill is impossible. The entire purpose of a CAPTCHA is that a machine cannot complete the form, and the gateway is a machine. The same holds for login forms that rely on browser-side JavaScript to build or sign the submission. Nothing in the gateway works around this: either the protection comes off the form for requests originating at the proxy, or this application needs a different integration.

## The three protection patterns

Every gateway deployment is one or more of these. They are not alternatives to each other — a single URI pattern can inject headers *and* the site can use Kerberos for the login step.

| Pattern                                    | What the application receives                                                              | Where it is configured                                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **Header, parameter and cookie injection** | Identity as trusted request headers, query-string parameters or cookies                    | **Metadata** on a URI pattern, paired with an exclude rule that strips any browser-supplied copy |
| **Form fill**                              | A submission to its own login form, with the credentials filled in                         | **Metadata** of type **Form Post Processor** on the *form action* path                           |
| **Kerberos / desktop SSO**                 | Nothing extra — this changes how the *user* authenticates, not what the *application* sees | An authentication rule in OpenIAM, plus SPNEGO on the proxy host                                 |

{% hint style="warning" %}
**Injection is only as trustworthy as your exclude rules.** A header you inject can also be sent by a browser. For every identity header, parameter or cookie you set, add an **Exclude Headers** or **Exclude Cookies** entry naming the same thing on the same pattern, so the inbound copy is stripped before the trusted one is set. This is the single most commonly missed step in a gateway deployment.
{% endhint %}

## What you configure, and where

Everything an administrator configures on the gateway is a row on a content provider or on one of its URI patterns, and takes effect on a cache timer without touching the proxy host.

| Surface                                | Where it lives                                                   | What it decides                                                                     |
| -------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| URI patterns                           | **URI Patterns** on the content provider                         | What is protected, what is public, and which upstream a path is proxied to          |
| Header, parameter and cookie injection | **Metadata** on a URI pattern                                    | What identity the application receives                                              |
| Form fill                              | **Metadata** of type **Form Post Processor**                     | How a user is signed in to an application that only understands its own login form  |
| URL rewriting and redirects            | **HTML Substitution List** and **Redirect URL** on a URI pattern | Which absolute URLs are fixed on the way out, and which requests are sent elsewhere |
| An authentication rule bound to a URL  | **Supported Authentication Levels** on a URI pattern             | Whether one path demands a different authentication from the rest of the site       |
| A stylesheet and logos                 | **UI Theme** on the content provider or a URI pattern            | What the pages OpenIAM renders in front of the application look like                |

Two things are deliberately **not** on that list. Apache directives and container environment variables are deployment concerns belonging to whoever owns the proxy host or the manifest; they are covered by the [Installation Guide](/installation/installation.md). Their names are catalogued in [Access Gateway reference](/administration-guide/gateway/access-gateway-reference.md) so that you can read what the gateway is doing and name precisely what you need changed — not as the way to configure any of the six surfaces above. Where a feature has both a Webconsole field and a directive, the Webconsole field is the supported way: it is stored with the content provider, visible on screen, scoped to one pattern, and changeable without a configuration reload.

{% hint style="danger" %}
Gateway configuration decides how people reach the Webconsole, so a mistake can lock you out of the tool you would use to fix it. Establish and **test** a break-glass administrator and an unprotected route to the Webconsole before your first change — see [Change configuration safely](/administration-guide/start/change-safely.md). Then remember the five-minute cache: a bad change and its rollback each have a several-minute blast radius.
{% endhint %}

## Related

* [Protect an application behind the Access Gateway](/administration-guide/gateway/protect-an-application.md) — the model above, done end to end with real values
* [Content providers and URI patterns](/administration-guide/access/content-providers-and-uri-patterns.md) — the two objects every surface here is configured on, field by field
* [Access Gateway reference](/administration-guide/gateway/access-gateway-reference.md) — metadata types, value sources, the calls the gateway makes, and the directive catalogue
* [Configure federation and application SSO](/administration-guide/federation.md) — the protocols to prefer where the application supports them

*Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/gateway/access-gateway.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.