Introducing Appreg for Azure AD

Introduction

At my organization, we decided to switched from several in-house OAuth and OIDC systems developed over the years to Azure B2C. While this was a great decision, as the overall security of our systems improved, it also meant that we now have a central place to manage applications.

Creating those applications manually might not seem like a big deal when you only have to create a few of them, but it very quickly becomes tedious, boring and so, error-prone. This problem is exacerbated by the fact that the App Registrations blade in the Azure Portal is not very user-friendly, as the lists cannot be reordered, applications don't always show up when searching for them, and it's generally quite slow.

This is why I decided to create appreg, to automate the creation of applications in Azure B2C and help manage them. Note that this tool is not officially supported by Microsoft, and that it is provided as-is, without any warranty.

Also, do note that this provides an opinionated, limited subset of the features available in Azure B2C. For other scenarios, you might want to use the Azure Portal or the Azure CLI instead.

Source code

The source code is available on GitHub. The project is MIT-licensed, which means you are free to use it for personal and commercial use.

Installation

Since this is a .NET Tool, you can install it using the following command:

dotnet tool install --global TerevintoSoftware.AadAppRegistry.Tool

After that, you can invoke the tool from anywhere using the appreg command.

Usage

Note: the latest documentation is always available on GitHub

This tool supports a number of commands to manage App Registrations, which are used both in Azure AD and Azure B2C. The first thing you need to do is to set up the credentials. As of version 1.0.1, only the Client Credentials flow is supported, and can be configured with:

appreg credentials set --tenant-id <tenant-id> --client-id <client-id> --client-secret <client-secret>

The following sections show some examples of how to use the tool.

Listing applications

One of the tasks I've had the most trouble with in the Azure Portal is finding applications, as the ordering in the table doesn't work, and the browser's search feature is not very reliable.

Appreg allows you to list applications with a particular order, which is defaulted to the application's display name. For example, to list apps by creation date, you can use:

appreg list --order-by createdDateTime

This list command will display a table with some basic properties, which currently looks like this:

Note that the Application ID column will output a clickable link to the Azure Portal's page on supported platforms.

Creating applications

Creating applications is the other main part of the problem, as it's very repetitive (hence error-prone). This tool allows you to create applications in an opinionated way, ensuring that APIs/Web/SPAs/Public/Confidential clients are all explicitly separated, as they have different security requirements and are treated differently by Azure.

For example, to create an API application, you can use the following command:

appreg publish api Some.Api.Name --set-default-uri --access-as-user --sign-in-audience AzureADandPersonalMicrosoftAccount

The above command will create an application, set the Application URI (based on AAD or B2C mode), and add the access_as_user scope. The last parameter is used to set the signInAudience property, which is required only for B2C mode, and allows external users to use the API.

If you run that command, you will get back JSON output akin to this:

{
   "Data": {
      "Name": "Some.Api.Name",
      "ClientId": "11111111-1111-1111-1111-111111111111",
      "ObjectId": "22222222-2222-2222-2222-222222222222",
      "Uri": "api://11111111-1111-1111-1111-111111111111",
      "Scope": "api://11111111-1111-1111-1111-111111111111/access_as_user"
   },
   "Status": "Success",
   "Message": null,
   "Success": true
}

Also note that all the publish commands will not do anything by default if an application with the same display name already exists, which is meant to prevent accidental creation of duplicate applications and help with CI/CD scenarios. This can be overridden with the --disable-duplicate-check flag.

Adding scopes to applications

You can add scopes to an application with the add-scope command. Notice though that you need to open the Azure Portal to grant administrator approval for the scope. This might be automated in the future, but I'm weary of adding that support as it requires certain high privilege permissions.

For example, to add the access_as_user scope to an application, you can use the following command:

appreg app add-scope Some.Web.App --api-app-id Some.Api.App --scope-name access_as_user

The name of the application/API application can be either the display name or the client ID. appreg will transform the name to the appropriate ID, as well as transforming the name of the scope to the underlying ID.

Viewing and deleting applications

You can view an application's details with the view command, which will display a JSON representation of the application:

appreg app view Some.Api.Name

Which will output something like this:

{
   "ClientId": "11111111-1111-1111-1111-111111111111",
   "DisplayName": "Some.Api.Name",
   "Uri": "api://11111111-1111-1111-1111-111111111111",
   "Scopes": [
      "api://11111111-1111-1111-1111-111111111111/access_as_user"
   ],
   "RedirectUris": [],
   "Secret": "",
   "ConsumedScopes": null
}

You can also delete an application with the delete command:

appreg app delete Some.Api.Name -y

Closing

I hope you find this tool useful. If you have any feedback, please feel free to open an issue on GitHub.