Skip to main content

Portal Connect

Overview​

Portal Connect is a lightweight agent that acts as a secure proxy between Portal and APIs that it cannot directly reach. The Agent runs in your infrastructure and enables access to services (GitHub, GitLab, internal APIs, metrics endpoints, etc.) that are behind your firewall or otherwise unreachable. All credentials and API keys stay within your network.

Use Cases for Portal Connect​

Portal Connect is particularly useful when:

  • Your infrastructure has strict firewall rules and you cannot open inbound ports
  • Your security policy prohibits inbound connections from the internet
  • You need your Portal to access services behind your firewall without exposing them to the internet
  • You want to avoid exposing internal services to the internet while still enabling Portal integration
  • You need to maintain audit trails and control over API access
  • You require secure, authenticated connections without changing your firewall configuration

How Portal Connect Works​

You deploy the Portal Connect Agent as a lightweight Docker container in your infrastructure. The Agent runs within your internal network, keeping sensitive data such as API keys and credentials within your network perimeter.

Architecture​

The Agent establishes an outbound WebSocket connection to Portal and registers which URLs (routes) it can access. When Portal needs to make a request to one of these services, the request is forwarded through the WebSocket to the Agent, which executes the HTTP request and returns the response.

Request Flow​

  1. Portal needs to access an internal service (e.g., https://github.internal.company.com)
  2. Portal forwards the request through the secure WebSocket connection to the Agent
  3. Agent executes the HTTP request from within your network
  4. Agent returns the response through the WebSocket back to Portal
  5. Portal processes the response as if it had direct access

Authentication​

The Agent authenticates to Portal using mutual TLS (mTLS) certificates with a 180-day maximum lifespan. This ensures only authorized Agents can connect to your Portal instance.

Monitoring​

The Agent provides metrics for monitoring connection health, request volumes, error rates, and certificate expiration.

Features​

Portal Connect is designed with security and simplicity in mind:

No Inbound Firewall Rules Needed​

  • The Agent only makes outbound connections
  • There is no need to open incoming ports
  • After the connection is initiated, the secure WebSocket connection is bidirectional
  • Zero inbound ports required - the Agent never listens or accepts connections
  • No inbound attack surface - connections are always initiated from inside your network
  • Your firewall configuration for incoming traffic remains unchanged

This makes Portal Connect ideal for security-conscious environments where opening inbound ports is prohibited or restricted.

Security by Design​

  • All data in transit is encrypted via TLS using WebSocket Secure (WSS)
  • mTLS authentication ensures only authorized Agents can connect
  • Route-based access control - the Agent explicitly registers which URLs it can access
  • Credentials and API keys stay within your network - Portal never sees your internal service credentials

Simple Configuration​

  • No special proxy configuration needed in Backstage plugins
  • Configure plugins with internal URLs as if Portal were running inside your network
  • Portal Connect handles routing transparently

Stateless Operation​

  • The Agent operates as a stateless proxy with no persistent data storage
  • Requests and responses are held in memory only during active processing
  • No caching or logging of sensitive data to disk