ingressd
Sign inGet started
Docspreview · subject to change
Docs / Guides / Access policies

Access policies

An access policy puts a sign-in page in front of an app. Visitors prove their email address with a one-time code, sent by the panel, and the node lets them through if a rule matches.

How sign-in works#

  1. A visitor opens a protected app, such as ha.example.net.
  2. The node redirects them to your sign-in page, the portal host (for example auth.example.net, set under Access in the panel).
  3. They enter their email address. The panel emails them a one-time code; codes expire quickly and are rate limited per address and per IP.
  4. With a valid code, the node checks the app's policies in order. The first matching policy decides.
  5. The visitor gets a session for that app. Sessions are valid on every node, so failover doesn't sign anyone out.

The portal host needs a DNS record pointing at your nodes, like any app hostname.

Policies#

A policy has an action and up to three lists of rules:

Action Effect
allow Let matching visitors in after they sign in.
deny Refuse matching visitors.
bypass Let matching visitors in without signing in (use with an IP rule, or for a public path).
service_auth Let machines in with a service token instead of a person signing in.
List Meaning
Include The visitor must match at least one rule.
Require The visitor must match every rule.
Exclude A visitor matching any rule is not matched by this policy.

Rules can match everyone, an email address, an email domain, an IP address or range, or a country. Country rules need a GeoIP database on the node.

Examples:

  • Family: allow, include emails alice@example.net and bob@example.net, session 24h.
  • Admins from home: allow, include email you@example.net, require IP 198.51.100.0/24, session 8h.
  • Office: allow, include email domain example.net, exclude country RU.

Attach policies to an app on its page. With several policies, the first match wins.

Login to play#

Game servers with login_to_play access use the same sign-in flow on their play host: after signing in under the chosen policy, the player's IP is added to the server's allowlist for a set time. See game servers.

Revoke sessions#

Sessions can be revoked per user. On a node:

shellon a node
$ ingressd sessions list --email alice@example.net
$ ingressd sessions revoke --email alice@example.net
$ ingressd access test --app ha --email alice@example.net --ip 198.51.100.23

ingressd access test shows which policy would apply to a request, without sending a code.

Standalone nodes#

A standalone node sends codes itself, through your own SES or SMTP account (email in config.yaml); see standalone mode. Managed nodes need no email setup: the panel sends the codes.