Microsoft(wbr)dotnet(wbr)-wbrmsidentity 2.0.8

dotnet msidentity

命令行工具，用于将现有的 ASP.NET Core 应用更新为使用 Microsoft 身份验证平台进行身份验证和授权。当执行此工具时，它将更新应用程序代码并在 Azure AD 或 AD B2C 租户中创建或更新应用程序。

安装/卸载最新发布的版本

要安装 dotnet msidentity 工具，我们将使用 dotnet tool 命令。此命令将下载指定的 NuGet 包，然后安装包含在该包中的工具。由于 dotnet msidentity 工具目前处于预览版，因此在调用 dotnet tool install 时您需要指定 --version 参数。要安装最新版本的工具，请运行以下命令。

  dotnet tool install Microsoft.dotnet-msidentity -g --version "1.0.2"

要安装不同版本的工具，您可以在 https://nuget.net.cn/packages/Microsoft.dotnet-msidentity 上找到可用版本。

要卸载工具，请执行以下操作。

  dotnet tool uninstall -g microsoft.dotnet-msidentity

从仓库安装/卸载工具

要在控制台中构建 dotnet msidentity 代码并将其安装为 .NET Core 全局工具，请按照以下步骤操作。

Windows

1. cd 到仓库根目录
2. scripts\install-msidentity.cmd

MacOS 或 Linux

1. cd 到仓库根目录
2. scripts\install-msidentity.sh

如果脚本成功完成，则 dotnet msidentity 工具作为全局工具可用。

要从任何目录中卸载此工具。

  dotnet tool uninstall --global Microsoft.dotnet-msidentity

使用此工具的先决条件

拥有一个Azure AD或AD B2C租户（或两者都拥有）。

• 如果您想添加Azure AD注册，您通常会在这个租户中签入Visual Studio。如果需要，您可以通过以下快速入门创建自己的租户：设置租户。但请务必从Visual Studio或Azure CLI注销并重新登录，这样租户就会被识别在共享令牌缓存中。

• 如果您想添加Azure AD B2C注册，您需要一个B2C租户，并且需要将租户显式传递给工具的--tenant-id选项。以及登录/注册策略--susi-policy-id。有关创建B2C租户的信息，请参阅创建B2C租户。

使用该工具

要使用Microsoft身份平台创建一个具有身份验证支持的ASP.NET Core项目，需要在命令行中进行两个步骤。

1. 使用dotnet new创建ASP.NET Core项目，并传递--auth参数。
2. 使用dotnet msidentity工具更新项目的身份验证。

dotnet-msidentity:
  Creates or updates an Azure AD / AD B2C app registration, and updates the project, using
   your developer credentials (from Visual Studio, Azure CLI, Azure RM PowerShell, VS Code).
   Use this tool in folders containing applications created with the following command:

   dotnet new <template> --auth <authOption> [--calls-graph] [--called-api-url <URI> --called-api-scopes <scopes>]

   where the <template> is a webapp, mvc, webapi, blazorserver, blazorwasm.
   See https://aka.ms/dotnet-msidentity.

Usage:
  dotnet msidentity [command] [options]

Commands:
  --register-app               Registers or updates an Azure AD or Azure AD B2C App registration in Azure.
                                        - Updates the appsettings.json file.
                                        - Updates local user secrets
                                        - Updates Startup.cs and package references if needed.

  --unregister-app             Unregister an Azure AD or Azure AD B2C Application in Azure.
  
  --update-app-registration    Update an Azure AD or Azure AD B2C app registration in Azure.

Internal Commands (These commands have little do with registering Azure AD/Azure AD B2C apps but are nice helpers):
  
  --list--aad-apps                     Lists Azure AD Applications for a given tenant + username.
  
  --list-service-principals            Lists Azure AD Service Principals for a given tenant + username.
  
  --list-tenants                       Lists Azure AD + Azure AD B2C tenants for a given username.
  
  --update-project                     Given client id for an Azure AD/AD B2C app, update appsettings.json, local user secrets. [TODO : and project code(Startup.cs, project references to get the app auth ready).]
  
  --create-client-secret               Create a client secret for given app registration (client id) and print the secret.
  
  --create-app-registration            Create an Azure AD or Azure AD B2C app registration in Azure.    

Options:
  --tenant-id <tenant-id>              Azure AD or Azure AD B2C tenant in which to create/update the app.
                                        - If specified, the tool will create the application in the specified tenant.
                                        - Otherwise it will create the app in your home tenant.
  
  --username <username>                Username to use to connect to the Azure AD or Azure AD B2C tenant.
                                        It's only needed when you are signed-in in Visual Studio, or Azure CLI with
                                        several identities. In that case, the username param is used to disambiguate
                                        which identity to use to create the app in the tenant.
  
  --client-id <client-id>              Client ID of an existing application from which to update the code. This is
                                        used when you don't want to register a new app, but want to configure the code
                                        from an existing application (which can also be updated by the tool if needed).
                                        You might want to also pass-in the if you know it.
  
  -p, --project-file-path              Path to the project file (.csproj file) to be used. 
   <project-file-path>                  If not provided, the project file in the current working directory will be used.
  
  --client-secret <client-secret>      Client secret to use as a client credential.
  
  --susi-policy-id <susi-policy-id>    Sign-up/Sign-in policy required for configurating
                                        a B2C application from code that was created for Azure AD.
  
  --api-client-id <api-client-id>      Client ID of the blazorwasm hosted web API.
                                        This is only used on the case of a blazorwasm hosted application where you only
                                        want to configure the code (named after the --api-client-id blazorwasm
                                        template parameter).
  
  --app-id-uri <app-id-uri>            The App ID Uri for the blazorwasm hosted API. It's only used
                                        on the case of a blazorwasm hosted application (named after the --app-id-uri
                                        blazorwasm template parameter).
  
  --version                            Display the version of this tool.
  
  -?, -h, --help                       Show commandline help.

如果您使用PowerShell或Bash，您也可以在shell中获得完成，但前提是您已安装dotnet-suggest。有关如何配置shell以便利用dotnet-suggest的说明，请参阅https://github.com/dotnet/command-line-api/blob/main/docs/dotnet-suggest.md。

场景

注册新的Azure AD应用并使用您的开发凭据配置代码

给定尚未配置的现有代码

• 检测应用的类型（Web应用、Web API、Blazor服务器、Blazor Web Assembly、托管或非托管）
• 检测 Identity Provider (IdP)（Azure AD或B2C）
• 在租户中创建新的应用注册，如果可能的话使用您开发者的凭据（否则则提示您）。确保已为所有在launchSettings.json文件中列出的applicationUrl注册了重定向URI。
• 更新配置文件（以及Blazor应用的program.cs）

注意，在以下示例中，您始终可以在模板中添加对Microsoft Graph的调用 [--calls-graph]，或对下游API的调用 [--called-api-url URI --called-api-scopes scopes]。这里现在展示这只是为了保持简单。

• 在您的本地租户中创建新的应用并更新代码

dotnet new webapp --auth SingleOrg
dotnet msidentity --register-application

• 在不同的租户中创建新的应用并更新代码

dotnet new webapp --auth SingleOrg
dotnet msidentity --register-app --tenant-id testprovisionningtool.onmicrosoft.com

• 使用不同的身份创建新的应用并更新代码

dotnet new webapp --auth SingleOrg
dotnet msidentity --register-app --username username@domain.com

注册新的Azure AD B2C应用并使用您的开发凭据配置代码

注意，在以下示例中，您始终可以在模板中添加对Microsoft Graph的调用 [--calls-graph]，或对下游API的调用 [--called-api-url URI --called-api-scopes scopes]。这里现在展示这只是为了保持简单。

• 创建新的Azure AD B2C应用并更新最初为Azure AD设计的代码

dotnet new webapp --auth SingleOrg
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com --susi-policy-id b2c_1_susi

• 创建新的Azure AD B2C应用并更新代码

dotnet new webapp --auth IndividualB2C
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com

• 使用不同的身份创建新的Azure AD B2C应用并更新代码

dotnet new webapp --auth IndividualB2C
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com  --username username@domain.com

从现有应用配置代码

以下使用现有应用配置代码。

dotnet new webapp --auth SingleOrg

dotnet msidentity --register-app [--tenant-id <tenantId>] --client-id <clientId>

对于调用Microsoft Graph的应用同样是这么做的。

dotnet new webapp --auth SingleOrg --calls-graph

dotnet msidentity --register-app [--tenant-id <tenantId>] --client-id <clientId>

更新尚未配置为使用Azure AD或Azure AD B2C的现有项目

此场景目前不支持，但计划实现。目前此工具只能更新已配置为Azure AD或Azure AD B2C的项目。

支持的框架

该工具支持使用.NET 5.0和netcoreapp3.1创建的ASP.NET Core应用程序。在netcoreapp3.1的情况下，对于blazorwasm应用程序，为应用程序创建的重定向URI是一个“Web”重定向URI（因为Blazor Web Assembly在netcoreapp3.1中使用了MSAL.js 1.x），而在net5.0中则是一个“SPA”重定向URI（因为Blazor Web Assembly在net5.0中使用了MSAL.js 2.x）。

dotnet new blazorwasm --auth SingleOrg --framework netcoreapp3.1
dotnet msidentity
dotnet run --framework netstandard2.1