Utility API for VMware Cloud auth

Signed-off-by: Jamie Klassen <jamie.klassen@broadcom.com>

.changeset/kind-wombats-draw.md

@@ -0,0 +1,11 @@
+---
+'@backstage/core-plugin-api': minor
+'@backstage/app-defaults': minor
+'@backstage/core-app-api': minor
+'@backstage/frontend-plugin-api': patch
+---
+
+Added a utility API for VMware Cloud auth; the API ref is available in the
+`@backstage/core-plugin-api` and `@backstage/frontend-plugin-api` packages, the
+implementation is in `@backstage/core-app-api` and a factory has been added to
+`@backstage/app-defaults`.

packages/app-defaults/src/defaults/apis.ts

@@ -34,6 +34,7 @@ import {
   AtlassianAuth,
   createFetchApi,
   FetchMiddlewares,
+  VMwareCloudAuth,
 } from '@backstage/core-app-api';
 
 import {
@@ -56,6 +57,7 @@ import {
   bitbucketAuthApiRef,
   bitbucketServerAuthApiRef,
   atlassianAuthApiRef,
+  vmwareCloudAuthApiRef,
 } from '@backstage/core-plugin-api';
 import {
   permissionApiRef,
@@ -259,6 +261,22 @@ export const apis = [
       });
     },
   }),
+  createApiFactory({
+    api: vmwareCloudAuthApiRef,
+    deps: {
+      discoveryApi: discoveryApiRef,
+      oauthRequestApi: oauthRequestApiRef,
+      configApi: configApiRef,
+    },
+    factory: ({ discoveryApi, oauthRequestApi, configApi }) => {
+      return VMwareCloudAuth.create({
+        configApi,
+        discoveryApi,
+        oauthRequestApi,
+        environment: configApi.getOptionalString('auth.environment'),
+      });
+    },
+  }),
   createApiFactory({
     api: permissionApiRef,
     deps: {

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

@@ -64,6 +64,7 @@ import { SessionState } from '@backstage/core-plugin-api';
 import { StorageApi } from '@backstage/core-plugin-api';
 import { StorageValueSnapshot } from '@backstage/core-plugin-api';
 import { SubRouteRef } from '@backstage/core-plugin-api';
+import { vmwareCloudAuthApiRef } from '@backstage/core-plugin-api';
 
 // @public
 export class AlertApiForwarder implements AlertApi {
@@ -651,6 +652,12 @@ export class UrlPatternDiscovery implements DiscoveryApi {
   getBaseUrl(pluginId: string): Promise<string>;
 }
 
+// @public
+export class VMwareCloudAuth {
+  // (undocumented)
+  static create(options: OAuthApiCreateOptions): typeof vmwareCloudAuthApiRef.T;
+}
+
 // @public
 export class WebStorage implements StorageApi {
   constructor(namespace: string, errorApi: ErrorApi);

packages/core-app-api/src/apis/implementations/auth/index.ts

@@ -25,4 +25,5 @@ export * from './onelogin';
 export * from './bitbucket';
 export * from './bitbucketServer';
 export * from './atlassian';
+export * from './vmwareCloud';
 export type { OAuthApiCreateOptions, AuthApiCreateOptions } from './types';

packages/core-app-api/src/apis/implementations/auth/vmwareCloud/VMwareCloudAuth.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { vmwareCloudAuthApiRef } from '@backstage/core-plugin-api';
+import { OAuth2 } from '../oauth2';
+import { OAuthApiCreateOptions } from '../types';
+
+const DEFAULT_PROVIDER = {
+  id: 'vmwareCloudServices',
+  title: 'VMware Cloud',
+  icon: () => null,
+};
+
+/**
+ * Implements the OAuth flow for VMware Cloud Services
+ *
+ * @public
+ */
+export default class VMwareCloudAuth {
+  static create(
+    options: OAuthApiCreateOptions,
+  ): typeof vmwareCloudAuthApiRef.T {
+    const {
+      configApi,
+      discoveryApi,
+      oauthRequestApi,
+      environment = 'development',
+      provider = DEFAULT_PROVIDER,
+      defaultScopes = ['openid'],
+    } = options;
+
+    return OAuth2.create({
+      configApi,
+      discoveryApi,
+      oauthRequestApi,
+      provider,
+      environment,
+      defaultScopes,
+    });
+  }
+}

packages/core-app-api/src/apis/implementations/auth/vmwareCloud/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { default as VMwareCloudAuth } from './VMwareCloudAuth';

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

@@ -776,6 +776,15 @@ export function useRouteRefParams<Params extends AnyParams>(
   _routeRef: RouteRef<Params> | SubRouteRef<Params>,
 ): Params;
 
+// @public
+export const vmwareCloudAuthApiRef: ApiRef<
+  OAuthApi &
+    OpenIdConnectApi &
+    ProfileInfoApi &
+    BackstageIdentityApi &
+    SessionApi
+>;
+
 // @public
 export function withApis<T extends {}>(
   apis: TypesToApiRefs<T>,

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

@@ -450,3 +450,22 @@ export const atlassianAuthApiRef: ApiRef<
 > = createApiRef({
   id: 'core.auth.atlassian',
 });
+
+/**
+ * Provides authentication towards VMware Cloud APIs and identities.
+ *
+ * @public
+ * @remarks
+ *
+ * For more info about VMware Cloud identity and access management:
+ * - {@link https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-53D39337-D93A-4B84-BD18-DDF43C21479A.html}
+ */
+export const vmwareCloudAuthApiRef: ApiRef<
+  OAuthApi &
+    OpenIdConnectApi &
+    ProfileInfoApi &
+    BackstageIdentityApi &
+    SessionApi
+> = createApiRef({
+  id: 'core.auth.vmware-cloud',
+});

packages/frontend-app-api/src/wiring/createApp.test.tsx

@@ -291,6 +291,7 @@ describe('createApp', () => {
           <api:core.auth.bitbucket out=[core.api.factory] />
           <api:core.auth.bitbucket-server out=[core.api.factory] />
           <api:core.auth.atlassian out=[core.api.factory] />
+          <api:core.auth.vmware-cloud out=[core.api.factory] />
           <api:plugin.permission.api out=[core.api.factory] />
         ]
       </app>"

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

@@ -86,6 +86,7 @@ import { TypesToApiRefs } from '@backstage/core-plugin-api';
 import { useApi } from '@backstage/core-plugin-api';
 import { useApiHolder } from '@backstage/core-plugin-api';
 import { useTranslationRef } from '@backstage/core-plugin-api/alpha';
+import { vmwareCloudAuthApiRef } from '@backstage/core-plugin-api';
 import { withApis } from '@backstage/core-plugin-api';
 import { z } from 'zod';
 import { ZodSchema } from 'zod';
@@ -1167,5 +1168,7 @@ export function useRouteRefParams<Params extends AnyRouteRefParams>(
 
 export { useTranslationRef };
 
+export { vmwareCloudAuthApiRef };
+
 export { withApis };
 ```

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

@@ -36,4 +36,5 @@ export {
   oktaAuthApiRef,
   microsoftAuthApiRef,
   oneloginAuthApiRef,
+  vmwareCloudAuthApiRef,
 } from '@backstage/core-plugin-api';