Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[dotnet-msidentity] help, README, and version update #1569

Merged
merged 2 commits into from
May 11, 2021
Merged

[dotnet-msidentity] help, README, and version update #1569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
238c825
help, README, and version update
deepchoudhery May 10, 2021
d35b1f3
PR fixes 1
deepchoudhery May 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 45 additions & 21 deletions src/MSIdentityScaffolding/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# 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.

## Installing/Uninstalling the tool
## 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"

## 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):
```Shell
dotnet tool uninstall --global dotnet-msidentity
dotnet tool uninstall --global Microsoft.dotnet-msidentity
```

## Pre-requisites to using the tool
Expand All @@ -21,7 +25,7 @@ Have an AAD or B2C tenant (or both).

```text
dotnet-msidentity:
deepchoudhery marked this conversation as resolved.
Show resolved Hide resolved
Creates or updates an Azure AD / Azure AD B2C application, and updates the code, using
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:

Expand All @@ -31,47 +35,67 @@ dotnet-msidentity:
See https://aka.ms/dotnet-msidentity.

Usage:
dotnet-msidentity [command] [options]
dotnet msidentity [command] [options]

Commands:
--register-app Registers/updates an AAD/AAD B2C Application in Azure.
--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
--unregister-app Unregister an AAD/AAD B2C Application in Azure.
- 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 AAD/AAD B2C apps but are nice helpers):

--list--aad-apps Lists AAD Applications for a given tenant + username.

--list-service-principals Lists AAD Service Principals for a given tenant + username.

--list-tenants Lists AAD + AAD 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.
--folder <folder> When specified, will analyze the application code in the specified folder.
Otherwise analyzes the code in the current directory.

-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 AAD.

--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).
--unregister Unregister the application, instead of registering it.
--version Show version information
-?, -h, --help Show help and usage information

--version Display the version of this tool.

-?, -h, --help Show commandline help.
```

If you use PowerShell, or Bash, you can also get the completion in the shell, provivided you install [dotnet-suggest](https://www.nuget.org/packages/dotnet-suggest/). See https://github.com/dotnet/command-line-api/blob/main/docs/dotnet-suggest.md on how to configure the shell so that it leverages dotnet-suggest.
Expand All @@ -95,7 +119,7 @@ Note that in the following samples, you can always have your templates adding a
<code>
dotnet new webapp --auth SingleOrg

dotnet-msidentity --register-application
dotnet msidentity --register-application
</code>
</td>
<td>Creates a new app <b>in your home tenant</b> and updates code</td>
Expand All @@ -106,7 +130,7 @@ dotnet-msidentity --register-application
<code>
dotnet new webapp --auth SingleOrg

dotnet-msidentity --register-application --tenant-id testprovisionningtool.onmicrosoft.com
dotnet msidentity --register-app --tenant-id testprovisionningtool.onmicrosoft.com
</code>
</td>
<td>Creates a new app <b>in a different tenant</b> and updates code</td>
Expand All @@ -117,7 +141,7 @@ dotnet-msidentity --register-application --tenant-id testprovisionningtool.onmic
<code>
dotnet new webapp --auth SingleOrg

dotnet-msidentity --register-application --username username@domain.com
dotnet msidentity --register-app --username username@domain.com
</code>
</td>
<td>Creates a new app <b>using a different identity</b> and updates code</td>
Expand All @@ -135,7 +159,7 @@ Note that in the following samples, you can always have your templates adding a
<code>
dotnet new webapp --auth SingleOrg

dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com --susi-policy-id b2c_1_susi
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com --susi-policy-id b2c_1_susi
</code>
</td>
<td>Creates a new Azure AD B2C app and updates code which was initially meant
Expand All @@ -147,7 +171,7 @@ dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com
<code>
dotnet new webapp --auth IndividualB2C

dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com
</code>
</td>
<td>Creates a new Azure AD B2C app and updates code</td>
Expand All @@ -158,7 +182,7 @@ dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com
<code>
dotnet new webapp --auth IndividualB2C

dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com --username username@domain.com
dotnet msidentity --register-app --tenant-id fabrikamb2c.onmicrosoft.com --username username@domain.com
</code>
</td>
<td>Creates a new app Azure AD B2C app <b>using a different identity</b> and updates code</td>
Expand All @@ -174,15 +198,15 @@ dotnet-msidentity --register-application --tenant-id fabrikamb2c.onmicrosoft.com
```Shell
dotnet new webapp --auth SingleOrg

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

Same thing for an application calling Microsoft Graph

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

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

### Adding code and configuration to an app which is not authentication/authorization enabled yet
Expand All @@ -195,6 +219,6 @@ The tool supports ASP.NET Core applications created with .NET 5.0 and netcoreapp

```Shell
dotnet new blazorwasm --auth SingleOrg --framework netcoreapp3.1
dotnet-msidentity
dotnet run -f netstandard2.1
dotnet msidentity
dotnet run --framework netstandard2.1
```
Loading