core-plugin-api: deprecated some auth api refs and marked the rest as experimental

Co-authored-by: Johan Haals <johan.haals@gmail.com> Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2021-12-13 11:49:08 +01:00
parent a3ec122170
commit 8a7372cfd5
4 changed files with 156 additions and 27 deletions
@@ -61,3 +61,125 @@ breaking change to make `theme` optional. This means that if you currently
 construct the themes that you pass on to `createApp` using `AppTheme` as an
 intermediate type, you will need to work around this in some way, for example by
 passing the themes to `createApp` more directly.
+
+### Generic Auth API Refs
+
+`Released 2021-12-16 in @backstage/core-plugin-api v0.3.1`
+
+There are four auth Utility API references in `@backstage/core-plugin-api` that
+were too generic to be useful. The APIs in question are `auth0AuthApiRef`,
+`oauth2ApiRef`, `oidcAuthApiRef`, and `samlAuthApiRef`. The issue with these
+APIs was that they had no actual contract of what the backing auth provider was.
+This made it more or less impossible to use these providers in open source
+plugins in any meaningful way. We also did not want to keep these Utility API
+references around just as helpers either, instead opting to remove them and let
+integrators define their own APIs that are more specific to their auth provider.
+This is also falls in line with a long-term goal to unify all auth providers to
+not have separate frontend implementations.
+
+If you're currently using one of these API references for either Sign-In or
+access delegation within an app, there are a couple of steps you need to take to
+migrate to your own custom API.
+
+First, you'll need to define a new Utility API reference. If you're only using
+the API for sign-in, you can put the definition in `packages/app/src/apis.ts`.
+However, if you need to access your auth API inside plugins you you'll need to
+export it from a common package. If you don't already have one we recommended
+creating `@internal/apis` and from there export the API reference.
+
+```ts
+// `ProfileInfoApi & BackstageIdentityApi & SessionApi` are required for sign-in
+// Include `OAuthApi & OpenIdConnectApi` only if applicable
+export const acmeAuthApiRef: ApiRef<
+  OAuthApi &
+    OpenIdConnectApi &
+    ProfileInfoApi &
+    BackstageIdentityApi &
+    SessionApi
+> = createApiRef({
+  id: 'internal.auth.acme',
+});
+```
+
+Next you'll want to wire up the API inside `packages/app/src/apis.ts`, which
+varies depending on which API you're replacing. If you for example are replacing
+the `oauth2ApiRef`, the factory might look like this:
+
+```ts
+// oauth2
+createApiFactory({
+  api: acmeAuthApiRef,
+  deps: {
+    discoveryApi: discoveryApiRef,
+    oauthRequestApi: oauthRequestApiRef,
+    configApi: configApiRef,
+  },
+  factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
+    OAuth2.create({
+      discoveryApi,
+      oauthRequestApi,
+      environment: configApi.getOptionalString('auth.environment'),
+    }),
+});
+```
+
+Provider specific factory implementations, copy the code you need into the
+factory method depending on which apiRef you previously used.
+
+```ts
+// samlAuthApiRef
+SamlAuth.create({
+  discoveryApi,
+  environment: configApi.getOptionalString('auth.environment'),
+});
+
+// oidcAuthApiRef
+OAuth2.create({
+  discoveryApi,
+  oauthRequestApi,
+  provider: {
+    id: 'oidc',
+    title: 'Your Identity Provider',
+    icon: () => null,
+  },
+  environment: configApi.getOptionalString('auth.environment'),
+});
+
+// auth0AuthApiRef
+OAuth2.create({
+  discoveryApi,
+  oauthRequestApi,
+  provider: {
+    id: 'auth0',
+    title: 'Auth0',
+    icon: () => null,
+  },
+  defaultScopes: ['openid', 'email', 'profile'],
+  environment: configApi.getOptionalString('auth.environment'),
+});
+```
+
+Finally, for the provider to show up in your settings menu, you also need to
+update the settings route in `packages/app/src/App.tsx` to pass the
+`acmeAuthApiRef` to the `UserSettingsPage`. This replaces all existing provider
+items, so you might want to add back any of the default ones that you are using
+from the
+[DefaultProviderSettings](https://github.com/backstage/backstage/blob/a3ec122170e0205fd3f9c307b98b1c5e4f55bf5f/plugins/user-settings/src/components/AuthProviders/DefaultProviderSettings.tsx#L35).
+
+```tsx
+<Route
+  path="/settings"
+  element={
+    <UserSettingsPage
+      providerSettings={
+        <ProviderSettingsItem
+          title="ACME"
+          description="Provides sign-in via ACME"
+          apiRef={acmeAuthApiRef}
+          icon={Star}
+        />
+      }
+    />
+  }
+/>
+```