From af015ceecc1c0312dd56f1e7c13c72ae7a3fa308 Mon Sep 17 00:00:00 2001 From: Martin Machacek Date: Fri, 5 Jun 2026 15:07:29 +0200 Subject: [PATCH] Adds 'entra agent blueprintprincipal list' command. Closes #7253 --- .../agent/agent-blueprintprincipal-list.mdx | 145 ++++++++++++++++ docs/src/config/sidebars.ts | 9 + eslint.config.mjs | 2 + src/config.ts | 1 + src/m365/entra/commands.ts | 1 + .../agent-blueprintprincipal-list.spec.ts | 163 ++++++++++++++++++ .../agent/agent-blueprintprincipal-list.ts | 61 +++++++ 7 files changed, 382 insertions(+) create mode 100644 docs/docs/cmd/entra/agent/agent-blueprintprincipal-list.mdx create mode 100644 src/m365/entra/commands/agent/agent-blueprintprincipal-list.spec.ts create mode 100644 src/m365/entra/commands/agent/agent-blueprintprincipal-list.ts diff --git a/docs/docs/cmd/entra/agent/agent-blueprintprincipal-list.mdx b/docs/docs/cmd/entra/agent/agent-blueprintprincipal-list.mdx new file mode 100644 index 00000000000..cb956cef358 --- /dev/null +++ b/docs/docs/cmd/entra/agent/agent-blueprintprincipal-list.mdx @@ -0,0 +1,145 @@ +import Global from '../../_global.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# entra agent blueprintprincipal list + +Retrieves a list of agent blueprint principals + +## Usage + +```sh +m365 entra agent blueprintprincipal list [options] +``` + +## Options + +```md definition-list +`-p, --properties [properties]` +: Comma-separated list of properties to retrieve. +``` + + + +## Remarks + +Using the `--properties` option, you can specify a comma-separated list of agent blueprint principal properties to retrieve from the Microsoft Graph. If you don't specify any properties, the command will output the default properties returned by Graph. + +## Permissions + + + + + | Resource | Permissions | + |-----------------|------------------------------------------| + | Microsoft Graph | AgentIdentityBlueprintPrincipal.Read.All | + + + + + | Resource | Permissions | + |-----------------|------------------------------------------| + | Microsoft Graph | AgentIdentityBlueprintPrincipal.Read.All | + + + + +## Examples + +Retrieve all agent blueprint principals + +```sh +m365 entra agent blueprintprincipal list +``` + +Retrieve id and name of agent blueprint principals + +```sh +m365 entra agent blueprintprincipal list --properties 'id,appDisplayName' +``` + +## Response + + + + + ```json + [ + { + "accountEnabled": true, + "appDescription": null, + "appDisplayName": "OcnAgentBluePrint02", + "appId": "0e81af7f-b058-470a-84be-3a4f5a8014ca", + "appOwnerOrganizationId": "70cf0eca-e1e8-4d78-9d03-62ecf811dfc2", + "appRoleAssignmentRequired": false, + "createdByAppId": "14d82eec-204b-4c2f-b7e8-296a70dab67e", + "disabledByMicrosoftStatus": null, + "displayName": "OcnAgentBluePrint02", + "servicePrincipalNames": [ + "0e81af7f-b058-470a-84be-3a4f5a8014ca" + ], + "servicePrincipalType": "Application", + "signInAudience": "AzureADMyOrg", + "tags": [], + "id": "59246ef4-b832-48eb-a5e0-87748132e12c", + "appRoles": [], + "info": { + "logoUrl": null, + "marketingUrl": null, + "privacyStatementUrl": null, + "supportUrl": null, + "termsOfServiceUrl": null + }, + "oauth2PermissionScopes": [], + "verifiedPublisher": { + "displayName": null, + "verifiedPublisherId": null, + "addedDateTime": null + } + } + ] + ``` + + + + + ```text + id appDisplayName appId + ------------------------------------ ------------------- ------------------------------------ + 59246ef4-b832-48eb-a5e0-87748132e12c OcnAgentBluePrint02 0e81af7f-b058-470a-84be-3a4f5a8014ca + ``` + + + + + ```csv + accountEnabled,appDescription,appDisplayName,appId,appOwnerOrganizationId,appRoleAssignmentRequired,createdByAppId,disabledByMicrosoftStatus,displayName,servicePrincipalType,signInAudience,id + 1,,OcnAgentBluePrint02,0e81af7f-b058-470a-84be-3a4f5a8014ca,70cf0eca-e1e8-4d78-9d03-62ecf811dfc2,0,14d82eec-204b-4c2f-b7e8-296a70dab67e,,OcnAgentBluePrint02,Application,AzureADMyOrg,59246ef4-b832-48eb-a5e0-87748132e12c + ``` + + + + + ```md + # entra agent blueprintprincipal list --debug "false" --verbose "false" + + Date: 6/5/2026 + + ## OcnAgentBluePrint02 (59246ef4-b832-48eb-a5e0-87748132e12c) + + Property | Value + ---------|------- + accountEnabled | true + appDisplayName | OcnAgentBluePrint02 + appId | 0e81af7f-b058-470a-84be-3a4f5a8014ca + appOwnerOrganizationId | 70cf0eca-e1e8-4d78-9d03-62ecf811dfc2 + appRoleAssignmentRequired | false + createdByAppId | 14d82eec-204b-4c2f-b7e8-296a70dab67e + displayName | OcnAgentBluePrint02 + servicePrincipalType | Application + signInAudience | AzureADMyOrg + id | 59246ef4-b832-48eb-a5e0-87748132e12c + ``` + + + \ No newline at end of file diff --git a/docs/src/config/sidebars.ts b/docs/src/config/sidebars.ts index ec1463235f8..e70e0c8cefa 100644 --- a/docs/src/config/sidebars.ts +++ b/docs/src/config/sidebars.ts @@ -249,6 +249,15 @@ const sidebars: SidebarsConfig = { } ] }, + { + agent: [ + { + type: 'doc', + label: 'agent blueprintprincipal list', + id: 'cmd/entra/agent/agent-blueprintprincipal-list' + } + ] + }, { app: [ { diff --git a/eslint.config.mjs b/eslint.config.mjs index 925703e197b..682ca51fc83 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -14,6 +14,7 @@ const dictionary = [ 'activations', 'adaptive', 'administrative', + 'agent', 'ai', 'app', 'application', @@ -26,6 +27,7 @@ const dictionary = [ 'autofill', 'azure', 'bin', + 'blueprintprincipal', 'brand', 'builder', 'calendar', diff --git a/src/config.ts b/src/config.ts index 8218037c14f..ad1e1752c04 100644 --- a/src/config.ts +++ b/src/config.ts @@ -4,6 +4,7 @@ export default { allScopes: [ 'https://management.azure.com/user_impersonation', 'https://admin.services.crm.dynamics.com/user_impersonation', + 'https://graph.microsoft.com/AgentIdentityBlueprintPrincipal.Read.All', 'https://graph.microsoft.com/AppCatalog.ReadWrite.All', 'https://graph.microsoft.com/AuditLog.Read.All', 'https://graph.microsoft.com/Bookings.Read.All', diff --git a/src/m365/entra/commands.ts b/src/m365/entra/commands.ts index 1b9476ec605..60c93fdadc6 100644 --- a/src/m365/entra/commands.ts +++ b/src/m365/entra/commands.ts @@ -10,6 +10,7 @@ export default { ADMINISTRATIVEUNIT_MEMBER_LIST: `${prefix} administrativeunit member list`, ADMINISTRATIVEUNIT_MEMBER_REMOVE: `${prefix} administrativeunit member remove`, ADMINISTRATIVEUNIT_ROLEASSIGNMENT_ADD: `${prefix} administrativeunit roleassignment add`, + AGENT_BLUEPRINTPRINCIPAL_LIST: `${prefix} agent blueprintprincipal list`, APP_ADD: `${prefix} app add`, APP_GET: `${prefix} app get`, APP_LIST: `${prefix} app list`, diff --git a/src/m365/entra/commands/agent/agent-blueprintprincipal-list.spec.ts b/src/m365/entra/commands/agent/agent-blueprintprincipal-list.spec.ts new file mode 100644 index 00000000000..41eb770b3ac --- /dev/null +++ b/src/m365/entra/commands/agent/agent-blueprintprincipal-list.spec.ts @@ -0,0 +1,163 @@ +import assert from 'assert'; +import sinon from 'sinon'; +import auth from '../../../../Auth.js'; +import { cli } from '../../../../cli/cli.js'; +import { CommandInfo } from '../../../../cli/CommandInfo.js'; +import { Logger } from '../../../../cli/Logger.js'; +import { CommandError } from '../../../../Command.js'; +import request from '../../../../request.js'; +import { telemetry } from '../../../../telemetry.js'; +import { pid } from '../../../../utils/pid.js'; +import { session } from '../../../../utils/session.js'; +import { sinonUtil } from '../../../../utils/sinonUtil.js'; +import commands from '../../commands.js'; +import command, { options } from './agent-blueprintprincipal-list.js'; + +describe(commands.AGENT_BLUEPRINTPRINCIPAL_LIST, () => { + let log: string[]; + let logger: Logger; + let loggerLogSpy: sinon.SinonSpy; + let commandInfo: CommandInfo; + let commandOptionsSchema: typeof options; + + const response = [ + { + "accountEnabled": true, + "appDescription": null, + "appDisplayName": "OcnAgentBluePrint02", + "appId": "0e81af7f-b058-470a-84be-3a4f5a8014ca", + "appOwnerOrganizationId": "70cf0eca-e1e8-4d78-9d03-62ecf811dfc2", + "appRoleAssignmentRequired": false, + "createdByAppId": "14d82eec-204b-4c2f-b7e8-296a70dab67e", + "disabledByMicrosoftStatus": null, + "displayName": "OcnAgentBluePrint02", + "servicePrincipalNames": [ + "0e81af7f-b058-470a-84be-3a4f5a8014ca" + ], + "servicePrincipalType": "Application", + "signInAudience": "AzureADMyOrg", + "tags": [], + "id": "59246ef4-b832-48eb-a5e0-87748132e12c", + "appRoles": [], + "info": { + "logoUrl": null, + "marketingUrl": null, + "privacyStatementUrl": null, + "supportUrl": null, + "termsOfServiceUrl": null + }, + "oauth2PermissionScopes": [], + "verifiedPublisher": { + "displayName": null, + "verifiedPublisherId": null, + "addedDateTime": null + } + } + ]; + + const limitedResponse = [ + { + "id": "59246ef4-b832-48eb-a5e0-87748132e12c", + "appDisplayName": "OcnAgentBluePrint02" + } + ]; + + before(() => { + sinon.stub(auth, 'restoreAuth').resolves(); + sinon.stub(telemetry, 'trackEvent').resolves(); + sinon.stub(pid, 'getProcessName').returns(''); + sinon.stub(session, 'getId').returns(''); + auth.connection.active = true; + commandInfo = cli.getCommandInfo(command); + commandOptionsSchema = commandInfo.command.getSchemaToParse() as typeof options; + }); + + beforeEach(() => { + log = []; + logger = { + log: async (msg: string) => { + log.push(msg); + }, + logRaw: async (msg: string) => { + log.push(msg); + }, + logToStderr: async (msg: string) => { + log.push(msg); + } + }; + loggerLogSpy = sinon.spy(logger, 'log'); + }); + + afterEach(() => { + sinonUtil.restore([ + request.get + ]); + }); + + after(() => { + sinon.restore(); + auth.connection.active = false; + }); + + it('has correct name', () => { + assert.strictEqual(command.name, commands.AGENT_BLUEPRINTPRINCIPAL_LIST); + }); + + it('has a description', () => { + assert.notStrictEqual(command.description, null); + }); + + it('defines correct properties for the default output', () => { + assert.deepStrictEqual(command.defaultProperties(), ['id', 'appDisplayName', 'appId']); + }); + + it(`should get a list of agent identity blueprints`, async () => { + sinon.stub(request, 'get').callsFake(async (opts) => { + if (opts.url === `https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`) { + return { + value: response + }; + } + + throw 'Invalid request'; + }); + + await command.action(logger, { options: commandOptionsSchema.parse({}) }); + + assert( + loggerLogSpy.calledWith(response) + ); + }); + + it(`should get a list of administrative units with specified properties`, async () => { + sinon.stub(request, 'get').callsFake(async (opts) => { + if (opts.url === `https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal?$select=id,appDisplayName`) { + return { + value: limitedResponse + }; + } + + throw 'Invalid request'; + }); + + await command.action(logger, { options: commandOptionsSchema.parse({ properties: 'id,appDisplayName' }) }); + + assert( + loggerLogSpy.calledWith(limitedResponse) + ); + }); + + it('handles error when retrieving administrative units list failed', async () => { + sinon.stub(request, 'get').callsFake(async (opts) => { + if (opts.url === `https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`) { + throw { error: { message: 'An error has occurred' } }; + } + throw `Invalid request`; + }); + + await assert.rejects( + command.action(logger, { options: commandOptionsSchema.parse({}) }), + new CommandError('An error has occurred') + ); + }); +}); diff --git a/src/m365/entra/commands/agent/agent-blueprintprincipal-list.ts b/src/m365/entra/commands/agent/agent-blueprintprincipal-list.ts new file mode 100644 index 00000000000..b6218608d9e --- /dev/null +++ b/src/m365/entra/commands/agent/agent-blueprintprincipal-list.ts @@ -0,0 +1,61 @@ +import { z } from 'zod'; +import { Logger } from '../../../../cli/Logger.js'; +import { globalOptionsZod } from '../../../../Command.js'; +import { odata } from '../../../../utils/odata.js'; +import GraphCommand from '../../../base/GraphCommand.js'; +import commands from '../../commands.js'; + +export const options = z.strictObject({ + ...globalOptionsZod.shape, + properties: z.string().optional().alias('p') +}); +declare type Options = z.infer; + +interface CommandArgs { + options: Options; +} + +class EntraAgentBlueprintprincipalListCommand extends GraphCommand { + public get name(): string { + return commands.AGENT_BLUEPRINTPRINCIPAL_LIST; + } + + public get description(): string { + return 'Retrieves a list of agent blueprint principals'; + } + + public get schema(): z.ZodType | undefined { + return options; + } + + public defaultProperties(): string[] | undefined { + return ['id', 'appDisplayName', 'appId']; + } + + public async commandAction(logger: Logger, args: CommandArgs): Promise { + const queryParameters: string[] = []; + + if (args.options.properties) { + const allProperties = args.options.properties.split(','); + const selectProperties = allProperties.filter(prop => !prop.includes('/')); + + if (selectProperties.length > 0) { + queryParameters.push(`$select=${selectProperties}`); + } + } + + const queryString = queryParameters.length > 0 + ? `?${queryParameters.join('&')}` + : ''; + + try { + const results = await odata.getAllItems(`${this.resource}/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal${queryString}`); + await logger.log(results); + } + catch (err: any) { + this.handleRejectedODataJsonPromise(err); + } + } +} + +export default new EntraAgentBlueprintprincipalListCommand(); \ No newline at end of file