# @backstage/plugin-catalog-backend-module-msgraph > A Backstage catalog backend module that helps integrate towards Microsoft Graph Latest version **0.10.6** (published 2026-09-15) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @backstage/plugin-catalog-backend-module-msgraph pnpm add @backstage/plugin-catalog-backend-module-msgraph yarn add @backstage/plugin-catalog-backend-module-msgraph bun add @backstage/plugin-catalog-backend-module-msgraph ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; pre 1.0. ## Facts | | | |---|---| | Version | 0.10.6 | | Published | 2026-09-15 | | First published | 2021-06-18 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 10 | | Unpacked size | 320 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | patriko, freben, marcuseide | | Keywords | backstage | ## Links - npm: https://www.npmjs.com/package/@backstage/plugin-catalog-backend-module-msgraph - Repository: https://github.com/backstage/backstage - Homepage: https://backstage.io - npm.io page: https://npm.io/package/@backstage/plugin-catalog-backend-module-msgraph ## Dependencies (10) - [qs](https://npm.io/package/qs.md) ^6.15.2 - [lodash](https://npm.io/package/lodash.md) ^4.17.21 - [p-limit](https://npm.io/package/p-limit.md) ^3.0.2 - [@azure/identity](https://npm.io/package/@azure/identity.md) ^4.0.0 - [@backstage/config](https://npm.io/package/@backstage/config.md) ^1.3.9 - [@backstage/catalog-model](https://npm.io/package/@backstage/catalog-model.md) ^1.10.1 - [@backstage/backend-plugin-api](https://npm.io/package/@backstage/backend-plugin-api.md) ^1.10.1 - [@backstage/plugin-catalog-node](https://npm.io/package/@backstage/plugin-catalog-node.md) ^2.2.5 - [@backstage/plugin-catalog-common](https://npm.io/package/@backstage/plugin-catalog-common.md) ^1.2.0 - [@microsoft/microsoft-graph-types](https://npm.io/package/@microsoft/microsoft-graph-types.md) ^2.6.0 ## Recent versions - 0.10.6 (latest) — 2026-09-15 - 0.10.7-next.1 (next) — 2026-09-29 - 0.0.0-nightly-20260928023907 (nightly) — 2026-09-28 - 0.0.0-nightly-20260927023342 — 2026-09-27 - 0.0.0-nightly-20260926022852 — 2026-09-26 - 0.0.0-nightly-20260925022940 — 2026-09-25 - 0.0.0-nightly-20260924023050 — 2026-09-24 - 0.0.0-nightly-20260923023054 — 2026-09-23 - 0.10.7-next.0 — 2026-09-22 - 0.0.0-nightly-20260922023058 — 2026-09-22 - 0.0.0-nightly-20260921023416 — 2026-09-21 - 0.0.0-nightly-20260920023043 — 2026-09-20 - 0.0.0-nightly-20260919022921 — 2026-09-19 - 0.0.0-nightly-20260918023200 — 2026-09-18 - 0.0.0-nightly-20260909022715 — 2026-09-09 - … 1706 more at https://npm.io/package/@backstage/plugin-catalog-backend-module-msgraph/versions ## README # Catalog Backend Module for Microsoft Graph This is an extension module to the `plugin-catalog-backend` plugin, providing a `MicrosoftGraphOrgEntityProvider` that can be used to ingest organization data from the Microsoft Graph API. This provider is useful if you want to import users and groups from Entra Id (formerly Azure Active Directory) or Office 365. ## Getting Started 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) - 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 catalog: providers: microsoftGraphOrg: providerId: 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: ${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: ${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. # (See https://docs.microsoft.com/en-us/graph/aad-advanced-queries) queryMode: basic # basic | advanced # Optional configuration block user: # Optional parameter to include the expanded resource or collection referenced # by a single relationship (navigation property) in your results. # Only one relationship can be expanded in a single request. # See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter # Can be combined with userGroupMember[...] instead of userFilter. expand: manager # 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 # This is combined with the base `accountEnabled eq true` filter # that is always applied automatically. filter: userType eq 'member' # Set to false to not load user photos. loadPhotos: true # See https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0 select: ['id', 'displayName', 'description'] # Optional /users by default but allow to query users from different msgraph endpoints path: /users # Optional configuration block userGroupMember: # Optional filter for users, use group membership to get users. # (Filtered groups and fetch their members.) # See https://docs.microsoft.com/en-us/graph/search-query-parameter filter: "displayName eq 'Backstage Users'" # Optional search for users, use group membership to get users. # (Search for groups and fetch their members.) search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' # Optional /groups by default but allow to query groups from different msgraph endpoints path: /groups # Optional configuration block group: # Optional parameter to include the expanded resource or collection referenced # by a single relationship (navigation property) in your results. # Only one relationship can be expanded in a single request. # See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter # Can be combined with userGroupMember[...] instead of userFilter. expand: 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 filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified') # Optional search for groups, see Microsoft Graph API for the syntax # See https://docs.microsoft.com/en-us/graph/search-query-parameter search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' # Optional select for groups, this will allow you work with schemaExtensions # in order to add extra information to your groups that can be used on your custom groupTransformers # See https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0 select: ['id', 'displayName', 'description'] # Optional /groups by default but allow to query groups from different msgraph endpoints path: /groups schedule: # optional; same options as in TaskScheduleDefinition # supports cron, ISO duration, "human duration" as used in code frequency: { hours: 1 } # supports ISO duration, "human duration" as used in code timeout: { minutes: 50 } # supports ISO duration, "human duration" as used in code initialDelay: { seconds: 15}, ``` By default, all enabled users are loaded (disabled accounts are automatically filtered out). If you want to further filter users based on their attributes, use `user.filter`. `userGroupMember.filter` can be used if you want to load users based on their group membership. 3. The package is not installed by default, therefore you have to add a dependency to `@backstage/plugin-catalog-backend-module-msgraph` to your backend package. ```bash # From your Backstage root directory yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-msgraph ``` 4. The `MicrosoftGraphOrgEntityProvider` is not registered by default, so you have to register it in the catalog plugin. Pass the target to reference a provider from the configuration. ```diff // packages/backend/src/plugins/catalog.ts +import { MicrosoftGraphOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-msgraph'; export default async function createPlugin( env: PluginEnvironment, ): Promise { const builder = await CatalogBuilder.create(env); + builder.addEntityProvider( + MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { + logger: env.logger, + scheduler, + }), + ); ``` Instead of configuring the refresh schedule inside the config (per provider instance), you can define it in code (for all of them): ```diff - scheduler, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { hours: 1 }, + timeout: { minutes: 50 }, + initialDelay: { seconds: 15}, + }), ``` ## Customize the Processor or Entity Provider In case you want to customize the ingested entities, the `MicrosoftGraphOrgEntityProvider` allows to pass transformers for users, groups and the organization. 1. Create a transformer: ```ts export async function myGroupTransformer( group: MicrosoftGraph.Group, groupPhoto?: string, ): Promise { 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); } ``` 2. Add the transformer: ```diff builder.addEntityProvider( MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { logger: env.logger, scheduler, + groupTransformer: myGroupTransformer, }), ); ``` --- _Source: https://npm.io/package/@backstage/plugin-catalog-backend-module-msgraph · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._