Web

Overview

A Web Resource puts a browser-based application, such as an internal dashboard or admin portal, behind the Connector. Users sign in to Formal in their browser. The Connector then proxies their requests with their Formal identity, logs each request, and evaluates HTTP policies.

A user opens the Resource’s address on the Connector.
If the browser has no Formal session, the Connector redirects it to https://app.formal.ai/connector-auth.
The user signs in to Formal. Formal redirects the browser back to the Connector with a one-time code.
The Connector exchanges the code and sets two session cookies: formalconnector and formalconnector_username. It then redirects to the page the user first asked for.
Each later request carries the cookies. The Connector removes them before forwarding the request, and it drops any attempt by the application to set them.

When a session expires, the Connector sends the browser back to sign in. One-time codes expire after 5 minutes and work once.

Requirements

Connector hostname: Give the Connector a hostname. See Hostname and TLS Configuration. Without one, the Connector answers hostname not configured for resource.
Address: Users reach the Resource at the Connector hostname, or at <resource-name>.<connector-hostname>. Other host names are rejected. To serve several Web Resources, use wildcard DNS and a wildcard TLS certificate, as for HTTP Resources.
Listener: Link the Resource to a Connector listener, usually on port 443.
People: Users sign in with their own human Formal account.

If your Permissions deny by default, allow the browser sign-in step:

package formal.app

import future.keywords.if

allow if {
  input.app.command.name == "connector-callback"
}

Create a Web Resource

Control Plane
Terraform

Go to Resources and click Create Resource. Set Technology to Web. Set Hostname to the application’s upstream hostname, such as grafana.internal.example.com. The Port defaults to 443.

resource "formal_resource" "grafana" {
  name       = "grafana"
  technology = "web"
  hostname   = "grafana.internal.example.com"
  port       = 443
}

Verify: Open https://grafana.<connector-hostname> in a browser. Sign in to Formal when prompted. The application loads, and the requests appear in Logs.

Use the Application’s Usual Address

Users who run the Formal Endpoint in Transparent Mode can keep the application’s usual URL. A network rule with forward_to_connector and resource_name sends that traffic to the Web Resource.

Upstream Credentials

A Native User is optional. Without one, the Connector forwards requests as the browser sent them, and the application handles its own sign-in. To inject a credential for the application, add a Native User of type HTTP Basic, HTTP Bearer, or API Key. See HTTP authentication.

Policy Evaluation

Web Resources support the same stages and actions as HTTP Resources. Policies read the request from input.http, and input.resource.technology is web. This policy blocks the admin area for everyone outside the platform-admins group:

package formal.v2

import future.keywords.if
import future.keywords.in

request := {
  "action": "block",
  "type": "block_with_custom_message",
  "message": "The admin area is limited to platform administrators"
} if {
  input.resource.technology == "web"
  startswith(input.http.path, "/admin")
  not "platform-admins" in input.user.groups
}

Troubleshooting

The browser shows hostname not configured for resource

Cause: The Connector has no hostname. Fix: Set the Connector’s hostname, then reload.

The browser shows invalid callback authority

Cause: The address isn’t the Connector hostname or <resource-name>.<connector-hostname>. Fix: Open the Resource at one of those addresses.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

Requirements

Create a Web Resource

Use the Application’s Usual Address

Upstream Credentials

Policy Evaluation

Troubleshooting

Next Steps

HTTP

Listeners

​Overview

​How Sign-In Works

​Requirements

​Create a Web Resource

​Use the Application’s Usual Address

​Upstream Credentials

​Policy Evaluation

​Troubleshooting

​Next Steps

HTTP

Listeners

Overview

How Sign-In Works

Requirements

Create a Web Resource

Use the Application’s Usual Address

Upstream Credentials

Policy Evaluation

Troubleshooting

Next Steps