This document covers Graphistry's authentication system with respect to architecture, usage, and configuration.
It also touches on coarse authorization decisions where relevant. However, authorization is generally beyond the scope of this document.
See also security hardening, general configuration, manual user account creation, and threat model.
Graphistry authentication uses standard web software layers:
-
Container: Docker / docker-compose
- Determine ports for http and/or https
-
Reverse proxy: Caddy (
caddy
)- Web and API calls are initially reverse-proxied through reverse proxy Docker service
caddy
- The Caddyfile and docker-compose.yml configurations (Docker virtual network definition) are the primary places for customizing networking
- TLS: System administrators should configure automatic and manual TLS as a custom Caddyfile
- Web and API calls are initially reverse-proxied through reverse proxy Docker service
-
Bastion: Nginx (
nginx
)- Caddy sends user HTTP requests to the Graphistry-configured reverse proxy Docker service
nginx
- It performs a coarse per-service/route authorization for public / user / staff based on the service being accessed
- For example, notebook service use currently require staff level permissions
- Nginx is not exposed for configuration
- Caddy sends user HTTP requests to the Graphistry-configured reverse proxy Docker service
-
Authentication service: Django (
nexus
) - CSRF/JWT cookies and sessions- Web sesssions use HTTP-only
csrftoken
andgraphistry_jwt
cookies - APIs use
jwt
tokens via headerAuthorization: Bearer xyz
- ... TLS is required for protecting these from MITM attacks
- By default, authentication is via Graphistry's internal account system
- Integrating with social/external and internal auth are also possible
- Web sesssions use HTTP-only
-
Single sign-on (SSO)
- Graphistry supports OIDC-compliant single sign-on (SSO)
- Menu: Admin Portal -> Settings -> Config -> IS_SSO_SIGNUP: Enable, save
- Manu:
- Site-wide SSO: Go to Manage Site
- Organization-specific: Go to Manage Organizations -> Security icon (SSO)
- Configure the identity provider as instructed
- For popular providers, pick a template, fill in the host name, and get the rest prefilled
-
Services use JWT tokens
- They will translate csrf to JWT as needed
- Resources having corresponding protected metadata:
- Resource request handlers take a JWT/csrf and check it
- Services maintain the JWT token as part of their request context for passing to resource requests
- Services are written following an object-capability paradigm:
- Having a value gives authority to read/write/call it
- ... As does passing it, or having/passing a csrf/jwt credential authorized for it
-
Browser security headers
- Unconfigured servers do nto have TLS
- Add a TLS certificate enables TLS
- Further consider adding additional security headers
- Cross-origin embedding for unauthenticated visualizations is enabled by default
- To enable cross-origin embedding of authenticated visualizations, modify the cookie options
-
The first user to create an account will be given an administrator role. This may vary, such as AWS Marketplace does have an initial account:
admin
/i-theInstanceID
. -
Subsequent user registration follows a configurable policy (see user creation)
- By default, only the administrator can invite subsequent users
- The administrator may want to open account creation or manually elevate the role of different users
- Organization administrators may control whether their organization is open for joining at all, including whether SSO users can self-join or require an explicit invitation
-
API users, upon getting an account, will make their code programmatically generate short-lived JWT tokens and refresh them.
The most typical authentication configurations are:
-
Set TLS via
Caddyfile
, with optional manual TLS credential volume mount in thedocker-compose.yml
. See TLS docs. -
Open/close account registration and invite users. See user creation docs. Contact staff for more advanced options, such as social logins and LDAP/SAML.
-
Enable cross-origin embedding of authenticated visualizations by editing cookie settings (requires TLS)
-
Enable SSO