core-plugin-api: auth request type renames and deprecations

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/young-students-applaud.md

@@ -0,0 +1,11 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Renamed `AuthProvider` to `AuthProviderInfo` and add a required 'id' property to match the majority of usage. The `AuthProvider` type without the `id` property still exists but is deprecated, and all usage of it without an `id` is deprecated as well. For example, calling `createAuthRequest` without a `provider.id` is deprecated and it will be required in the future.
+
+The following types have been renamed. The old names are still exported but deprecated, and are scheduled for removal in a future release.
+
+- Renamed `AuthRequesterOptions` to `OAuthRequesterOptions`
+- Renamed `AuthRequester` to `OAuthRequester`
+- Renamed `PendingAuthRequest` to `PendingOAuthRequest`

packages/core-app-api/src/apis/implementations/OAuthRequestApi/OAuthRequestManager.ts

@@ -39,6 +39,12 @@ export class OAuthRequestManager implements OAuthRequestApi {
   private handlerCount = 0;
 
   createAuthRequester<T>(options: AuthRequesterOptions<T>): AuthRequester<T> {
+    if (!options.provider.id) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'DEPRECATION WARNING: Not passing a provider id to createAuthRequester is deprecated, it will be required in the future',
+      );
+    }
     const handler = new OAuthPendingRequests<T>();
 
     const index = this.handlerCount;

packages/core-plugin-api/api-report.md

@@ -211,22 +211,21 @@ export const auth0AuthApiRef: ApiRef<
   OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
 >;
 
+// @public @deprecated (undocumented)
+export type AuthProvider = Omit<AuthProviderInfo, 'id'>;
+
 // @public
-export type AuthProvider = {
+export type AuthProviderInfo = {
+  id: string;
   title: string;
   icon: IconComponent;
 };
 
-// @public
-export type AuthRequester<AuthResponse> = (
-  scopes: Set<string>,
-) => Promise<AuthResponse>;
+// @public @deprecated (undocumented)
+export type AuthRequester<T> = OAuthRequester<T>;
 
-// @public
-export type AuthRequesterOptions<AuthResponse> = {
-  provider: AuthProvider;
-  onAuthRequest(scopes: Set<string>): Promise<AuthResponse>;
-};
+// @public @deprecated (undocumented)
+export type AuthRequesterOptions<T> = OAuthRequesterOptions<T>;
 
 // @public
 export type AuthRequestOptions = {
@@ -598,15 +597,28 @@ export type OAuthApi = {
 
 // @public
 export type OAuthRequestApi = {
-  createAuthRequester<AuthResponse>(
-    options: AuthRequesterOptions<AuthResponse>,
-  ): AuthRequester<AuthResponse>;
+  createAuthRequester<OAuthResponse>(
+    options: OAuthRequesterOptions<OAuthResponse>,
+  ): OAuthRequester<OAuthResponse>;
   authRequest$(): Observable_2<PendingAuthRequest[]>;
 };
 
 // @public
 export const oauthRequestApiRef: ApiRef<OAuthRequestApi>;
 
+// @public
+export type OAuthRequester<TAuthResponse> = (
+  scopes: Set<string>,
+) => Promise<TAuthResponse>;
+
+// @public
+export type OAuthRequesterOptions<TOAuthResponse> = {
+  provider: Omit<AuthProviderInfo, 'id'> & {
+    id?: string;
+  };
+  onAuthRequest(scopes: Set<string>): Promise<TOAuthResponse>;
+};
+
 // @public
 export type OAuthScope = string | string[];
 
@@ -679,10 +691,15 @@ export type PathParams<S extends string> = {
   [name in ParamNames<S>]: string;
 };
 
+// @public @deprecated (undocumented)
+export type PendingAuthRequest = PendingOAuthRequest;
+
 // @public
-export type PendingAuthRequest = {
-  provider: AuthProvider;
-  reject: () => void;
+export type PendingOAuthRequest = {
+  provider: Omit<AuthProviderInfo, 'id'> & {
+    id?: string;
+  };
+  reject(): void;
   trigger(): Promise<void>;
 };
 

packages/core-plugin-api/src/apis/definitions/OAuthRequestApi.ts

@@ -14,31 +14,15 @@
  * limitations under the License.
  */
 
-import { IconComponent } from '../../icons/types';
 import { Observable } from '@backstage/types';
 import { ApiRef, createApiRef } from '../system';
+import { AuthProviderInfo } from './auth';
 
 /**
- * Information about the auth provider that we're requesting a login towards.
- *
- * @remarks
- *
- * This should be shown to the user so that they can be informed about what login is being requested
- * before a popup is shown.
- *
  * @public
+ * @deprecated Use AuthProviderInfo instead
  */
-export type AuthProvider = {
-  /**
-   * Title for the auth provider, for example "GitHub"
-   */
-  title: string;
-
-  /**
-   * Icon for the auth provider.
-   */
-  icon: IconComponent;
-};
+export type AuthProvider = Omit<AuthProviderInfo, 'id'>;
 
 /**
  * Describes how to handle auth requests. Both how to show them to the user, and what to do when
@@ -46,26 +30,34 @@ export type AuthProvider = {
  *
  * @public
  */
-export type AuthRequesterOptions<AuthResponse> = {
+export type OAuthRequesterOptions<TOAuthResponse> = {
   /**
    * Information about the auth provider, which will be forwarded to auth requests.
+   *
+   * Not passing in an `id` is deprecated, and it will be required in the future.
    */
-  provider: AuthProvider;
+  provider: Omit<AuthProviderInfo, 'id'> & { id?: string };
 
   /**
    * Implementation of the auth flow, which will be called synchronously when
    * trigger() is called on an auth requests.
    */
-  onAuthRequest(scopes: Set<string>): Promise<AuthResponse>;
+  onAuthRequest(scopes: Set<string>): Promise<TOAuthResponse>;
 };
 
+/**
+ * @public
+ * @deprecated Use OAuthRequesterOptions instead
+ */
+export type AuthRequesterOptions<T> = OAuthRequesterOptions<T>;
+
 /**
  * Function used to trigger new auth requests for a set of scopes.
  *
  * @remarks
  *
  * The returned promise will resolve to the same value returned by the onAuthRequest in the
- * {@link AuthRequesterOptions}. Or rejected, if the request is rejected.
+ * {@link OAuthRequesterOptions}. Or rejected, if the request is rejected.
  *
  * This function can be called multiple times before the promise resolves. All calls
  * will be merged into one request, and the scopes forwarded to the onAuthRequest will be the
@@ -73,9 +65,15 @@ export type AuthRequesterOptions<AuthResponse> = {
  *
  * @public
  */
-export type AuthRequester<AuthResponse> = (
+export type OAuthRequester<TAuthResponse> = (
   scopes: Set<string>,
-) => Promise<AuthResponse>;
+) => Promise<TAuthResponse>;
+
+/**
+ * @public
+ * @deprecated Use OAuthRequester instead
+ */
+export type AuthRequester<T> = OAuthRequester<T>;
 
 /**
  * An pending auth request for a single auth provider. The request will remain in this pending
@@ -88,16 +86,18 @@ export type AuthRequester<AuthResponse> = (
  *
  * @public
  */
-export type PendingAuthRequest = {
+export type PendingOAuthRequest = {
   /**
    * Information about the auth provider, as given in the AuthRequesterOptions
+   *
+   * Not passing in an `id` is deprecated, and it will be required in the future.
    */
-  provider: AuthProvider;
+  provider: Omit<AuthProviderInfo, 'id'> & { id?: string };
 
   /**
    * Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
    */
-  reject: () => void;
+  reject(): void;
 
   /**
    * Trigger the auth request to continue the auth flow, by for example showing a popup.
@@ -107,6 +107,12 @@ export type PendingAuthRequest = {
   trigger(): Promise<void>;
 };
 
+/**
+ * @public
+ * @deprecated Use PendingOAuthRequest instead
+ */
+export type PendingAuthRequest = PendingOAuthRequest;
+
 /**
  * Provides helpers for implemented OAuth login flows within Backstage.
  *
@@ -125,9 +131,9 @@ export type OAuthRequestApi = {
    *
    * See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info.
    */
-  createAuthRequester<AuthResponse>(
-    options: AuthRequesterOptions<AuthResponse>,
-  ): AuthRequester<AuthResponse>;
+  createAuthRequester<OAuthResponse>(
+    options: OAuthRequesterOptions<OAuthResponse>,
+  ): OAuthRequester<OAuthResponse>;
 
   /**
    * Observers pending auth requests. The returned observable will emit all

packages/core-plugin-api/src/apis/definitions/auth.ts

@@ -15,6 +15,7 @@
  */
 
 import { ApiRef, createApiRef } from '../system';
+import { IconComponent } from '../../icons/types';
 import { Observable } from '@backstage/types';
 
 /**
@@ -28,6 +29,33 @@ import { Observable } from '@backstage/types';
  * const googleAuthApiRef = createApiRef<OAuthApi & OpenIDConnectApi>({ ... })
  */
 
+/**
+ * Information about the auth provider.
+ *
+ * @remarks
+ *
+ * This information is used both to connect the correct auth provider in the backend, as
+ * well as displaying the provider to the user.
+ *
+ * @public
+ */
+export type AuthProviderInfo = {
+  /**
+   * The ID of the auth provider. This should match with ID of the provider in the `@backstage/auth-backend`.
+   */
+  id: string;
+
+  /**
+   * Title for the auth provider, for example "GitHub"
+   */
+  title: string;
+
+  /**
+   * Icon for the auth provider.
+   */
+  icon: IconComponent;
+};
+
 /**
  * An array of scopes, or a scope string formatted according to the
  * auth provider, which is typically a space separated list.