CreateAzureADB2CAppRegistrations.md

Registering the apps with Microsoft identity platform and updating the configuration files using PowerShell scripts

Overview

⚠️ We recommend that you run the scripts using option 6, however if your tenant has MFA enabled it is not possible to supply credentials directly, as such use option 5.

The script will regitered two applications in the Azure AD B2C tenant. The first is for the Web API Service application, and the second is for the mobile client. This allows these applications to authenticate and validate users against the Azure AD B2C tenant, using the registered user flows and returning the assigned user attributes.

Quick summary

1. On Windows run PowerShell and navigate to the root of the cloned directory
2. In PowerShell run:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

3. Run the script to create your Azure AD application and configure the code of the sample application accordingly. (Other ways of running the scripts are described below)

   cd .\AppCreationScripts\ 
   .\Configure.ps1

Prerequisites

• You must have an existing Azure subscription, before you begin.
• You must have the TenantId for the Azure AD B2C tenant you created in Create an Azure Active Directory B2C Tenant
• You must have a valid AD origanisation username and password with rights to manage the Azure Ad B2C tenant.

More details

• Present the scripts and explain their usage patterns for test and DevOps scenarios.
• Explain the pre-requisites
• Explain six ways of running the scripts:
  • Interactively to create the app in your home tenant
  • Passing credentials to create the app in your home tenant
  • Interactively in a specific tenant
  • Passing credentials in a specific tenant
  • Interactively in a specific tenant and naming apps
  • Passing credentials in a specific tenant and naming apps
• Post configuration

Tasks

The following are suggested tasks, as these may be needed later.

• Run Configure.ps1 against your Azure AD B2C tenant
• Record the Application (client) ID for the regitered Web API Service application.
• Record the Application (client) ID for the registered mobile client application.

Goal of the scripts

The scripts offer a quick and consistent method for creating and configuring (and deleting) Azure AD B2C application registrations.

Presentation of the scripts

There are two PowerShell scripts, which automate the creation of the Azure Active Directory applications.

These scripts are:

• Configure.ps1 which:

  • creates Azure AD applications and their related objects (permissions, dependencies, secrets),
  • creates a summary file named createdApps.html in the folder from which you ran the script, and containing, for each Azure AD application it created:
    • the identifier of the application
    • the AppId of the application
    • the url of its registration in the Azure portal.

• Cleanup.ps1 which cleans-up the Azure AD objects created by Configure.ps1.

Usage pattern for tests and DevOps scenarios

The Configure.ps1 will stop if it tries to create an Azure AD application which already exists in the tenant. This is what is shown in the steps below.

How to use the app creation scripts ?

Pre-requisites

1. Open PowerShell (On Windows, press Windows-R and type PowerShell in the search window)
2. Navigate to the root directory of the project.
3. Until you change it, the default Execution Policy for scripts is usually Restricted. In order to run the PowerShell script you need to set the Execution Policy to RemoteSigned. You can set this just for the current PowerShell process by running the command:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

(Optionally) install AzureAD PowerShell modules

The scripts install the required PowerShell module (AzureAD) for the current user if needed. However, if you want to install if for all users on the machine, you can follow the following steps:

4. If you have never done it already, in the PowerShell window, install the AzureAD PowerShell modules. For this:

   1. Open PowerShell as admin (On Windows, Search Powershell in the search bar, right click on it and select Run as administrator).

   2. Type:

      Install-Module AzureAD

      or if you cannot be administrator on your machine, run:

      Install-Module AzureAD -Scope CurrentUser

Run the script

5. Go to the AppCreationScripts sub-folder. From the folder where you cloned the repo,

   cd AppCreationScripts

6. Run the scripts. See below for the six options to do that.

Six ways to run the script

We advise five ways of running the script:

• Interactive: you will be prompted for credentials, and the scripts decide in which tenant to create the objects,
• Non-interactive: you will provide credentials, and the scripts decide in which tenant to create the objects,
• Interactive in specific tenant: you will provide the tenant in which you want to create the objects and then you will be prompted for credentials, and the scripts will create the objects,
• Non-interactive in specific tenant: you will provide tenant in which you want to create the objects and credentials, and the scripts will create the objects.
• Interactive in specific tenant, naming the apps: you will provide tenant in which you want to create the objects and credentials, the application names, and the scripts will create the objects.
• Non-interactive in specific tenant, naming the apps: you will provide tenant in which you want to create the objects and credentials, the application names, and the scripts will create the objects.

Here are the details on how to do this.

Option 1 (interactive)

• Just run . .\Configure.ps1, and you will be prompted to sign-in (email address, password, and if needed MFA).
• The script will be run as the signed-in user and will use the tenant in which the user is defined.

Note that the script will choose the tenant in which to create the applications, based on the user. Also to run the Cleanup.ps1 script, you will need to re-sign-in.

Option 2 (non-interactive)

When you know the indentity and credentials of the user in the name of whom you want to create the applications, you can use the non-interactive approach. It's more adapted to DevOps. Here is an example of script you'd want to run in a PowerShell Window

$secpasswd = ConvertTo-SecureString "[Password here]" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("[login@tenantName here]", $secpasswd)
. .\Cleanup.ps1 -Credential $mycreds
. .\Configure.ps1 -Credential $mycreds

Option 3 (Interactive, but create apps in a specified tenant)

If you want to create the apps in a particular tenant, you can use the following option:

• Open the Azure portal
• Select the Azure Active directory you are interested in (in the combo-box below your name on the top right of the browser window)
• Find the "Active Directory" object in this tenant
• Go to Properties and copy the content of the Directory Id property
• Then use the full syntax to run the scripts:

$tenantId = "yourTenantIdGuid"
. .\Cleanup.ps1 -TenantId $tenantId
. .\Configure.ps1 -TenantId $tenantId

Option 4 (non-interactive, and create apps in a specified tenant)

This option combines option 2 and option 3: it creates the application in a specific tenant. See option 3 for the way to get the tenant Id. Then run:

$secpasswd = ConvertTo-SecureString "[Password here]" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("[login@tenantName here]", $secpasswd)
$tenantId = "yourTenantIdGuid"
. .\Cleanup.ps1 -Credential $mycreds -TenantId $tenantId
. .\Configure.ps1 -Credential $mycreds -TenantId $tenantId

Option 5 (interactive, and create apps in a specified tenant and naming apps)

This option combines option 2, 3 and option 4: it creates the application in a specific tenant, naming the registered apps. See option 3 for the way to get the tenant Id. Then run:

$tenantId = "yourTenantIdGuid"
$SeriveAppName = "Your Web API service app name"
$MobileClientName = "Your mobile client name"
. .\Cleanup.ps1 -TenantId $tenantId -ServiceApplicationName $SeriveAppName -ClientApplicationName $MobileClientName
. .\Configure.ps1 -TenantId $tenantId -ServiceApplicationName $SeriveAppName -ClientApplicationName $MobileClientName

Option 6 (non-interactive, and create apps in a specified tenant and naming apps)

This option combines option 2, 3 and option 4: it creates the application in a specific tenant, naming the registered apps. See option 3 for the way to get the tenant Id. Then run:

$secpasswd = ConvertTo-SecureString "[Password here]" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("[login@tenantName here]", $secpasswd)
$tenantId = "yourTenantIdGuid"
$SeriveAppName = "Your Web API service app name"
$MobileClientName = "Your mobile client name"
. .\Cleanup.ps1 -Credential $mycreds -TenantId $tenantId -ServiceApplicationName $SeriveAppName -ClientApplicationName $MobileClientName
. .\Configure.ps1 -Credential $mycreds -TenantId $tenantId -ServiceApplicationName $SeriveAppName -ClientApplicationName $MobileClientName

Post configuration

These configuration steps are required as some of the options are not (yet) available in the AzureAD PowerShell module.

Grant admin consent

Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process.

1. Sign in to the Azure portal.
2. Select the Directory + Subscription icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
3. In the Azure portal, search for and select Azure AD B2C.
4. Under Manage, select App registrations.
5. On the App registrations page, select the Owned applications tab and select the client application.
6. On the Client application page, under Manage, select API Permissions.
7. On the API permissions page, click on Grant admin consent for..., and select Yes when asked to confirm concent.

Update manifest of Client

1. Sign in to the Azure portal.
2. Select the Directory + Subscription icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
3. In the Azure portal, search for and select Azure AD B2C.
4. Under Manage, select App registrations.
5. On the App registrations page, select the Owned applications tab and select the client application.
6. On the Client application page, under Manage, select Manifest.
7. Change the following:

   "accessTokenAcceptedVersion": 2,
   "signInAudience": "AzureADandPersonalMicrosoftAccount",

8. Click on Save.

Update manifect of Web API Service

1. Sign in to the Azure portal.
2. Select the Directory + Subscription icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
3. In the Azure portal, search for and select Azure AD B2C.
4. Under Manage, select App registrations.
5. On the App registrations page, select the Owned applications tab and select the web API service application.
6. On the Client application page, under Manage, select Manifest.
7. Change the following:

   "accessTokenAcceptedVersion": 2,
   "oauth2AllowIdTokenImplicitFlow": false,
   "signInAudience": "AzureADandPersonalMicrosoftAccount",

8. Click on Save.

More information

• For more information on Azure B2C, see the Azure AD B2C documentation homepage.
• Azure portal
• Tutorial: Register a web application in Azure Active Directory B2C
• Tutorial: Grant access to an ASP.NET web API using Azure Active Directory B2C