Merge branch 'master' into mobile-sidebar

Signed-off-by: Philipp Hugenroth <philipph@spotify.com>

docs/api/deprecations.md

@@ -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}
+        />
+      }
+    />
+  }
+/>
+```

docs/features/search/search-engines.md

@@ -90,6 +90,18 @@ within your instance. The configuration options are documented in the
 The underlying functionality is using official ElasticSearch client version 7.x,
 meaning that ElasticSearch version 7 is the only one confirmed to be supported.
 
+Should you need to create your own bespoke search experiences that require more
+than just a query translator (such as faceted search or Relay pagination), you
+can access the configuration of the search engine in order to create new elastic
+search clients. The version of the client need not be the same as one used
+internally by the elastic search engine plugin. For example:
+
+```typescript
+import { Client } from '@elastic/elastic-search';
+
+const client = searchEngine.newClient(options => new Client(options));
+```
+
 ## Example configurations
 
 ### AWS