Skip to content

Update admin docs about Frame Ancestor #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vaimdevs wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Update admin docs about Frame Ancestor #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/app-config/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,16 +74,24 @@ grphstry.my-website.org, :80 {
# disable clients from sniffing the media type
header_down X-Content-Type-Options nosniff

# clickjacking protection
header_down X-Frame-Options SAMEORIGIN
# clickjacking protection (CSP frame-ancestors replaces X-Frame-Options)
header_down Content-Security-Policy "frame-ancestors 'self' {$FRAME_ANCESTORS:}"
header_down -X-Frame-Options

# keep referrer data off of HTTP connections
header_down Referrer-Policy no-referrer-when-downgrade
}
}
```

Note: Configuration line `header_down X-Frame-Options SAMEORIGIN` will prevent all cross-origin embedding. By default, public content can be cross-origin embedded while private content cannot. See also `COOKIE_SAMESITE` for enabling authorized private content in cross-origin embeddings.
Note: `frame-ancestors 'self'` (default) restricts embedding to same-origin only. To allow cross-origin embedding (e.g., Databricks, Jupyter), set `FRAME_ANCESTORS` in `data/config/custom.env`:

```bash
# Allow specific origins to embed Graphistry in iframes
FRAME_ANCESTORS=https://*.databricks.com https://*.cloud.databricks.com
```

`X-Frame-Options` is removed — modern browsers use CSP `frame-ancestors` instead. See also `COOKIE_SAMESITE` for enabling authorized private content in cross-origin embeddings.

#### Application servers

Expand Down
13 changes: 13 additions & 0 deletions docs/app-config/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,19 @@ COOKIE_SECURE=true
COOKIE_SAMESITE=None
```

## Security Headers

| Variable | Description | Default |
|----------|-------------|---------|
| `FRAME_ANCESTORS` | Space-separated origins allowed to embed Graphistry in iframes (CSP `frame-ancestors`) | `""` (same-origin only) |

**Example** — allow Databricks:
```bash
FRAME_ANCESTORS=https://*.databricks.com https://*.cloud.databricks.com
```

See [TLS Hardening - Caddy](configure.md#caddy) for Caddyfile context.

## Maps / Geospatial

Enable Kepler.gl-based geospatial map visualizations.
Expand Down
2 changes: 1 addition & 1 deletion docs/security/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Graphistry authentication uses standard web software layers:
* Unconfigured servers do nto have TLS
* [Add a TLS certificate](../app-config/configure.md#tls) enables TLS
* Further consider adding [additional security headers](../app-config/configure.md#caddy)
* Cross-origin embedding for unauthenticated visualizations is enabled by default
* Same-origin embedding enforced by default via CSP `frame-ancestors 'self'`; set `FRAME_ANCESTORS` in `custom.env` to allow specific cross-origin hosts (e.g., Databricks, Jupyter)
* To enable cross-origin embedding of authenticated visualizations, [modify the cookie options](../app-config/configure.md#application-servers)

## Usage
Expand Down
4 changes: 2 additions & 2 deletions docs/security/configure-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ For futher information, see:
* As a web Admin, we recommend also creating a non-admin account for yourself
* Sessions are protected with JWT tokens and HTTP-only CSRF tokens
* TLS recommended
* Cross-origin embedding enabled
* Same-origin embedding enforced by default via CSP `frame-ancestors 'self'`; set `FRAME_ANCESTORS` in `custom.env` to allow specific cross-origin hosts
* Cross-origin embedded login disabled (see TLS configuration section)
* Visualizations are shared as secure web keys (unguessable IDs)
* Unique secrets are set in managed host environments (AWS/Azure Marketplace)
Expand Down Expand Up @@ -78,7 +78,7 @@ After, there are additional [Caddyfile http/https header settings](https://githu

Enabling **cross-origin authenticated use** is often desirable:

* Cross-origin embedding for unauthenticated visualizations is enabled by default
* Cross-origin embedding is same-origin only by default (CSP `frame-ancestors 'self'`); set `FRAME_ANCESTORS` in `data/config/custom.env` to allow specific origins (e.g., `https://*.databricks.com`)
* Cross-origin embedding for authenticated visualizations is disabled by default, enable as part of [TLS configuration](../app-config/configure.md#tls)

### Firewalls & SSH
Expand Down