Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Login und Berechtigungen

Ziel: Anna und Thomas melden sich mit ihrem Forgejo-Konto am Portal an, und eine eigene Permission-Policy lässt nur Team Plattform Entities löschen und Templates ausführen. · Dauer: ca. 120 min · Voraussetzung: Tag 11

Briefing

  • Bisher prüft niemand, wer du bist: Der Guest-Provider macht jeden zu Thomas Zachmann (Tag 4). Heute übernimmt Forgejo als OIDC-Provider die Anmeldung.
  • Ein Sign-in-Resolver übersetzt die Forgejo-Identität in eine User-Entity aus kranich/org. Ohne passende Entity kein Login.
  • Das Ergebnis ist ein Backstage-Token mit sub (User) und ent (ownershipEntityRefs: User plus Gruppen).
  • Die Permission-Policy entscheidet bei jeder geschützten Aktion anhand dieses Tokens: ALLOW, DENY oder CONDITIONAL.
Browser ─Sign In─► Popup: Forgejo /login/oauth/authorize ─► Login + Autorisieren
   ▲                                                            │ code
   │ Backstage-Token (sub, ent)                                 ▼
Backend /api/auth/oidc/handler/frame ── Token + ID-Token ── Forgejo
   │ Resolver: E-Mail ─► user:default/anna.berger (memberOf team-sendung)
   ▼
Permission-Policy: catalog.entity.delete? scaffolder.task.create? ─► ALLOW/DENY

Drill 1: Forgejo vorbereiten

Ausgangslage ist das Ende von Tag 11. Wichtig für heute: kranich/org mit den Users aus Tag 4 (E-Mails <name>@kranich.example) und das Template node-service aus Tag 5. Forgejo braucht zuerst Konten mit genau diesen E-Mail-Adressen:

source ~/backstage-lab/setup/env.sh
mkdir -p ~/backstage-lab/tag12 && cd ~/backstage-lab/tag12
for u in anna.berger thomas.zachmann; do
  docker exec "$FORGEJO_NAME" forgejo admin user create --username "$u" \
    --password lab-user-pw-123 --email "$u@kranich.example" \
    --must-change-password=false
done

Erwartet (Passwort lab-user-pw-123 ist ein Lab-Wert):

New user 'anna.berger' has been successfully created!
New user 'thomas.zachmann' has been successfully created!

Jetzt die OAuth2-Application. Sie gehört lab-admin, die Redirect-URI ist der Callback des Backends für den Provider oidc:

curl -s -u "$ADMIN" -H 'Content-Type: application/json' \
  -X POST "$FORGEJO/api/v1/user/applications/oauth2" \
  -d '{"name":"Backstage","confidential_client":true,
       "redirect_uris":["http://localhost:7007/api/auth/oidc/handler/frame"]}' \
  > oauth-app.json
jq '.client_secret |= .[0:8] + "…"' oauth-app.json

Erwartet (IDs weichen ab):

{
  "id": 4,
  "name": "Backstage",
  "client_id": "f5c8cbb4-cdc1-40cc-8da7-a6c1e5c0bd86",
  "client_secret": "gto_x7qc…",
  "confidential_client": true,
  "redirect_uris": [
    "http://localhost:7007/api/auth/oidc/handler/frame"
  ],
  "created": "2026-10-13T07:30:35Z"
}

Das Secret zeigt Forgejo nur dieses eine Mal. Es kommt zusammen mit einem Session-Secret für das Auth-Backend in die Lab-Datei setup/oidc-client, die env.sh ab jetzt mitlädt:

{ jq -r '"export OIDC_CLIENT_ID=\(.client_id)",
         "export OIDC_CLIENT_SECRET=\(.client_secret)"' oauth-app.json
  echo "export AUTH_SESSION_SECRET=$(openssl rand -hex 24)"
} > ~/backstage-lab/setup/oidc-client
chmod 600 ~/backstage-lab/setup/oidc-client && rm oauth-app.json
echo '[ -s "$LAB/setup/oidc-client" ] && source "$LAB/setup/oidc-client" || true' \
  >> ~/backstage-lab/setup/env.sh
source ~/backstage-lab/setup/env.sh
echo "${OIDC_CLIENT_ID:0:8}… Secret: ${#OIDC_CLIENT_SECRET} Zeichen"
curl -s "$FORGEJO/.well-known/openid-configuration" \
  | jq -c '{issuer, authorization_endpoint, scopes_supported}'

Erwartet:

f5c8cbb4… Secret: 56 Zeichen
{"issuer":"http://127.0.0.1:3300","authorization_endpoint":"http://127.0.0.1:3300/
login/oauth/authorize","scopes_supported":["openid","profile","email","groups"]}

Das || true am Ende ist Absicht: Skripte wie up.sh laden env.sh mit set -e und würden sonst abbrechen, solange die Datei fehlt.

Sicherheit: oidc-client enthält echte Geheimnisse deiner Lab-Instanz. Sie liegt wie forgejo-token nur in setup/ und nie im Portal-Repo.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der OIDC-Provider im Backend

cd ~/backstage-lab/portal
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-oidc-provider \
  @backstage/backend-plugin-api
grep -E 'oidc-provider|backend-plugin-api' packages/backend/package.json

Erwartet (gekürzt):

➤ YN0000: · Done with warnings in 2s 188ms
    "@backstage/backend-plugin-api": "^1.10.1",
    "@backstage/plugin-auth-backend-module-oidc-provider": "^0.4.21",

backend-plugin-api brauchst du ab Drill 5 für eigene Module. Das OIDC-Modul kommt direkt unter den Guest-Provider:

sed -i '' "/plugin-auth-backend-module-guest-provider'));/a\\
backend.add(import('@backstage/plugin-auth-backend-module-oidc-provider'));
" packages/backend/src/index.ts
grep "auth-backend" packages/backend/src/index.ts

Erwartet:

backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
backend.add(import('@backstage/plugin-auth-backend-module-oidc-provider'));

Die Konfigurationsschlüssel stehen in config.schema.json des Moduls (metadataUrl, clientId, clientSecret, optional prompt, additionalScopes …), die Resolver in dist/resolvers.cjs.js: emailMatchingUserEntityProfileEmail und emailLocalPartMatchingUserEntityName. Der alte auth-Block aus Tag 4 fliegt raus – der Gast soll nicht länger Thomas Zachmann sein:

yq -i 'del(.auth)' app-config.local.yaml
cat >> app-config.local.yaml <<'EOF'
auth:
  environment: development
  session:
    secret: ${AUTH_SESSION_SECRET}
  providers:
    oidc:
      development:
        metadataUrl: http://127.0.0.1:3300/.well-known/openid-configuration
        clientId: ${OIDC_CLIENT_ID}
        clientSecret: ${OIDC_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail
            - resolver: emailLocalPartMatchingUserEntityName
EOF
grep -c '^auth:' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
  "$BACKSTAGE/api/auth/oidc/start?env=development" | cut -c1-80

Erwartet:

1
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
302 http://127.0.0.1:3300/login/oauth/authorize?client_id=f5c8cbb4-cdc1-40cc-8da

development unter oidc ist der Name der Umgebung aus auth.environment. Die Resolver probiert Backstage der Reihe nach; meldet einer „nicht gefunden”, kommt der nächste dran. Der Gast ist ohne userEntityRef wieder user:development/guest.

Achtung: Ohne auth.session.secret liefert oidc/start HTTP 500, im Log steht Authentication failed, authentication requires session support. Der OIDC-Provider legt state und PKCE-Verifier in einer Server-Session ab, und die gibt es nur mit Secret.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die Sign-in-Seite

Die Standard-Sign-in-Seite des neuen Frontend-Systems ist fest verdrahtet: @backstage/plugin-app/dist/extensions/DefaultSignInPage.esm.js rendert <SignInPage providers={["guest"]} />, ohne Config-Schlüssel. Du ersetzt die Extension sign-in-page:app durch ein eigenes App-Modul mit SignInPageBlueprint. Für OIDC gibt es keine fertige API-Referenz, also legst du eine an und lässt sie von OAuth2.create aus @backstage/core-app-api bauen:

yarn --cwd packages/app add @backstage/core-app-api
mkdir -p packages/app/src/modules/signin
cat > packages/app/src/modules/signin/index.tsx <<'EOF'
import {
  ApiBlueprint,
  configApiRef,
  createApiRef,
  createFrontendModule,
  discoveryApiRef,
  oauthRequestApiRef,
} from '@backstage/frontend-plugin-api';
import {
  BackstageIdentityApi,
  OpenIdConnectApi,
  ProfileInfoApi,
  SessionApi,
} from '@backstage/core-plugin-api';
import { OAuth2 } from '@backstage/core-app-api';
import { SignInPageBlueprint } from '@backstage/plugin-app-react';
import { SignInPage } from '@backstage/core-components';

// Eigene API-Referenz: core-plugin-api bringt keine für OIDC mit
export const forgejoAuthApiRef = createApiRef<
  OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>().with({ id: 'auth.forgejo' });

const forgejoAuthApi = ApiBlueprint.make({
  name: 'forgejo-auth',
  params: defineParams =>
    defineParams({
      api: forgejoAuthApiRef,
      deps: {
        discoveryApi: discoveryApiRef,
        oauthRequestApi: oauthRequestApiRef,
        configApi: configApiRef,
      },
      factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
        OAuth2.create({
          configApi,
          discoveryApi,
          oauthRequestApi,
          environment: configApi.getOptionalString('auth.environment'),
          // muss 'oidc' heißen: Pfad /api/auth/oidc/… im Backend
          provider: { id: 'oidc', title: 'Forgejo', icon: () => null },
          defaultScopes: ['openid', 'profile', 'email'],
        }),
    }),
});

const signInPage = SignInPageBlueprint.make({
  params: {
    loader: async () => props =>
      (
        <SignInPage
          {...props}
          title="Kranich Entwicklerportal"
          providers={[
            'guest',
            {
              id: 'forgejo-auth-provider',
              title: 'Forgejo',
              message: 'Mit dem Forgejo-Konto anmelden',
              apiRef: forgejoAuthApiRef,
            },
          ]}
        />
      ),
  },
});

export const signInModule = createFrontendModule({
  pluginId: 'app',
  extensions: [forgejoAuthApi, signInPage],
});
EOF

Das Modul muss in App.tsx unter features (Stand Tag 9):

cd packages/app/src
sed -i '' "/modules\/theme';/a\\
import { signInModule } from './modules/signin';
" App.tsx
sed -i '' 's/themeModule\]/themeModule, signInModule]/' App.tsx
grep -n 'signInModule' App.tsx
cd ~/backstage-lab/portal && yarn tsc && ~/backstage-lab/setup/portal.sh restart

Erwartet:

6:import { signInModule } from './modules/signin';
9:  features: [catalogPlugin, navModule, homeModule, themeModule, signInModule],
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)

Sieht deine features-Liste nach Tag 11 anders aus, trage signInModule von Hand ein. Warum pluginId: 'app'? Ein Modul darf nur Extensions seines eigenen Plugins überschreiben, und sign-in-page:app gehört dem App-Plugin – genau wie das Sidebar-Modul aus Tag 9.

  1. Öffne http://localhost:3000 in einem frischen Fenster (oder melde dich über Settings → ⋮ → Sign Out ab).
  2. Erwartet: zwei Karten, Guest mit Enter und Forgejo mit Sign In, wie in der Abbildung.
Sign-in-Seite mit Guest und Forgejo

Fortschritt speichern? Kostenlos registrieren

Drill 4: Erster Login – ohne E-Mail

  1. Klicke bei Forgejo auf Sign In. Es öffnet sich ein Popup mit der Forgejo-Anmeldung.
  2. Melde dich als anna.berger / lab-user-pw-123 an (Anmelden), wie in der Abbildung.
Forgejo-Anmeldung im Popup
  1. Erwartet: Forgejo fragt, ob „Backstage” auf das Konto zugreifen darf – mit den Scopes openid profile email und der Redirect-URI aus Drill 1, wie in der Abbildung. Klicke Anwendung autorisieren.
Forgejo fragt nach der Autorisierung der Anwendung Backstage
  1. Erwartet: Das Popup schließt sich, aber die Anmeldung scheitert. Unten erscheint:
Login failed; caused by Error: Login failed, user profile does not contain an email

Dabei hat Anna eine E-Mail-Adresse. Die Ursache steht im Modul:

M=node_modules/@backstage/plugin-auth-backend-module-oidc-provider
grep -n -A1 email_verified $M/dist/authenticator.cjs.js

Erwartet:

23:      ...input.fullProfile.userinfo.email_verified === true && {
24-        email: input.fullProfile.userinfo.email

Das Modul übernimmt die E-Mail nur, wenn der Userinfo-Endpunkt email_verified: true meldet. Forgejo liefert unter /login/oauth/userinfo aber nur sub, name, preferred_username, email und picture – email_verified steht allein im ID-Token. Ohne E-Mail im Profil wirft der Resolver einen Fehler, bevor er im Katalog sucht.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Ein eigenes Auth-Modul

Das Paket exportiert den oidcAuthenticator und die Resolver einzeln. Du baust daraus einen eigenen Provider oidc mit einem profileTransform, der die E-Mail aus dem geprüften ID-Token nimmt:

mkdir -p packages/backend/src/modules
cat > packages/backend/src/modules/forgejoAuth.ts <<'EOF'
import { createBackendModule } from '@backstage/backend-plugin-api';
import {
  authProvidersExtensionPoint,
  createOAuthProviderFactory,
} from '@backstage/plugin-auth-node';
import {
  oidcAuthenticator,
  oidcSignInResolvers,
} from '@backstage/plugin-auth-backend-module-oidc-provider';

// Ersetzt das Standardmodul: Forgejo meldet email_verified nur im ID-Token,
// nicht in /login/oauth/userinfo – ohne Transform bliebe profile.email leer.
export default createBackendModule({
  pluginId: 'auth',
  moduleId: 'forgejo-oidc',
  register(reg) {
    reg.registerInit({
      deps: { providers: authProvidersExtensionPoint },
      async init({ providers }) {
        providers.registerProvider({
          providerId: 'oidc',
          factory: createOAuthProviderFactory({
            authenticator: oidcAuthenticator,
            async profileTransform({ fullProfile }) {
              const claims = fullProfile.tokenset.claims();
              return {
                profile: {
                  email:
                    claims.email_verified === true ? claims.email : undefined,
                  displayName: fullProfile.userinfo.name,
                  picture: fullProfile.userinfo.picture,
                },
              };
            },
            signInResolverFactories: oidcSignInResolvers,
          }),
        });
      },
    });
  },
});
EOF
OLD="'@backstage/plugin-auth-backend-module-oidc-provider'"
sed -i '' "s#import($OLD)#import('./modules/forgejoAuth')#" \
  packages/backend/src/index.ts
grep -E "guest-provider|forgejoAuth|oidc" packages/backend/src/index.ts

Erwartet:

backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
backend.add(import('./modules/forgejoAuth'));

Das Standardmodul muss raus: Zwei Module mit providerId: 'oidc' vertragen sich nicht. Config und Resolver-Namen bleiben gleich, weil signInResolverFactories dieselben Fabriken registriert. Das Backend startet nach dem Speichern von selbst neu.

  1. Lade http://localhost:3000 neu, klicke Sign In bei Forgejo. Das Popup schließt sich diesmal ohne Rückfrage – Forgejo hat sich die Autorisierung gemerkt.
  2. Öffne Settings.
  3. Erwartet: Profile mit Forgejo-Avatar und E-Mail, darunter Backstage Identity mit der User-Entity Anna Berger und Team Sendung, wie in der Abbildung.
Settings-Seite von Anna Berger mit Profil und Backstage Identity

Was passiert mit jemandem, der in Forgejo existiert, aber nicht in org.yaml? Probe mit dem Forgejo-Admin:

  1. Melde dich in Backstage ab (Settings → ⋮ → Sign Out) und öffne in einem neuen privaten Fenster http://localhost:3000.
  2. Sign In bei Forgejo, Login lab-admin / lab-admin-pw-123, Anwendung autorisieren.
  3. Erwartet: die Fehlermeldung wie in der Abbildung.
Login ohne passende User-Entity scheitert am Resolver

Beide Resolver finden nichts: Es gibt keinen User mit [email protected] und keinen mit dem Namen admin. Genau so soll es sein – Forgejo beweist nur die Identität, ob sie ins Portal darf, entscheidet der Katalog.

Tipp: Sign Out beendet nur die Backstage-Sitzung. Die Forgejo-Sitzung im Browser bleibt, und das nächste Sign In meldet dich ohne Passwort wieder als derselbe User an. Zum Wechseln zwischen Anna und Thomas nimm ein privates Fenster oder melde dich auch in Forgejo ab.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Eine eigene Permission-Policy

Das Permission-Framework ist seit create-app eingeschaltet (permission.enabled: true in app-config.yaml), aber die Policy erlaubt alles:

grep -A2 'permission.enabled\|^permission:' app-config.yaml | grep enabled
grep -B1 -A1 allow-all-policy packages/backend/src/index.ts

Erwartet:

  enabled: true
backend.add(
  import('@backstage/plugin-permission-backend-module-allow-all-policy'),
);

Die Namen der Permissions stehen in @backstage/plugin-catalog-common und @backstage/plugin-scaffolder-common (dist/permissions.esm.js), z. B. catalog.entity.delete, catalog.location.delete und scaffolder.task.create. Die Policy hängt sich als Modul an das Permission-Plugin, über den Extension Point policyExtensionPoint aus @backstage/plugin-permission-node/alpha:

cat > packages/backend/src/modules/permissionPolicy.ts <<'EOF'
import {
  coreServices,
  createBackendModule,
  UserInfoService,
} from '@backstage/backend-plugin-api';
import {
  AuthorizeResult,
  PolicyDecision,
} from '@backstage/plugin-permission-common';
import {
  PermissionPolicy,
  PolicyQuery,
  PolicyQueryUser,
} from '@backstage/plugin-permission-node';
import { policyExtensionPoint } from '@backstage/plugin-permission-node/alpha';

// Diese Aktionen bleiben dem Team Plattform vorbehalten
const NUR_PLATTFORM = [
  'catalog.entity.delete',
  'catalog.location.delete',
  'scaffolder.task.create',
];
const PLATTFORM = 'group:default/plattform';

class KranichPolicy implements PermissionPolicy {
  constructor(private readonly userInfo: UserInfoService) {}

  async handle(
    request: PolicyQuery,
    user?: PolicyQueryUser,
  ): Promise<PolicyDecision> {
    if (!NUR_PLATTFORM.includes(request.permission.name)) {
      return { result: AuthorizeResult.ALLOW };
    }
    if (!user) {
      return { result: AuthorizeResult.DENY };
    }
    const { ownershipEntityRefs } = await this.userInfo.getUserInfo(
      user.credentials,
    );
    return ownershipEntityRefs.includes(PLATTFORM)
      ? { result: AuthorizeResult.ALLOW }
      : { result: AuthorizeResult.DENY };
  }
}

export default createBackendModule({
  pluginId: 'permission',
  moduleId: 'kranich-policy',
  register(reg) {
    reg.registerInit({
      deps: {
        policy: policyExtensionPoint,
        userInfo: coreServices.userInfo,
      },
      async init({ policy, userInfo }) {
        policy.setPolicy(new KranichPolicy(userInfo));
      },
    });
  },
});
EOF

Ersetze in packages/backend/src/index.ts die drei Zeilen mit allow-all-policy durch:

backend.add(import('./modules/permissionPolicy'));
grep -E "permission-backend'|permissionPolicy" packages/backend/src/index.ts
yarn tsc && yarn --cwd packages/backend lint && echo "✔ tsc + lint"

Erwartet:

backend.add(import('@backstage/plugin-permission-backend'));
backend.add(import('./modules/permissionPolicy'));
✔ tsc + lint

Warum userInfo.getUserInfo() statt user.info? Das Feld info ist in PolicyQueryUser als deprecated markiert. catalog.location.delete steht mit in der Liste, weil der Unregister-Dialog bei registrierten Locations die Location löscht, nicht die Entity.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Gegenprobe im GUI

  1. Melde dich in einem privaten Fenster als anna.berger an (Team Sendung) und klicke auf Create.
  2. Erwartet: Die Karte Node.js-Service hat keinen Button Choose – wie in der Abbildung.
Template-Karte für Anna Berger ohne Choose-Button
  1. Öffne im Katalog tracking-web, klicke oben rechts auf ⋮ und dann auf Unregister entity.
  2. Erwartet: Nichts passiert. Der Eintrag sieht in 1.55 aus wie immer, ist aber gesperrt (aria-disabled="true") – die Antwort der Policy war DENY.
  3. Wiederhole beides in einem neuen privaten Fenster als thomas.zachmann (Team Plattform und Team Web).
  4. Erwartet: Choose ist da, und Unregister entity öffnet den Dialog wie in den Abbildungen. Klicke dort Cancel.
Template-Karte für Thomas Zachmann mit Choose-Button
Unregister-Dialog für Thomas Zachmann

Das Frontend fragt für jeden Button vorab POST /api/permission/authorize und blendet aus oder sperrt. Die eigentliche Absicherung sitzt im Backend: Auch ein direkter API-Aufruf scheitert. Probe mit dem Gast, der ohne Gruppen dasteht:

GUEST=$(curl -s -H 'X-Requested-With: XMLHttpRequest' \
  "$BACKSTAGE/api/auth/guest/refresh" | jq -r .backstageIdentity.token)
curl -s -H "Authorization: Bearer $GUEST" -H 'Content-Type: application/json' \
  "$BACKSTAGE/api/permission/authorize" -d '{"items":[
   {"id":"1","permission":{"type":"basic","name":"scaffolder.task.create",
    "attributes":{"action":"create"}}},
   {"id":"2","permission":{"type":"basic","name":"catalog.entity.read",
    "attributes":{"action":"read"}}}]}' | jq -c .
UID_TW=$(bs catalog/entities/by-name/component/default/tracking-web \
  | jq -r .metadata.uid)
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE \
  -H "Authorization: Bearer $GUEST" "$BACKSTAGE/api/catalog/entities/by-uid/$UID_TW"

Erwartet:

{"items":[{"id":"1","result":"DENY"},{"id":"2","result":"ALLOW"}]}
403

Fortschritt speichern? Kostenlos registrieren

Drill 8: Und der Lab-Token?

Seit Tag 0 arbeitest du mit bs und dem statischen Token lab-cli. Gilt die Policy auch für ihn?

curl -s -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  -H 'Content-Type: application/json' "$BACKSTAGE/api/permission/authorize" \
  -d '{"items":[]}' | jq -r .error.message
UID_EX=$(bs catalog/entities/by-name/component/default/example-website \
  | jq -r .metadata.uid)
bs catalog/entities/by-uid/$UID_EX -X DELETE -w '%{http_code}\n'
sleep 10
bs catalog/entities/by-name/component/default/example-website | jq -r .metadata.name

Erwartet:

This endpoint does not allow 'service' credentials
204
example-website

Der Token ist ein Service-Principal, kein User. ServerPermissionClient in @backstage/plugin-permission-node entscheidet für Service-Principals sofort selbst und fragt die Policy gar nicht – ohne Einschränkung heißt das ALLOW. Die Entity kommt nach Sekunden zurück, weil ihre Location noch existiert.

Einschränken kannst du einen Token nur an der Quelle, mit accessRestrictions in backend.auth.externalAccess (Schlüssel plugin, permission, permissionAttribute.action laut backend-defaults). Ein zweiter, reiner Lese-Token:

yq -i '.backend.auth.externalAccess += [{"type": "static",
  "options": {"token": "lab-ro-token-0123456789abcdef", "subject": "lab-readonly"},
  "accessRestrictions": [{"plugin": "catalog",
    "permissionAttribute": {"action": "read"}}]}]' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
RO=lab-ro-token-0123456789abcdef                          # Lab-Wert!
curl -s -o /dev/null -w 'GET catalog: %{http_code}\n' \
  -H "Authorization: Bearer $RO" "$BACKSTAGE/api/catalog/entities?limit=1"
curl -s -o /dev/null -w 'DELETE: %{http_code}\n' -X DELETE \
  -H "Authorization: Bearer $RO" "$BACKSTAGE/api/catalog/entities/by-uid/$UID_EX"
curl -s -H "Authorization: Bearer $RO" "$BACKSTAGE/api/scaffolder/v2/tasks" \
  | jq -r .error.message

Erwartet:

✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
GET catalog: 200
DELETE: 403
This token's access is restricted to plugin(s) 'catalog'

Plugins, die in accessRestrictions fehlen, sind für diesen Token komplett zu. lab-cli lässt du ohne Einschränkung, die Folgekapitel brauchen ihn.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cp ~/backstage-lab/code/tag12/kontrolle.sh ~/backstage-lab/tag12/
bash ~/backstage-lab/tag12/kontrolle.sh

Das Skript holt sich ein Gast-Token und fragt die Policy direkt; ein User-Token für Anna gibt es nur über den Browser-Login. Kern der Prüfung:

authz() { curl -sf -H "Authorization: Bearer $GUEST" \
  -H 'Content-Type: application/json' "$BACKSTAGE/api/permission/authorize" \
  -d "{\"items\":[{\"id\":\"1\",\"permission\":{\"type\":\"basic\",
       \"name\":\"$1\",\"attributes\":{}}}]}" | jq -r '.items[0].result'; }
t "Gast darf keine Templates ausführen (scaffolder.task.create = DENY)" \
  "[ \"\$(authz scaffolder.task.create)\" = DENY ]"

Erwartet:

✔ OAuth2-App Backstage in Forgejo
✔ Forgejo-User anna.berger und thomas.zachmann
✔ auth/oidc/start leitet zu Forgejo um
✔ Gast darf lesen (catalog.entity.read = ALLOW)
✔ Gast darf keine Templates ausführen (scaffolder.task.create = DENY)
✔ Lab-Token lab-cli liest weiter den Katalog

Challenge

Refresh einer Entity (der Kreispfeil in der Karte About) soll nur noch ihr Owner auslösen dürfen. Anna darf sendungs-api aktualisieren, tracking-web nicht.

Hinweis: Für Resource-Permissions darf die Policy statt ALLOW/DENY eine Bedingung zurückgeben, die der Katalog selbst prüft – fertige Bausteine stehen in @backstage/plugin-catalog-backend/alpha.

Lösung

Die vollständige Datei liegt unter code/tag12/challenge/permissionPolicy.ts. Neu sind zwei Imports und ein Zweig vor dem Gruppen-Check; außerdem gehört catalog.entity.refresh zu den Permissions, die die Policy überhaupt anfasst:

import {
  AuthorizeResult,
  isResourcePermission,
  PolicyDecision,
} from '@backstage/plugin-permission-common';
import {
  catalogConditions,
  createCatalogConditionalDecision,
} from '@backstage/plugin-catalog-backend/alpha';
// … in handle():
    const regelt =
      NUR_PLATTFORM.includes(request.permission.name) ||
      request.permission.name === 'catalog.entity.refresh';
    if (!regelt) {
      return { result: AuthorizeResult.ALLOW };
    }
    // … user prüfen, ownershipEntityRefs holen wie bisher, dann:
    if (
      isResourcePermission(request.permission, 'catalog-entity') &&
      request.permission.name === 'catalog.entity.refresh'
    ) {
      return createCatalogConditionalDecision(
        request.permission,
        catalogConditions.isEntityOwner({ claims: ownershipEntityRefs }),
      );
    }
cp ~/backstage-lab/code/tag12/challenge/permissionPolicy.ts \
  ~/backstage-lab/portal/packages/backend/src/modules/permissionPolicy.ts
cd ~/backstage-lab/portal && yarn tsc && echo "✔ tsc"

Erwartet: ✔ tsc. Melde dich als Anna an: Auf sendungs-api (Owner Team Sendung) zeigt About den Refresh-Button, auf tracking-web (Team Web) fehlt er. Die Policy kennt die Entity nicht – sie liefert nur die Bedingung IS_ENTITY_OWNER, und das Catalog-Backend wertet sie gegen die Relationen der Entity aus.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Im Unternehmen kommt OIDC meist von Entra ID, Keycloak oder Okta. Der Resolver matcht dann gegen User-Entities aus demselben Verzeichnis (Tag 4) – E-Mail oder ein stabiler Objekt-ID-Claim, nie ein frei änderbarer Anzeigename.
  • Der Guest-Provider verweigert außerhalb von NODE_ENV=development den Dienst, solange niemand dangerouslyAllowOutsideDevelopment: true setzt. Lass es so und nimm 'guest' aus der Sign-in-Seite.
  • auth.session.secret, Client-Secret und Backend-Keys gehören in einen Secret-Store (Vault, Kubernetes Secret) und werden per Env injiziert; Redirect-URIs nur mit HTTPS.
  • Policies sind Code: mit Unit-Tests, Review und Änderungshistorie. Für viele Regeln lohnt ein RBAC-Plugin, das Rollen per UI oder CSV pflegt.
  • Statische Tokens für CI und Skripte immer mit accessRestrictions und eigenem subject ausgeben – Service-Principals umgehen sonst jede Policy.