Merge pull request #24965 from backstage/freben/docs

just some small service docs advancements

docs/backend-system/core-services/permissions.md

@@ -16,36 +16,42 @@ import {
   coreServices,
   createBackendPlugin,
 } from '@backstage/backend-plugin-api';
-import { Router } from 'express';
+import { NotAllowedError } from '@backstage/errors';
+import { AuthorizeResult } from '@backstage/plugin-permission-common';
+import Router from 'express-promise-router';
 
-createBackendPlugin({
+export default createBackendPlugin({
   pluginId: 'example',
   register(env) {
     env.registerInit({
       deps: {
         permissions: coreServices.permissions,
-        http: coreServices.httpRouter,
+        httpRouter: coreServices.httpRouter,
+        httpAuth: coreServices.httpAuth,
       },
-      async init({ permissions, http }) {
-        const router = Router();
-        router.get('/test-me', (request, response) => {
-          // use the identity service to pull out the token from request headers
-          const { token } = await identity.getIdentity({
-            request,
-          });
-
-          // ask the permissions framework what the decision is for the permission
+      async init({ permissions, httpRouter, httpAuth }) {
+        const endpoints = Router();
+        endpoints.get('/test-me', (request, response) => {
+          // Ask the permissions framework what the decision is for the given
+          // permission, for the principal that made the original request. The
+          // `httpAuth` service helps us extract those credentials. We authorize
+          // a single permission here, so the result will be an array with one
+          // element accordingly.
           const permissionResponse = await permissions.authorize(
-            [
-              {
-                permission: myCustomPermission,
-              },
-            ],
-            { token },
+            [{ permission: myCustomPermission }],
+            { credentials: await httpAuth.credentials(request) },
           );
+
+          if (permissionResponse[0].result !== AuthorizeResult.ALLOW) {
+            throw new NotAllowedError(
+              'You are not permitted to perform this action',
+            );
+          }
+
+          // TODO: Actual code goes here
         });
 
-        http.use(router);
+        httpRouter.use(endpoints);
       },
     });
   },

docs/backend-system/core-services/plugin-metadata.md

@@ -5,4 +5,28 @@ sidebar_label: Plugin Metadata
 description: Documentation for the Plugin Metadata service
 ---
 
-TODO
+This service allows you to query for metadata about the current plugin. In particular, this service is used by other plugin-scoped services, if they need to know what the ID is of the plugin that they are being instantiated for.
+
+## Using the service
+
+The following example shows a fake plugin-scoped service which wants to know what plugin it "belongs" to.
+
+```ts
+import {
+  coreServices,
+  createServiceFactory,
+} from '@backstage/backend-plugin-api';
+
+export const myServiceFactory = createServiceFactory({
+  service: myServiceRef,
+  deps: {
+    logger: coreServices.logger,
+    plugin: coreServices.pluginMetadata,
+  },
+  async factory({ logger, plugin }) {
+    const pluginId = plugin.getId();
+    logger.info(`Creating an instance of my service for plugin '${id}'`);
+    return ...; // TODO
+  },
+});
+```