0.5.25 • Published 17 hours ago

@backstage/plugin-catalog-backend-module-msgraph v0.5.25

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
17 hours ago

Catalog Backend Module for Microsoft Graph

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 users and groups from Azure Active Directory or Office 365.

Getting Started

  1. The processor is not installed by default, therefore you have to add a dependency to @backstage/plugin-catalog-backend-module-msgraph to your backend package.
# From your Backstage root directory
cd packages/backend
yarn add @backstage/plugin-catalog-backend-module-msgraph
  1. The MicrosoftGraphOrgReaderProcessor is not registered by default, so you have to register it in the catalog plugin:
// packages/backend/src/plugins/catalog.ts
builder.addProcessor(
  MicrosoftGraphOrgReaderProcessor.fromConfig(config, {
    logger,
  }),
);
  1. Create or use an existing App registration in the Microsoft Azure Portal. 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).

  2. Configure the processor:

# app-config.yaml
catalog:
  processors:
    microsoftGraphOrg:
      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')
  1. Add a location that ingests from Microsoft Graph:
# 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.

  1. Create a transformer:
export async function myGroupTransformer(
  group: MicrosoftGraph.Group,
  groupPhoto?: string,
): Promise<GroupEntity | undefined> {
  if (
    ((group as unknown) as {
      creationOptions: string[];
    }).creationOptions.includes('ProvisionGroupHomepage')
  ) {
    return undefined;
  }

  // Transformations may change namespace, change entity naming pattern, fill
  // profile with more or other details...

  // Create the group entity on your own, or wrap the default transformer
  return await defaultGroupTransformer(group, groupPhoto);
}
  1. Configure the processor with the transformer:
builder.addProcessor(
  MicrosoftGraphOrgReaderProcessor.fromConfig(config, {
    logger,
    groupTransformer: myGroupTransformer,
  }),
);
0.5.26-next.2

3 days ago

0.5.26-next.1

10 days ago

0.5.26-next.0

17 days ago

0.5.25

24 days ago

0.5.25-next.1

1 month ago

0.5.25-next.0

1 month ago

0.5.24

1 month ago

0.5.22

2 months ago

0.5.23

2 months ago

0.5.21

2 months ago

0.5.21-next.2

2 months ago

0.5.21-next.1

2 months ago

0.5.20

2 months ago

0.5.20-next.0

2 months ago

0.5.18

3 months ago

0.5.19

3 months ago

0.5.17

3 months ago

0.5.17-next.3

3 months ago

0.5.17-next.2

3 months ago

0.5.17-next.1

3 months ago

0.5.17-next.0

4 months ago

0.5.16

4 months ago

0.5.16-next.2

4 months ago

0.5.16-next.1

4 months ago

0.5.16-next.0

5 months ago

0.5.15

5 months ago

0.5.15-next.3

5 months ago

0.5.15-next.2

5 months ago

0.5.15-next.1

5 months ago

0.5.6

10 months ago

0.5.9-next.0

9 months ago

0.5.10

8 months ago

0.5.11

8 months ago

0.5.12-next.0

8 months ago

0.5.12-next.1

7 months ago

0.5.14

6 months ago

0.5.12

7 months ago

0.5.13

7 months ago

0.5.7-next.0

10 months ago

0.5.7-next.1

9 months ago

0.5.7-next.2

9 months ago

0.5.13-next.2

7 months ago

0.5.8

9 months ago

0.5.7

9 months ago

0.5.9

9 months ago

0.5.10-next.1

9 months ago

0.5.10-next.3

8 months ago

0.5.10-next.2

8 months ago

0.5.15-next.0

6 months ago

0.5.14-next.0

7 months ago

0.5.14-next.1

6 months ago

0.5.14-next.2

6 months ago

0.5.5-next.2

11 months ago

0.5.5

11 months ago

0.5.6-next.0

11 months ago

0.5.5-next.1

12 months ago

0.5.5-next.0

12 months ago

0.5.4

12 months ago

0.5.4-next.1

1 year ago

0.5.3

1 year ago

0.5.3-next.3

1 year ago

0.5.4-next.0

1 year ago

0.5.0

1 year ago

0.5.2

1 year ago

0.5.1

1 year ago

0.5.2-next.1

1 year ago

0.5.2-next.2

1 year ago

0.5.2-next.0

1 year ago

0.5.3-next.1

1 year ago

0.5.3-next.0

1 year ago

0.5.3-next.2

1 year ago

0.4.6-next.1

1 year ago

0.4.6-next.2

1 year ago

0.4.8-next.1

1 year ago

0.4.8-next.0

1 year ago

0.4.7

1 year ago

0.4.6

1 year ago

0.5.0-next.2

1 year ago

0.4.6-next.0

1 year ago

0.4.4-next.1

2 years ago

0.4.4-next.0

2 years ago

0.4.5-next.3

1 year ago

0.4.5-next.1

1 year ago

0.4.5-next.2

1 year ago

0.4.5-next.0

1 year ago

0.4.5

1 year ago

0.4.4

1 year ago

0.4.3

2 years ago

0.4.3-next.0

2 years ago

0.4.3-next.1

2 years ago

0.4.3-next.2

2 years ago

0.4.2-next.2

2 years ago

0.4.2-next.3

2 years ago

0.4.2-next.0

2 years ago

0.4.2-next.1

2 years ago

0.4.2

2 years ago

0.4.1-next.0

2 years ago

0.3.3-next.0

2 years ago

0.3.3-next.1

2 years ago

0.4.0-next.2

2 years ago

0.4.0-next.1

2 years ago

0.3.3

2 years ago

0.4.1

2 years ago

0.4.0

2 years ago

0.3.4-next.0

2 years ago

0.3.2

2 years ago

0.3.2-next.1

2 years ago

0.3.2-next.0

2 years ago

0.2.19

2 years ago

0.3.0

2 years ago

0.3.1

2 years ago

0.3.1-next.2

2 years ago

0.3.1-next.0

2 years ago

0.3.1-next.1

2 years ago

0.2.19-next.0

2 years ago

0.2.18

2 years ago

0.2.17

2 years ago

0.2.16

2 years ago

0.2.15

2 years ago

0.2.14

2 years ago

0.2.13

2 years ago

0.2.12

2 years ago

0.2.13-next.0

2 years ago

0.2.15-next.0

2 years ago

0.2.14-next.0

2 years ago

0.2.11

2 years ago

0.2.10

2 years ago

0.2.9

2 years ago

0.2.7

3 years ago

0.2.6

3 years ago

0.2.8

3 years ago

0.2.5

3 years ago

0.2.4

3 years ago

0.2.3

3 years ago

0.2.2

3 years ago

0.2.1

3 years ago

0.2.0

3 years ago

0.1.1

3 years ago

0.1.0

3 years ago