Announcing the 2025 State of Backstage report
Roadie
← Backstage Plugins Guides
AWS Proxy SigV4 logo

Backstage AWS Proxy SigV4 Plugin

Created by Twilio Segment

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Add the plugin

bash
yarn add --cwd packages/backend '@segment/backstage-plugin-proxy-sigv4-backend'

For the New Backend System, make the following changes to your packages/backend/src/index.ts file.

typescript
// packages/backend/src/index.ts file
import { createBackend } from '@backstage/backend-defaults';
const backend = createBackend();
// ... other feature additions

+ // proxy-sigv4 plugin installation
+ backend.add(import('@segment/backstage-plugin-proxy-sigv4-backend'));

backend.start();

Or if you're using the Legacy Backend System, you'll need to add the plugin to the router in the backend. To do this, create a new backend plugin wrapper module and then add that to your backend index.ts file.

typescript
// packages/backend/src/plugins/proxy-sigv4.ts

import { createRouter } from '@segment/backstage-plugin-proxy-sigv4-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';

export default async function createPlugin({
  logger,
  config,
}: PluginEnvironment): Promise<Router> {
  return await createRouter({ logger, config });
}

// packages/backend/src/index.ts

+import proxySigV4 from './plugins/proxy-sigv4';

async function main() {
  ...
  const createEnv = makeCreateEnv(config);
  ...

  const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
+  const proxySigV4Env = useHotMemoize(module, () => createEnv('proxy-sigv4'));

  const apiRouter = Router();

  apiRouter.use('/proxy', await proxy(proxyEnv));
+  apiRouter.use('/proxy-sigv4', await proxySigV4(proxySignV4Env));
  ...
}

Then configure your proxy routes in either short or expanded form.

yaml
// Short form
proxysigv4:
  '/some-local-path': https://<API ID>.execute-api.<region>.amazonaws.com

// Expanded form
proxysigv4:
  '/some-local-path':
    target: 'https://<API ID>.execute-api.<region>.amazonaws.com'
    roleArn: 'arn:aws:iam::<account>:role/<name>'
    roleSessionName: tempAssumeRoleSession ## optional

Things to Know

Limitations

  • No response streaming.
  • No configuration of the forwarded or received headers allowlist.
  • No ability to override or manually configure target URL service and region properties CNAME'd endpoints are therefore not currently supported
  • Target URLs that lack a trailing slash (/) will always have one implicitly applied. e.g.: https://example.com/foo will be treated as https://example.com/foo/
  • Target URLs with a path prefix may be susceptible to path traversal attacks; test coverage for this is poor.

New Auth services

When using the new backend system with the new auth services, the proxy-sigv4 backend plugin will by default allow unauthenticated requests.

You can prevent this by adding allowUnauthenticatedRequests: false to your proxy file within the proxysigv4 section.

Changelog

This changelog is produced from commits made to the AWS Proxy SigV4 plugin since about 1 year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Features

  • Add region and service config options to the proxy sigv4 backend. You can set these per route to control aws4 signing. See README for an example. PR 19 merged 1 year ago

Breaking changes

  • None

Set up Backstage in minutes with Roadie

Get a demo