Merge pull request #3415 from Infisical/feat/addBackstagePluginsDocs

Add Backstage Plugins docs

backend/src/db/migrations/20250402000941_add-type-to-kms-keys.ts

@@ -5,15 +5,21 @@ import { KmsKeyUsage } from "@app/services/kms/kms-types";
 import { TableName } from "../schemas";
 
 export async function up(knex: Knex): Promise<void> {
-  const hasTypeColumn = await knex.schema.hasColumn(TableName.KmsKey, "type");
+  const hasKeyUsageColumn = await knex.schema.hasColumn(TableName.KmsKey, "keyUsage");
 
-  await knex.schema.alterTable(TableName.KmsKey, (t) => {
-    if (!hasTypeColumn) t.string("keyUsage").notNullable().defaultTo(KmsKeyUsage.ENCRYPT_DECRYPT);
-  });
+  if (!hasKeyUsageColumn) {
+    await knex.schema.alterTable(TableName.KmsKey, (t) => {
+      t.string("keyUsage").notNullable().defaultTo(KmsKeyUsage.ENCRYPT_DECRYPT);
+    });
+  }
 }
 
 export async function down(knex: Knex): Promise<void> {
-  await knex.schema.alterTable(TableName.KmsKey, (t) => {
-    t.dropColumn("keyUsage");
-  });
+  const hasKeyUsageColumn = await knex.schema.hasColumn(TableName.KmsKey, "keyUsage");
+
+  if (hasKeyUsageColumn) {
+    await knex.schema.alterTable(TableName.KmsKey, (t) => {
+      t.dropColumn("keyUsage");
+    });
+  }
 }

backend/src/services/kms/kms-service.ts

@@ -288,11 +288,6 @@ export const kmsServiceFactory = ({
       throw new NotFoundError({ message: `KMS with ID '${kmsId}' not found` });
     }
 
-    const encryptionAlgorithm = kmsDoc.internalKms?.encryptionAlgorithm as SymmetricKeyAlgorithm;
-    verifyKeyTypeAndAlgorithm(kmsDoc.keyUsage as KmsKeyUsage, encryptionAlgorithm, {
-      forceType: KmsKeyUsage.ENCRYPT_DECRYPT
-    });
-
     if (kmsDoc.externalKms) {
       let externalKms: TExternalKmsProviderFns;
 
@@ -353,6 +348,11 @@ export const kmsServiceFactory = ({
       };
     }
 
+    const encryptionAlgorithm = kmsDoc.internalKms?.encryptionAlgorithm as SymmetricKeyAlgorithm;
+    verifyKeyTypeAndAlgorithm(kmsDoc.keyUsage as KmsKeyUsage, encryptionAlgorithm, {
+      forceType: KmsKeyUsage.ENCRYPT_DECRYPT
+    });
+
     // internal KMS
     const keyCipher = symmetricCipherService(SymmetricKeyAlgorithm.AES_GCM_256);
     const dataCipher = symmetricCipherService(encryptionAlgorithm);
@@ -509,11 +509,6 @@ export const kmsServiceFactory = ({
       throw new NotFoundError({ message: `KMS with ID '${kmsId}' not found` });
     }
 
-    const encryptionAlgorithm = kmsDoc.internalKms?.encryptionAlgorithm as SymmetricKeyAlgorithm;
-    verifyKeyTypeAndAlgorithm(kmsDoc.keyUsage as KmsKeyUsage, encryptionAlgorithm, {
-      forceType: KmsKeyUsage.ENCRYPT_DECRYPT
-    });
-
     if (kmsDoc.externalKms) {
       let externalKms: TExternalKmsProviderFns;
       if (!kmsDoc.orgKms.id || !kmsDoc.orgKms.encryptedDataKey) {
@@ -568,6 +563,11 @@ export const kmsServiceFactory = ({
       };
     }
 
+    const encryptionAlgorithm = kmsDoc.internalKms?.encryptionAlgorithm as SymmetricKeyAlgorithm;
+    verifyKeyTypeAndAlgorithm(kmsDoc.keyUsage as KmsKeyUsage, encryptionAlgorithm, {
+      forceType: KmsKeyUsage.ENCRYPT_DECRYPT
+    });
+
     // internal KMS
     const keyCipher = symmetricCipherService(SymmetricKeyAlgorithm.AES_GCM_256);
     const dataCipher = symmetricCipherService(encryptionAlgorithm);

docs/integrations/external/backstage.mdx

@@ -0,0 +1,123 @@
+---
+title: Backstage Infisical Plugin
+description: A powerful plugin that integrates Infisical secrets management into your Backstage developer portal.
+---
+
+Integrate secrets management into your developer portal with the Backstage Infisical plugin suite. This plugin provides a seamless interface to manage your [Infisical](https://infisical.com) secrets directly within Backstage, including full support for environments and folder structure.
+
+## Features
+
+- **Secrets Management**: View, create, update, and delete secrets from Infisical
+- **Folder Navigation**: Explore the full folder structure of your Infisical projects
+- **Multi-Environment Support**: Easily switch between and manage different environments
+- **Entity Linking**: Map Backstage entities to specific Infisical projects via annotations
+
+---
+## Installation
+
+### Frontend Plugin
+
+```bash
+# From your Backstage root directory
+yarn --cwd packages/app add @infisical/backstage-plugin-infisical
+```
+
+### Backend Plugin
+
+```bash
+# From your Backstage root directory
+yarn --cwd packages/backend add @infisical/backstage-backend-plugin-infisical
+```
+
+## Configuration
+
+### Backend
+
+Update your `app-config.yaml`:
+
+```yaml
+infisical:
+  baseUrl: https://app.infisical.com
+
+  authentication:
+    # Option 1: API Token Authentication
+    auth_token:
+      token: ${INFISICAL_API_TOKEN}
+
+    # Option 2: Client Credentials Authentication
+    universalAuth:
+      clientId: ${INFISICAL_CLIENT_ID}
+      clientSecret: ${INFISICAL_CLIENT_SECRET}
+```
+
+<Tip>
+    If you have not created a machine identity yet, you can do so in [Identities](/documentation/platform/identities/machine-identities)
+</Tip>
+
+Register the plugin in `packages/backend/src/index.ts`:
+
+```ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+
+backend.add(import('@infisical/backstage-backend-plugin-infisical'));
+
+backend.start();
+```
+
+### Frontend
+
+Update `packages/app/src/App.tsx` to include the plugin:
+
+```tsx
+import { infisicalPlugin } from '@infisical/backstage-plugin-infisical';
+
+const app = createApp({
+  plugins: [
+    infisicalPlugin,
+    // ...other plugins
+  ],
+});
+```
+
+Modify `packages/app/src/components/catalog/EntityPage.tsx`:
+
+```tsx
+import { EntityInfisicalContent } from '@infisical/backstage-plugin-infisical';
+
+const serviceEntityPage = (
+  <EntityLayout>
+    {/* ...other tabs */}
+    <EntityLayout.Route path="/infisical" title="Secrets">
+      <EntityInfisicalContent />
+    </EntityLayout.Route>
+  </EntityLayout>
+);
+```
+
+### Entity Annotation
+
+Add the Infisical project ID to your entity yaml settings:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-service
+  annotations:
+    infisical/projectId: <your-infisical-project-id>
+```
+
+> Replace `<your-infisical-project-id>` with the actual project ID from Infisical.
+
+## Usage
+
+Once installed and configured, you can:
+
+1. **View and manage secrets** in Infisical from within Backstage
+2. **Create, update, and delete** secrets using the Infisical tab in entity pages
+3. **Navigate environments and folders**
+4. **Search and filter** secrets by key, value, or comments
+
+![Backstage Plugin Table](/images/integrations/external/backstage/backstage-plugin-infisical.png)

docs/mint.json

@@ -552,6 +552,12 @@
       "group": "Build Tool Integrations",
       "pages": ["integrations/build-tools/gradle"]
     },
+    {
+      "group": "Others",
+      "pages": [
+        "integrations/external/backstage"
+      ]
+    },
     {
       "group": "",
       "pages": ["sdks/overview"]