Skip to content

Commit

Permalink
updating msidentity readme (#1573)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sayedihashimi
sayedihashimi committed May 19, 2021
1 parent d66028d commit 3001196
Showing 1 changed file with 63 additions and 30 deletions.
93 changes: 63 additions & 30 deletions tools/dotnet-msidentity/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,60 @@
# dotnet-msidentity
Command line tool that creates Microsoft identity platform applications in a tenant (AAD or B2C) and updates the configuration code of your ASP.NET Core applications (mvc, webapp, blazorwasm, blazorwasm hosted, blazorserver). The tool can also be used to update code from an existing AAD/AAD B2C application.
# `dotnet msidentity`

## Installing/Uninstalling the tool
Install the prerelease 1.0.0-Preview 1 version of the dotnet-msidentity tool (as a global tool) :
dotnet tool install Microsoft.dotnet-msidentity -g --version "1.0.0-preview.1.21212.1"
Command line tool to update existing ASP.NET Core apps to use the Microsoft identity platform for authentication and authorization. When executed, this tool
will update the application code and create, or update, applications in an Azure AD, or AD B2C, tenant.

## Installing/Uninstalling the latest published version

To install the `dotnet msidentity` tool, we will use the [`dotnet tool`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install) command.
This command will download the specified NuGet package, and then install the tool that is contained in that package. Since the `dotnet msidentity` tool is currently
in preview, you will need to specify the `--version` parameter when calling `dotnet tool install`. To install the latest version of the tool, run the following.

```Shell
dotnet tool install Microsoft.dotnet-msidentity -g --version "1.0.0-preview.2.21253.1"
```

To install a different version of the tool, you can find the available versions at https://www.nuget.org/packages/Microsoft.dotnet-msidentity.

To uninstall the tool execute the following.

```Shell
dotnet tool uninstall -g microsoft.dotnet-msidentity
```

## Installing/Uninstalling the tool from the repo
Use the global_install.cmd global_install.sh command to install the package.
- Edit Version.props to match the version in global_install.

If later you want to uninstall the tool, just run (from anywhere):
To build the `dotnet msidentity` code and install it as a .NET Core global tool. Follow the steps below in a console.

### Windows
1. `cd` to the repo root directory
1. `scripts\install-msidentity.cmd`

### MacOS or Linux
1. `cd` to the repo root directory
1. `scripts/install-msidentity.sh`

If the script successfully completes, the `dotnet msidentity` tool is available as a global tool.

To uninstall the tool (from any directory).

```Shell
dotnet tool uninstall --global Microsoft.dotnet-msidentity
dotnet tool uninstall --global Microsoft.dotnet-msidentity
```

## Pre-requisites to using the tool

Have an AAD or B2C tenant (or both).
- If you want to add an AAD registration, you are usually already signed-in in Visual Studio in a tenant. If needed you can create your own tenant by following this quickstart [Setup a tenant](https://docs.microsoft.com/azure/active-directory/develop/quickstart-create-new-tenant). But be sure to sign-out and sign-in from Visual Studio or Azure CLI so that this tenant is known in the shared token cache.
Have an Azure AD or AD B2C tenant (or both).
- If you want to add an Azure AD registration, you are usually already signed-in in Visual Studio in a tenant. If needed you can create your own tenant by following this quickstart [Setup a tenant](https://docs.microsoft.com/azure/active-directory/develop/quickstart-create-new-tenant). But be sure to sign-out and sign-in from Visual Studio or Azure CLI so that this tenant is known in the shared token cache.

- If you want to add an AAD B2C registration you'll need a B2C tenant, and explicity pass it to the `--tenant-id` option of the tool. As well as the sign-up/sign-in policy `--susi-policy-id`. To create a B2C tenant, see [Create a B2C tenant](https://docs.microsoft.com/azure/active-directory-b2c/tutorial-create-tenant).
- If you want to add an Azure AD B2C registration you'll need a B2C tenant, and explicitly pass it to the `--tenant-id` option of the tool. As well as the sign-up/sign-in policy `--susi-policy-id`. To create a B2C tenant, see [Create a B2C tenant](https://docs.microsoft.com/azure/active-directory-b2c/tutorial-create-tenant).

## Using the tool

To create an ASP.NET Core project that has auth support with the Microsoft identity platform requires two steps on the command line.

1. Create the ASP.NET Core project with `dotnet new` and pass the parameter `--auth` parameter.
2. Update auth for the project with the `dotnet msidentity` tool.

```text
dotnet-msidentity:
Creates or updates an Azure AD / AD B2C app registration, and updates the project, using
Expand All @@ -47,19 +79,19 @@ Commands:
--update-app-registration Update an Azure AD or Azure AD B2C app registration in Azure.
Internal Commands (These commands have little do with registering AAD/AAD B2C apps but are nice helpers):
Internal Commands (These commands have little do with registering Azure AD/Azure AD B2C apps but are nice helpers):
--list--aad-apps Lists AAD Applications for a given tenant + username.
--list--aad-apps Lists Azure AD Applications for a given tenant + username.
--list-service-principals Lists AAD Service Principals for a given tenant + username.
--list-service-principals Lists Azure AD Service Principals for a given tenant + username.
--list-tenants Lists AAD + AAD B2C tenants for a given 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-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.
--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.
Expand All @@ -82,7 +114,7 @@ Options:
--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 AAD.
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
Expand All @@ -102,16 +134,16 @@ If you use PowerShell, or Bash, you can also get the completion in the shell, pr

## Scenarios

### Registering a new Azure AD app and configuring the code using your dev credentials

### Registering a new AAD app and configuring the code using your dev credentials
Given existing code which is not yet configured:

Given existing code which is not yet configured:
- detects the kind of application (web app, web api, blazor server, blazor web assembly, hosted or not)
- detects the IDP (AAD or B2C*)
- creates a new app registration in the tenant, using your developer credentials if possible (and prompting you otherwise). Ensures redirect URIs are registered for all the launchsettings ports.
- detects the kind of application (web app, web api, Blazor server, Blazor web assembly, hosted or not)
- detects the Identity Provider (IdP) (Azure AD or B2C)
- creates a new app registration in the tenant, using your developer credentials if possible (and prompting you otherwise). Ensures redirect URIs are registered for all `applicationUrl`s listed in the `launchSettings.json` file.
- updates the configuration files (and program.cs for Blazor apps)

Note that in the following samples, you can always have your templates adding a calls to Microsoft graph [--calls-graph], or to a downstream API [--called-api-url URI --called-api-scopes scopes]. This is now shown here to keep things simple.
Note that in the following samples, you can always have your templates add a call to Microsoft graph [--calls-graph], or to a downstream API [--called-api-url URI --called-api-scopes scopes]. This is now shown here to keep things simple.

<table>
<tr>
Expand Down Expand Up @@ -151,7 +183,7 @@ dotnet msidentity --register-app --username username@domain.com

### Registering a new AzureAD B2C app and configuring the code using your dev credentials

Note that in the following samples, you can always have your templates adding a calls to a downstream API [--called-api-url URI --called-api-scopes scopes]. This is now shown here to keep things simple.
Note that in the following samples, you can always have your templates add a call to Microsoft graph [--calls-graph], or to a downstream API [--called-api-url URI --called-api-scopes scopes]. This is now shown here to keep things simple.

<table>
<tr>
Expand Down Expand Up @@ -209,13 +241,14 @@ dotnet new webapp --auth SingleOrg --calls-graph
dotnet msidentity --register-app [--tenant-id <tenantId>] --client-id <clientId>
```

### Adding code and configuration to an app which is not authentication/authorization enabled yet

This scenario is on the backlog, but not yet supported
### Updating an existing project which is not configured to use Azure AD or Azure AD B2C

This scenario is not currently supported, but it is planned to be implemented. Currently this tool can only update projects which are already
configured for Azure AD or Azure AD B2C.

## Supported frameworks

The tool supports ASP.NET Core applications created with .NET 5.0 and netcoreapp3.1. In the case of netcoreapp3.1, for blazorwasm applictions, the redirect URI created for the app is a "Web" redirect URI (as Blazor web assembly leverages MSAL.js 1.x in netcoreapp3.1), whereas in net5.0 it's a "SPA" redirect URI (as Blazor web assembly leverages MSAL.js 2.x in net5.0)
The tool supports ASP.NET Core applications created with .NET 5.0 and netcoreapp3.1. In the case of netcoreapp3.1, for blazorwasm applications, the redirect URI created for the app is a "Web" redirect URI (as Blazor web assembly leverages MSAL.js 1.x in netcoreapp3.1), whereas in net5.0 it's a "SPA" redirect URI (as Blazor web assembly leverages MSAL.js 2.x in net5.0)
```Shell
dotnet new blazorwasm --auth SingleOrg --framework netcoreapp3.1
Expand Down

0 comments on commit 3001196

Please sign in to comment.