From d4d9f13693d6e3a5915ca1be0cf63ae08b5f36cf Mon Sep 17 00:00:00 2001
From: Oliver Sand <oliver.sand@sda-se.com>
Date: Wed, 16 Jun 2021 09:43:40 +0200
Subject: [PATCH] Improve README

Signed-off-by: Oliver Sand <oliver.sand@sda-se.com>
---
 .../catalog-backend-module-msgraph/README.md  | 42 ++++++++++++++++---
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/plugins/catalog-backend-module-msgraph/README.md b/plugins/catalog-backend-module-msgraph/README.md
index e2f13ebac3..0f1fc360e6 100644
--- a/plugins/catalog-backend-module-msgraph/README.md
+++ b/plugins/catalog-backend-module-msgraph/README.md
@@ -1,8 +1,8 @@
-# Catalog Backend Extension for Microsoft Graph
+# Catalog Backend Module for Microsoft Graph
 
-This is an extension to the `plugin-catalog-backend` plugin, providing a
+This is an extension module to the `plugin-catalog-backend` plugin, providing a
 `MicrosoftGraphOrgReaderProcessor` that can be used to ingest organization data
-from the Microsoft Graph API. This processor is useful, if you want to import
+from the Microsoft Graph API. This processor is useful if you want to import
 users and groups from Office 365.
 
 ## Getting Started
@@ -17,7 +17,8 @@ cd packages/backend
 yarn add @backstage/plugin-catalog-backend-module-msgraph
 ```
 
-2. The `MicrosoftGraphOrgReaderProcessor` is not registered by default, so you have to register it in the catalog plugin:
+2. The `MicrosoftGraphOrgReaderProcessor` is not registered by default, so you
+   have to register it in the catalog plugin:
 
 ```typescript
 // packages/backend/src/plugins/catalog.ts
@@ -28,7 +29,13 @@ builder.addProcessor(
 );
 ```
 
-3. Configure the processor:
+3. 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).
+
+4. Configure the processor:
 
 ```yaml
 # app-config.yaml
@@ -38,18 +45,41 @@ catalog:
       providers:
         - target: https://graph.microsoft.com/v1.0
           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}
+          # 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}
           # Optional filter for user, see Microsoft Graph API for the syntax
+          # See https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties
+          # and for the syntax https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter
           userFilter: accountEnabled eq true and userType eq 'member'
           # Optional filter for group, see Microsoft Graph API for the syntax
+          # See https://docs.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties
           groupFilter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
 ```
 
+5. Add a location that ingests from Microsoft Graph:
+
+```yaml
+# app-config.yaml
+catalog:
+  locations:
+    - type: microsoft-graph-org
+      target: https://graph.microsoft.com/v1.0
+      # If you catalog doesn't allow to import Group and User entities by
+      # default, allow them here
+      rules:
+        - allow: [Group, User]
+    …
+```
+
 ## Customize the Processor
 
-In case you want to customize the ingested entities, the `MicrosoftGraphOrgReaderProcessor` allows to pass transformers for users, groups and the organization.
+In case you want to customize the ingested entities, the `MicrosoftGraphOrgReaderProcessor`
+allows to pass transformers for users, groups and the organization.
 
 1. Create a transformer: