@backstage/plugin-catalog-backend-module-msgraph 0.4.0-next.2 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # @backstage/plugin-catalog-backend-module-msgraph
 
+## 0.4.1
+
+### Patch Changes
+
+- b1995df9f3: Adjust references in deprecation warnings to point to stable URL/document.
+- Updated dependencies
+  - @backstage/backend-tasks@0.3.4
+  - @backstage/plugin-catalog-backend@1.3.1
+
+## 0.4.1-next.0
+
+### Patch Changes
+
+- b1995df9f3: Adjust references in deprecation warnings to point to stable URL/document.
+- Updated dependencies
+  - @backstage/backend-tasks@0.3.4-next.0
+  - @backstage/plugin-catalog-backend@1.3.1-next.0
+
+## 0.4.0
+
+### Minor Changes
+
+- a145672f0f: Align `msgraph` plugin's entity provider config with other providers. **Deprecated** entity processor as well as previous config.
+
+  You will see warning at the log output until you migrate to the new setup.
+  All deprecated parts will be removed eventually after giving some time to migrate.
+
+  Please find information on how to migrate your current setup to the new one below.
+
+  **Migration Guide:**
+
+  There were two different way on how to use the msgraph plugin: processor or provider.
+
+  Previous registration for the processor:
+
+  ```typescript
+  // packages/backend/src/plugins/catalog.ts
+  builder.addProcessor(
+    MicrosoftGraphOrgReaderProcessor.fromConfig(env.config, {
+      logger: env.logger,
+      // [...]
+    }),
+  );
+  ```
+
+  Previous registration when using the provider:
+
+  ```typescript
+  // packages/backend/src/plugins/catalog.ts
+  builder.addEntityProvider(
+    MicrosoftGraphOrgEntityProvider.fromConfig(env.config, {
+      id: 'https://graph.microsoft.com/v1.0',
+      target: 'https://graph.microsoft.com/v1.0',
+      logger: env.logger,
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 30 },
+        timeout: { minutes: 3 },
+      }),
+      // [...]
+    }),
+  );
+  ```
+
+  Previous configuration as used for both:
+
+  ```yaml
+  # app-config.yaml
+  catalog:
+    processors:
+      microsoftGraphOrg:
+        providers:
+          - target: https://graph.microsoft.com/v1.0
+            # [...]
+  ```
+
+  **Replacement:**
+
+  Please check https://github.com/backstage/backstage/blob/master/plugins/catalog-backend-module-msgraph/README.md for the complete documentation of all configuration options (config as well as registration of the provider).
+
+  ```yaml
+  # app-config.yaml
+  catalog:
+    providers:
+      microsoftGraphOrg:
+        # In case you used the deprecated configuration with the entity provider
+        # using the value of `target` will keep the same location key for all
+        providerId: # some stable ID which will be used as part of the location key for all ingested data
+          target: https://graph.microsoft.com/v1.0
+          # [...]
+  ```
+
+  ```typescript
+  // packages/backend/src/plugins/catalog.ts
+  builder.addEntityProvider(
+    MicrosoftGraphOrgEntityProvider.fromConfig(env.config, {
+      logger: env.logger,
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 30 },
+        timeout: { minutes: 3 },
+      }),
+      // [...]
+    }),
+  );
+  ```
+
+  In case you've used multiple entity providers before
+  **and** you had different transformers for each of them
+  you can provide these directly at the one `fromConfig` call
+  by passing a Record with the provider ID as key.
+
+- b8ebecd100: Microsoft Graph plugin can supports many more options for authenticating with the Microsoft Graph API.
+  Previously only ClientId/ClientSecret was supported, but now all the authentication options of `DefaultAzureCredential` from `@azure/identity` are supported.
+  Including Managed Identity, Client Certificate, Azure CLI and VS Code.
+
+  If `clientId` and `clientSecret` are specified in configuration, the plugin behaves the same way as before.
+  If these fields are omitted, the plugin uses `DefaultAzureCredential` to automatically determine the best authentication method.
+  This is particularly useful for local development environments - the default configuration will try to use existing credentials from Visual Studio Code, Azure CLI and Azure PowerShell, without the user needing to configure any credentials in app-config.yaml
+
+### Patch Changes
+
+- a70869e775: Updated dependency `msw` to `^0.43.0`.
+- 8006d0f9bf: Updated dependency `msw` to `^0.44.0`.
+- Updated dependencies
+  - @backstage/plugin-catalog-backend@1.3.0
+  - @backstage/catalog-model@1.1.0
+  - @backstage/backend-tasks@0.3.3
+
 ## 0.4.0-next.2
 
 ### Patch Changes

package/README.md

@@ -6,13 +6,18 @@ This provider is useful if you want to import users and groups from Azure Active
 
 ## Getting Started
 
-1. Create or use an existing App registration in the [Microsoft Azure Portal](https://portal.azure.com/).
-   The App registration requires at least the API permissions `Group.Read.All`,
-   `GroupMember.Read.All`, `User.Read` and `User.Read.All` for Microsoft Graph
-   (if you still run into errors about insufficient privileges, add
-   `Team.ReadBasic.All` and `TeamMember.Read.All` too).
+1. Choose your authentication method - all methods supported by [DefaultAzureCredential](https://docs.microsoft.com/en-us/javascript/api/overview/azure/identity-readme?view=azure-node-latest#defaultazurecredential)
 
-2. Configure the entity provider:
+   - For local dev, use Azure CLI, Azure PowerShell or Visual Studio Code for authentication
+   - If your infrastructure supports Managed Identity, use that
+   - Otherwise use an App Registration
+
+1. If using Managed Identity or App Registration for authentication, grant the following application permissions (not delegated)
+
+   - `GroupMember.Read.All`
+   - `User.Read.All`
+
+1. Configure the entity provider:
 
 ```yaml
 # app-config.yaml
@@ -24,11 +29,13 @@ catalog:
         authority: https://login.microsoftonline.com
         # If you don't know you tenantId, you can use Microsoft Graph Explorer
         # to query it
-        tenantId: ${MICROSOFT_GRAPH_TENANT_ID}
+        tenantId: ${AZURE_TENANT_ID}
+        # Optional ClientId and ClientSecret if you don't want to use `DefaultAzureCredential`
+        # for authentication
         # Client Id and Secret can be created under Certificates & secrets in
         # the App registration in the Microsoft Azure Portal.
-        clientId: ${MICROSOFT_GRAPH_CLIENT_ID}
-        clientSecret: ${MICROSOFT_GRAPH_CLIENT_SECRET_TOKEN}
+        clientId: ${AZURE_CLIENT_ID}
+        clientSecret: ${AZURE_CLIENT_SECRET}
         # Optional mode for querying which defaults to "basic".
         # By default, the Microsoft Graph API only provides the basic feature set
         # for querying. Certain features are limited to advanced querying capabilities.
@@ -108,8 +115,9 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-msgraph
 +    MicrosoftGraphOrgEntityProvider.fromConfig(env.config, {
 +      logger: env.logger,
 +      schedule: env.scheduler.createScheduledTaskRunner({
-+        frequency: { minutes: 5 },
-+        timeout: { minutes: 3 },
++        frequency: { hours: 1 },
++        timeout: { minutes: 50 },
++        initialDelay: { seconds: 15}
 +      }),
 +    }),
 +  );

package/config.d.ts

@@ -50,13 +50,13 @@ export interface Config {
           /**
            * The OAuth client ID to use for authenticating requests.
            */
-          clientId: string;
+          clientId?: string;
           /**
            * The OAuth client secret to use for authenticating requests.
            *
            * @visibility secret
            */
-          clientSecret: string;
+          clientSecret?: string;
 
           // TODO: Consider not making these config options and pass them in the
           // constructor instead. They are probably not environment specific, so
@@ -130,13 +130,13 @@ export interface Config {
             /**
              * The OAuth client ID to use for authenticating requests.
              */
-            clientId: string;
+            clientId?: string;
             /**
              * The OAuth client secret to use for authenticating requests.
              *
              * @visibility secret
              */
-            clientSecret: string;
+            clientSecret?: string;
 
             user?: {
               /**