From 6918d9846064776481ce9ae3f1e71f2de776b62f Mon Sep 17 00:00:00 2001 From: Mathijs Verbeeck Date: Thu, 14 Mar 2024 13:48:43 +0100 Subject: [PATCH] Renames environment variables to 'entra'. Closes #5917 --- docs/docs/cmd/login.mdx | 4 ++-- docs/docs/concepts/authorization-tokens.mdx | 2 +- docs/docs/user-guide/cli-certificate-caveats.mdx | 2 +- docs/docs/user-guide/connecting-microsoft-365.mdx | 4 ++-- .../user-guide/run-cli-in-docker-container.mdx | 4 ++-- docs/docs/user-guide/using-own-identity.mdx | 12 ++++++------ src/Auth.ts | 4 ++-- src/config.spec.ts | 14 +++++++++++--- src/config.ts | 4 ++-- src/m365/cli/commands/cli-consent.spec.ts | 6 +++--- src/m365/cli/commands/cli-consent.ts | 2 +- src/m365/cli/commands/cli-reconsent.ts | 2 +- src/m365/commands/login.ts | 2 +- 13 files changed, 35 insertions(+), 27 deletions(-) diff --git a/docs/docs/cmd/login.mdx b/docs/docs/cmd/login.mdx index b533a40a8c0..a65c3dd0848 100644 --- a/docs/docs/cmd/login.mdx +++ b/docs/docs/cmd/login.mdx @@ -37,7 +37,7 @@ m365 login [options] : Client Secret of the Microsoft Entra application to use for authentication. Required when `authType` is set to `secret`. `--appId [appId]` -: App ID of the Microsoft Entra application to use for authentication. If not specified, use the app specified in the `CLIMICROSOFT365_AADAPPID` environment variable. If the environment variable is not defined, use the multitenant PnP Management Shell app +: App ID of the Microsoft Entra application to use for authentication. If not specified, use the app specified in the `CLIMICROSOFT365_ENTRAAPPID` environment variable. If the environment variable is not defined, use the multitenant PnP Management Shell app `--tenant [tenant]` : ID of the tenant from which accounts should be able to authenticate. Use `common` or `organization` if the app is multitenant. If not specified, use the tenant specified in the `CLIMICROSOFT365_TENANT` environment variable. If the environment variable is not defined, use `common` as the tenant identifier @@ -61,7 +61,7 @@ When logging in to Microsoft 365 using the user name and password, next to the a When logging in to Microsoft 365 using a certificate, the CLI for Microsoft 365 will store the contents of the certificate so that it can automatically re-authenticate if necessary. The contents of the certificate are removed by re-authenticating using the device code or by calling the [logout](logout.mdx) command. -To log in to Microsoft 365 using a certificate or secret, you will typically [create a custom Microsoft Entra application](../user-guide/using-own-identity.mdx). To use this application with the CLI for Microsoft 365, you will set the `CLIMICROSOFT365_AADAPPID` environment variable to the application's ID and the `CLIMICROSOFT365_TENANT` environment variable to the ID of the Microsoft Entra tenant, where you created the Microsoft Entra application. Also, please make sure to read about [the caveats when using the certificate login option](../user-guide/cli-certificate-caveats.mdx). +To log in to Microsoft 365 using a certificate or secret, you will typically [create a custom Microsoft Entra application](../user-guide/using-own-identity.mdx). To use this application with the CLI for Microsoft 365, you will set the `CLIMICROSOFT365_ENTRAAPPID` environment variable to the application's ID and the `CLIMICROSOFT365_TENANT` environment variable to the ID of the Microsoft Entra tenant, where you created the Microsoft Entra application. Also, please make sure to read about [the caveats when using the certificate login option](../user-guide/cli-certificate-caveats.mdx). Managed identity in Azure Cloud Shell is the identity of the user. It is neither system- nor user-assigned and it can't be configured. To log in to Microsoft 365 using managed identity in Azure Cloud Shell, set `authType` to `identity` and don't specify the `userName` option. diff --git a/docs/docs/concepts/authorization-tokens.mdx b/docs/docs/concepts/authorization-tokens.mdx index 06930af7d03..96b42c1b8d0 100644 --- a/docs/docs/concepts/authorization-tokens.mdx +++ b/docs/docs/concepts/authorization-tokens.mdx @@ -24,7 +24,7 @@ When you decide to use your own Microsoft Entra application, you need to choose ::: -When specifying a custom Microsoft Entra application to be used by the CLI for Microsoft 365, set the `CLIMICROSOFT365_AADAPPID` environment variable to the ID of your Microsoft Entra application. +When specifying a custom Microsoft Entra application to be used by the CLI for Microsoft 365, set the `CLIMICROSOFT365_ENTRAAPPID` environment variable to the ID of your Microsoft Entra application. CLI for Microsoft 365 requires the following permissions to Microsoft 365 services: diff --git a/docs/docs/user-guide/cli-certificate-caveats.mdx b/docs/docs/user-guide/cli-certificate-caveats.mdx index eb37abd7758..a2bf2e69368 100644 --- a/docs/docs/user-guide/cli-certificate-caveats.mdx +++ b/docs/docs/user-guide/cli-certificate-caveats.mdx @@ -7,7 +7,7 @@ sidebar_position: 11 ## I get error "AADSTS700027 Client assertion contains an invalid signature" when I login the CLI with certificate, what am I doing wrong -There is an article ["Using your own Microsoft Entra identity"](./using-own-identity.mdx) dedicated to using the CLI with your own identity, and you should have a look at it and see if it can help you. Many of the cases we've seen in the Github issues list are that people forget to set the `CLIMICROSOFT365_AADAPPID` or `CLIMICROSOFT365_TENANT` environment variables. Setting these variables could be as easy as adding them before your command on the bash command line like `CLIMICROSOFT365_AADAPPID=value1 CLIMICROSOFT365_TENANT=value2 m365 command` (see [#1532](https://github.com/pnp/cli-microsoft365/issues/1532) or [#1496](https://github.com/pnp/cli-microsoft365/issues/1496#issuecomment-625549739)). If you are Windows user the syntax should be like `set CLIMICROSOFT365_AADAPPID=value1` and `set CLIMICROSOFT365_TENANT=value2` then your cli command ([#1121](https://github.com/pnp/cli-microsoft365/issues/1121#issuecomment-533609882)). +There is an article ["Using your own Microsoft Entra identity"](./using-own-identity.mdx) dedicated to using the CLI with your own identity, and you should have a look at it and see if it can help you. Many of the cases we've seen in the GitHub issues list are that people forget to set the `CLIMICROSOFT365_ENTRAAPPID` or `CLIMICROSOFT365_TENANT` environment variables. Setting these variables could be as easy as adding them before your command on the bash command line like `CLIMICROSOFT365_ENTRAAPPID=value1 CLIMICROSOFT365_TENANT=value2 m365 command` (see [#1532](https://github.com/pnp/cli-microsoft365/issues/1532) or [#1496](https://github.com/pnp/cli-microsoft365/issues/1496#issuecomment-625549739)). If you are Windows user the syntax should be like `set CLIMICROSOFT365_ENTRAAPPID=value1` and `set CLIMICROSOFT365_TENANT=value2` then your cli command ([#1121](https://github.com/pnp/cli-microsoft365/issues/1121#issuecomment-533609882)). ## I get "Error: AADSTS700025: Client is public so 'client_assertion' should not be presented" diff --git a/docs/docs/user-guide/connecting-microsoft-365.mdx b/docs/docs/user-guide/connecting-microsoft-365.mdx index 6c03c63e16b..a49d0450550 100644 --- a/docs/docs/user-guide/connecting-microsoft-365.mdx +++ b/docs/docs/user-guide/connecting-microsoft-365.mdx @@ -54,7 +54,7 @@ Generally, you should use the default device code flow. If you need to use a non #### Log in using a certificate -Another way to log in to Microsoft 365 in the CLI for Microsoft 365 is by using a certificate. To use this authentication method, set the `CLIMICROSOFT365_AADAPPID` environment variable to the ID of the Microsoft Entra application that you want to use to authenticate the CLI for Microsoft 365 and the `CLIMICROSOFT365_TENANT` environment variable to the ID of your Microsoft Entra ID directory. When calling the login command, set the `authType` option to `certificate` and specify the path to the certificate private key using the `certificateFile` option. Optionally, you can specify the certificate's thumbprint using the `thumbprint` option. If not specified, CLI will automatically calculate it from the specified certificate. +Another way to log in to Microsoft 365 in the CLI for Microsoft 365 is by using a certificate. To use this authentication method, set the `CLIMICROSOFT365_ENTRAAPPID` environment variable to the ID of the Microsoft Entra application that you want to use to authenticate the CLI for Microsoft 365 and the `CLIMICROSOFT365_TENANT` environment variable to the ID of your Microsoft Entra ID directory. When calling the login command, set the `authType` option to `certificate` and specify the path to the certificate private key using the `certificateFile` option. Optionally, you can specify the certificate's thumbprint using the `thumbprint` option. If not specified, CLI will automatically calculate it from the specified certificate. To log in to Microsoft 365 using a Personal Information Exchange (.pfx) file, execute: @@ -118,7 +118,7 @@ At this point the `privateKeyWithPassphrase.pem` file can be used to log in the #### Log in using a secret -CLI for Microsoft 365 also supports login using a secret. To use this authentication method, set the `CLIMICROSOFT365_AADAPPID` environment variable to the ID of the Microsoft Entra application that you want to use to authenticate the CLI for Microsoft 365 and the `CLIMICROSOFT365_TENANT` environment variable to the ID of your Microsoft Entra ID directory. When calling the login command, set the `authType` option to `secret` and specify the client secret value. +CLI for Microsoft 365 also supports login using a secret. To use this authentication method, set the `CLIMICROSOFT365_ENTRAAPPID` environment variable to the ID of the Microsoft Entra application that you want to use to authenticate the CLI for Microsoft 365 and the `CLIMICROSOFT365_TENANT` environment variable to the ID of your Microsoft Entra ID directory. When calling the login command, set the `authType` option to `secret` and specify the client secret value. To log in to Microsoft 365 using a secret, execute: diff --git a/docs/docs/user-guide/run-cli-in-docker-container.mdx b/docs/docs/user-guide/run-cli-in-docker-container.mdx index d79440a6e77..b22039dddef 100644 --- a/docs/docs/user-guide/run-cli-in-docker-container.mdx +++ b/docs/docs/user-guide/run-cli-in-docker-container.mdx @@ -101,7 +101,7 @@ We have created a non-root user called `cli-microsoft365` inside the container. In scenarios where you need to set environment variables, for example, you want to use a custom Microsoft Entra identity identity when logging into your Microsoft 365 tenant using the CLI. You can set these variables by passing them in as options arguments `(-e)` into the `docker run` command. ```sh -docker run --rm -it -e "CLIMICROSOFT365_AADAPPID=51078274-0353-4f6a-b9f5-8674ab2e524c" -e "CLIMICROSOFT365_TENANT=9455bc83-d5af-4ccf-93f6-0af3f71aaf8e" m365pnp/cli-microsoft365:latest +docker run --rm -it -e "CLIMICROSOFT365_ENTRAAPPID=51078274-0353-4f6a-b9f5-8674ab2e524c" -e "CLIMICROSOFT365_TENANT=9455bc83-d5af-4ccf-93f6-0af3f71aaf8e" m365pnp/cli-microsoft365:latest ``` ## Combining script and environment variables @@ -109,7 +109,7 @@ docker run --rm -it -e "CLIMICROSOFT365_AADAPPID=51078274-0353-4f6a-b9f5-8674ab2 Combining scripts and environment variables is a powerful way to run the CLI in Docker, we can set environment variables which we can reference in the script that is executed in the running container and also. ```sh -docker run --rm -it -v ${PWD}:/home/cli-microsoft365/scripts -e "CLIMICROSOFT365_AADAPPID=da049853-dd90-49df-aa21-4e0c8b646a36" -e "CLIMICROSOFT365_TENANT=e8954f17-a373-4b61-b54d-45c038fe3188" -e "M365_USER=user@contoso.com" -e "M365_PASSWORD=password" m365pnp/cli-microsoft365:next pwsh scripts/script.ps1 +docker run --rm -it -v ${PWD}:/home/cli-microsoft365/scripts -e "CLIMICROSOFT365_ENTRAAPPID=da049853-dd90-49df-aa21-4e0c8b646a36" -e "CLIMICROSOFT365_TENANT=e8954f17-a373-4b61-b54d-45c038fe3188" -e "M365_USER=user@contoso.com" -e "M365_PASSWORD=password" m365pnp/cli-microsoft365:next pwsh scripts/script.ps1 ``` We can reference the environment variables passed in to the `docker run` command and use them in the script, in this example, passing the username and password variables into the `m365 login` command to login in to Microsoft 365 using password authentication. diff --git a/docs/docs/user-guide/using-own-identity.mdx b/docs/docs/user-guide/using-own-identity.mdx index 1cf3c4416c8..a1afbba72ed 100644 --- a/docs/docs/user-guide/using-own-identity.mdx +++ b/docs/docs/user-guide/using-own-identity.mdx @@ -107,27 +107,27 @@ This completes the configuration required in the Azure portal. We can now move o To configure the CLI for Microsoft 365 to use our newly created custom application, we need to tell it the Client ID of our custom application and the Tenant ID of where the custom application has been created. -To do that, we need to create two environment variables, named `CLIMICROSOFT365_AADAPPID` and `CLIMICROSOFT365_TENANT`, giving them the values that you saved earlier. +To do that, we need to create two environment variables, named `CLIMICROSOFT365_ENTRAAPPID` and `CLIMICROSOFT365_TENANT`, giving them the values that you saved earlier. How you set the environment variables depends on the operating system and shell that you are using. If you are on Windows, you can set the environment variables using the `$env:` approach in a PowerShell session. ```powershell -$env:CLIMICROSOFT365_AADAPPID="506af689-32aa-46c8-afb5-972ebf9d218a" +$env:CLIMICROSOFT365_ENTRAAPPID="506af689-32aa-46c8-afb5-972ebf9d218a" $env:CLIMICROSOFT365_TENANT="e8954f17-a373-4b61-b54d-45c038fe3188" ``` :::tip -Execute `$env:CLIMICROSOFT365_AADAPPID` and `$env:CLIMICROSOFT365_TENANT` to verify that the environment variables have been created correctly +Execute `$env:CLIMICROSOFT365_ENTRAAPPID` and `$env:CLIMICROSOFT365_TENANT` to verify that the environment variables have been created correctly ::: If you are using Linux or macOS, you can set the environment variables using the `export` command from your terminal prompt. ```sh -export CLIMICROSOFT365_AADAPPID=506af689-32aa-46c8-afb5-972ebf9d218a +export CLIMICROSOFT365_ENTRAAPPID=506af689-32aa-46c8-afb5-972ebf9d218a export CLIMICROSOFT365_TENANT=e8954f17-a373-4b61-b54d-45c038fe3188 ``` @@ -167,9 +167,9 @@ How you permanently set the environment variable is dependant on the operating s If you are on Windows, you can set the environment variables using the `Edit the system environment variables` approach in the Windows UI. -Search for `Edit the system environment variables` in Start Menu and launch it. Select `Environment Variables`, under the `User variables for ` section, select `New...` to add a new variable. In the dialog, in the variable name field enter `CLIMICROSOFT365_AADAPPID` and set the value using the Client ID (quotes should be omitted). Select `OK` to save the value and repeat the process for the `CLIMICROSOFT365_TENANT` variable. Select `OK` until all windows are closed to persist the changes. +Search for `Edit the system environment variables` in Start Menu and launch it. Select `Environment Variables`, under the `User variables for ` section, select `New...` to add a new variable. In the dialog, in the variable name field enter `CLIMICROSOFT365_ENTRAAPPID` and set the value using the Client ID (quotes should be omitted). Select `OK` to save the value and repeat the process for the `CLIMICROSOFT365_TENANT` variable. Select `OK` until all windows are closed to persist the changes. -Open a new PowerShell session and execute `$env:CLIMICROSOFT365_AADAPPID` and `$env:CLIMICROSOFT365_TENANT` to verify that the environment variables have been created correctly. +Open a new PowerShell session and execute `$env:CLIMICROSOFT365_ENTRAAPPID` and `$env:CLIMICROSOFT365_TENANT` to verify that the environment variables have been created correctly. If you are on Linux or MacOS, depending on your terminal, add the `export` lines to `.bashrc` or `.zshrc` file in your home directory. diff --git a/src/Auth.ts b/src/Auth.ts index 9a120f86450..ff314c44af3 100644 --- a/src/Auth.ts +++ b/src/Auth.ts @@ -76,7 +76,7 @@ export class Connection { constructor() { this.accessTokens = {}; - this.appId = config.cliAadAppId; + this.appId = config.cliEntraAppId; this.tenant = config.tenant; this.cloudType = CloudType.Public; } @@ -97,7 +97,7 @@ export class Connection { this.thumbprint = undefined; this.spoUrl = undefined; this.spoTenantId = undefined; - this.appId = config.cliAadAppId; + this.appId = config.cliEntraAppId; this.tenant = config.tenant; } } diff --git a/src/config.spec.ts b/src/config.spec.ts index 8b38f1bd454..db8a8d3f231 100644 --- a/src/config.spec.ts +++ b/src/config.spec.ts @@ -12,7 +12,14 @@ describe('Config', () => { process.env.CLIMICROSOFT365_AADAPPID = 'appId123'; const config = await import(`./config.js#${Math.random()}`); - assert.strictEqual(config.default.cliAadAppId, 'appId123'); + assert.strictEqual(config.default.cliEntraAppId, 'appId123'); + }); + + it('returns process.env CLIMICROSOFT365_ENTRAAPPID value', async () => { + process.env.CLIMICROSOFT365_ENTRAAPPID = 'appId123'; + + const config = await import(`./config.js#${Math.random()}`); + assert.strictEqual(config.default.cliEntraAppId, 'appId123'); }); it('returns default value since env CLIMICROSOFT365_TENANT not present', async () => { @@ -22,10 +29,11 @@ describe('Config', () => { assert.strictEqual(config.default.tenant, 'common'); }); - it('returns default value since env CLIMICROSOFT365_AADAPPID not present', async () => { + it('returns default value since env CLIMICROSOFT365_AADAPPID or CLIMICROSOFT365_ENTRAAPPID not present', async () => { delete process.env.CLIMICROSOFT365_AADAPPID; + delete process.env.CLIMICROSOFT365_ENTRAAPPID; const config = await import(`./config.js#${Math.random()}`); - assert.strictEqual(config.default.cliAadAppId, '31359c7f-bd7e-475c-86db-fdb8c937548e'); + assert.strictEqual(config.default.cliEntraAppId, '31359c7f-bd7e-475c-86db-fdb8c937548e'); }); }); \ No newline at end of file diff --git a/src/config.ts b/src/config.ts index 85b19616bf3..bd0c50f4ffc 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1,11 +1,11 @@ import { app } from "./utils/app.js"; -const cliAadAppId: string = '31359c7f-bd7e-475c-86db-fdb8c937548e'; +const cliEntraAppId: string = '31359c7f-bd7e-475c-86db-fdb8c937548e'; export default { applicationName: `CLI for Microsoft 365 v${app.packageJson().version}`, delimiter: 'm365\$', - cliAadAppId: process.env.CLIMICROSOFT365_AADAPPID || cliAadAppId, + cliEntraAppId: process.env.CLIMICROSOFT365_ENTRAAPPID || process.env.CLIMICROSOFT365_AADAPPID || cliEntraAppId, tenant: process.env.CLIMICROSOFT365_TENANT || 'common', configstoreName: 'cli-m365-config' }; \ No newline at end of file diff --git a/src/m365/cli/commands/cli-consent.spec.ts b/src/m365/cli/commands/cli-consent.spec.ts index 6444bd188dc..edbf11b5271 100644 --- a/src/m365/cli/commands/cli-consent.spec.ts +++ b/src/m365/cli/commands/cli-consent.spec.ts @@ -23,7 +23,7 @@ describe(commands.CONSENT, () => { sinon.stub(pid, 'getProcessName').callsFake(() => ''); sinon.stub(session, 'getId').callsFake(() => ''); originalTenant = config.tenant; - originalAadAppId = config.cliAadAppId; + originalAadAppId = config.cliEntraAppId; commandInfo = cli.getCommandInfo(command); }); @@ -45,7 +45,7 @@ describe(commands.CONSENT, () => { afterEach(() => { config.tenant = originalTenant; - config.cliAadAppId = originalAadAppId; + config.cliEntraAppId = originalAadAppId; }); after(() => { @@ -72,7 +72,7 @@ describe(commands.CONSENT, () => { it('shows consent URL for VivaEngage permissions for a custom single-tenant app', async () => { config.tenant = 'fb5cb38f-ecdb-4c6a-a93b-b8cfd56b4a89'; - config.cliAadAppId = '2587b55d-a41e-436d-bb1d-6223eb185dd4'; + config.cliEntraAppId = '2587b55d-a41e-436d-bb1d-6223eb185dd4'; await command.action(logger, { options: { service: 'VivaEngage' } }); assert(loggerLogSpy.calledWith(`To consent permissions for executing VivaEngage commands, navigate in your web browser to https://login.microsoftonline.com/fb5cb38f-ecdb-4c6a-a93b-b8cfd56b4a89/oauth2/v2.0/authorize?client_id=2587b55d-a41e-436d-bb1d-6223eb185dd4&response_type=code&scope=https%3A%2F%2Fapi.yammer.com%2Fuser_impersonation`)); }); diff --git a/src/m365/cli/commands/cli-consent.ts b/src/m365/cli/commands/cli-consent.ts index 65b7d0baa7a..d31634290a6 100644 --- a/src/m365/cli/commands/cli-consent.ts +++ b/src/m365/cli/commands/cli-consent.ts @@ -68,7 +68,7 @@ class CliConsentCommand extends AnonymousCommand { break; } - await logger.log(`To consent permissions for executing ${args.options.service} commands, navigate in your web browser to https://login.microsoftonline.com/${config.tenant}/oauth2/v2.0/authorize?client_id=${config.cliAadAppId}&response_type=code&scope=${encodeURIComponent(scope)}`); + await logger.log(`To consent permissions for executing ${args.options.service} commands, navigate in your web browser to https://login.microsoftonline.com/${config.tenant}/oauth2/v2.0/authorize?client_id=${config.cliEntraAppId}&response_type=code&scope=${encodeURIComponent(scope)}`); } public async action(logger: Logger, args: CommandArgs): Promise { diff --git a/src/m365/cli/commands/cli-reconsent.ts b/src/m365/cli/commands/cli-reconsent.ts index 046b7d9f28d..4130c49b772 100644 --- a/src/m365/cli/commands/cli-reconsent.ts +++ b/src/m365/cli/commands/cli-reconsent.ts @@ -17,7 +17,7 @@ class CliReconsentCommand extends AnonymousCommand { } public async commandAction(logger: Logger): Promise { - const url = `https://login.microsoftonline.com/${config.tenant}/oauth2/authorize?client_id=${config.cliAadAppId}&response_type=code&prompt=admin_consent`; + const url = `https://login.microsoftonline.com/${config.tenant}/oauth2/authorize?client_id=${config.cliEntraAppId}&response_type=code&prompt=admin_consent`; if (cli.getSettingWithDefaultValue(settingsNames.autoOpenLinksInBrowser, false) === false) { await logger.log(`To re-consent the PnP Microsoft 365 Management Shell Microsoft Entra application navigate in your web browser to ${url}`); diff --git a/src/m365/commands/login.ts b/src/m365/commands/login.ts index 843cce3341a..06ca3ccfaf0 100644 --- a/src/m365/commands/login.ts +++ b/src/m365/commands/login.ts @@ -163,7 +163,7 @@ class LoginCommand extends Command { } const authType = args.options.authType || cli.getSettingWithDefaultValue(settingsNames.authType, 'deviceCode'); - auth.connection.appId = args.options.appId || config.cliAadAppId; + auth.connection.appId = args.options.appId || config.cliEntraAppId; auth.connection.tenant = args.options.tenant || config.tenant; auth.connection.name = args.options.connectionName;