Skip to content

Latest commit

 

History

History
277 lines (193 loc) · 18.3 KB

CreationScript.md

File metadata and controls

277 lines (193 loc) · 18.3 KB

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

Quick summary

  1. Open the Azure portal. Navigate to the 'Portal settings' page. Copy and save the Directory ID somewhere for later use. Screenshot

  2. Open the Azure portal. Navigate to the 'Subscription' page. Copy and save the Subsription ID under that directory somewhere for later use. Screenshot

  3. Download PowerShell, PowerShellGet and Bicep tool

  4. Run PowerShell navigate to the directory

  5. Run the script to create your Azure AD tenant and enter the parameters (tenantId - Directory ID ; subscriptionId - Subsription ID) accordingly. During this process, two pop-ups will appear asking you to enter your identity information.

    cd .\Scripts\
.\1-authentication.ps1

Now you have done the following work by script:

  • Create a CIAM tenant.
  • Create the app registration with offline_access and open_id permission under admin grant.
  • Create a service principal for the app.
  • Create a user flow as the default one.
  • Create a customized localization branding as the default one.

More details

How to use the scripts?

Pre-requisites

  1. Download PowerShell, PowerShellGet and Bicep tool
  2. Open PowerShell (On Windows, press Windows-R and type PowerShell in the search window)
  3. Navigate to the root directory of the project.

Run the creation script and start running step by step

  1. Open the Azure portal. Navigate to the 'Portal settings' page. Copy and save the Directory ID somewhere for later use. Screenshot

  2. Open the Azure portal. Navigate to the 'Subscription' page. Copy and save the Subsription ID under that directory somewhere for later use. Screenshot

  3. Download PowerShell, PowerShellGet and Bicep tool

  4. From the folder where you cloned the repo, go to the Scripts folder. Run the script to create your Azure AD tenant and enter the parameters accordingly (tenantId - Directory ID ; subscriptionId - Subsription ID). During this process, two pop-ups will appear asking you to enter your identity information.

    cd .\Scripts\
.\1-authentication.ps1

  5. After finishing running the creation script, go to the application page in the portal, open the Azure portal and navigate to the 'Portal settings' page. Switch to the tenant newly created by the script. Screenshot

  6. Copy the link appeared in the PowerShell interface and visit that link through browser (If you did not switch to the correspond tenant in the previous step, you are likely to meet problem in this step). Copy Application (client) ID and Directory (tenant) ID which are used in later steps. Screenshot

  7. You can use Javascript sample appliation to test functionality. Under "ms-identity-javascript-tutorial\1-Authentication\1-sign-in\App", open authConfig file to replace the Application (client) ID and Directory (tenant) ID as figure showed. Screenshot

  8. Start the sample application using the lines below in the PowerShell. This step require Node.js installed.

    cd ms-identity-javascript-tutorial\1-Authentication\1-sign-in\App
npm install
npm start

    Screenshot

  9. Open your browser and visit http://localhost:3000/. You will see the page as the figure showed (recommended to use Edge private view mode). Screenshot

  10. Click Sign-in at the right-up corner to start the authentication flow. If choose Have an account? Sign in instead, you are going to jump into sign-up flow. Screenshot

  11. After filing in your email, one time passcode and new password, you complete the whole sign-up flow. The page will show your newly created information as the figure showed. Screenshot

  12. Click the Sign-out at the right-up corner to sign-out. The following pages are showed below. Screenshot Screenshot

Run the deletion script and start cleaning step by step

  1. From the folder where you cloned the repo, go to the Scripts folder. Run the script to create your Azure AD tenant and enter the parameters accordingly (tenantId - the directory ID you want to delete).

    cd .\Scripts\
.\1-authentication-cleanup-except-last-CIAM.ps1

    You will You will encounter some errors due to the issue2 but this script still works fine to achieve our goal. Screenshot

  2. After running the deletion script, all initial checks in the portal should pass except 'Users' & 'Users Flow' because of the issue4. Screenshot

  3. Back to the 'Deletion tenant' page and then click Refresh button. The Delete button will be activated after refreshing. You do not need to worry about the 'Delete all user flows' hint due to the issue4. Click Delete button to complete the last action to delete the tenant. Screenshot

Goal of the provided scripts

Presentation of the scripts

This sample comes with 5 PowerShell scripts and 1 bicep file, which automate the creation of the Azure Active Directory tenant, and the configuration of the code for this sample. Once you run them, you will only need to build the solution and you are good to test.

These scripts are:

  • 1-authentication.ps1 which is a overall script combining the following scripts together except from 1-authentication-cleanup-except-last-CIAM.ps1

  • 1-authentication-setup-context-CIAM.ps1 which:

    • check and install the required modules.
    • set the policy and unblock the scripts to run.
    • set the account context to run the AzAccount PowerShell lines.

  • 1-authentication-create-tenant-CIAM.ps1 which use New-AzResourceGroupDeployment with bicep file to deploy tenant. A tenant will be created in a resrouce group.

  • 1-authentication-configurate-app-CIAM.ps1 which:

    • create the app registration
    • create a service principal for the app
    • add microsoft graph permission of offline_access and openid
    • create Oauth2 permission grant
    • create a user flow
    • customize the branding of the text information
    • creates a summary containing:
      • the identifier of the application
      • the AppId of the application
      • the url of its registration in the Azure portal.

  • 1-authentication-cleanup-except-last-CIAM.ps1 which cleans-up the Azure AD objects created by 1-authentication.ps1. Note that this script delete applications, service principals, user flows and elevate the role but does not delete resource group. It prepare for the last delete click in the portal to delete tenant.

Usage pattern for tests and DevOps scenarios

The 1-authentication.ps1 contain resource existence checking logic. It will skip the creation step for an existing resource and exit if the creation fails or an error occurs. So you can re-run the script. The 1-authentication-cleanup-app-CIAM can be re-run as well.

Explanation on the scripts

1-authentication-setup-context-CIAM.ps1

Mandatory parameters:

parameters explanation
tenantId Tenant ID where the subscription ID is located
subscriptionID Subscription ID used to pay for the new tenant

References:

1-authentication-create-tenant-CIAM.ps1

Optional parameters:

parameters explanation
resourceGroupName Resource Group Name (Default: "ciamtest")
tenantPrefix Prefix for Tenant (Default: "ciamtest" + 5-digit random string)
resourceGroupLocation Location for Resource Group if it is created (Default: "northeurope")

References:

1-authentication-configure-app-CIAM.ps1

Mandatory parameter:

parameters explanation
tenantId Tenant ID newly created

Optional parameters:

parameters explanation
applicationName Display Name for application (Default: "CIAM Test App")
environmentName Graph environment to use while running the script (Default: "Global")

References:

  1. Establish connection.

    Using Microsoft Graph PowerShell authentication commands | Microsoft Learn

  2. Create the app registration.

    Get-MgApplication (Microsoft.Graph.Applications) | Microsoft Learn

  3. Create a service principal for the app.

    Get-MgServicePrincipal (Microsoft.Graph.Applications) | Microsoft Learn

  4. Add Microsoft Graph permission of offline_access and openid.

  5. Create Oauth2 permission grant.

    Grant tenant-wide admin consent to an application

    Grant consent on behalf of a single user by using PowerShell

  6. Create a user flow (MS Graph API, no available command line).

    ciam/API#3-CIAM-user-flows.md at main · microsoft-entra/ciam (github.com)

  7. Customize the experience.

    Get organizationalBrandingLocalization - Microsoft Graph beta | Microsoft Learn

1-authentication-cleanup-app-CIAM.ps1

Mandatory parameter:

parameters explanation
tenantId Tenant ID newly created

Optional parameters:

parameters explanation
applicationName Display Name for application (Default: "CIAM Test App")
environmentName Graph environment to use while running the script (Default: "Global")

References:

  1. Remove applications.

    Remove-AzADApplication (Az.Resources) | Microsoft Learn

  2. Remove user flows (MS Graph API, no available PowerShell). ciam/API#3-CIAM-user-flows.md at main · microsoft-entra/ciam (github.com)

  3. Remove service principals of the app.

    Remove-AzADServicePrincipal (Az.Resources) | Microsoft Learn

  4. Remove all users of the tenant.

    Remove-MgUser

    Microsoft Graph permissions reference

  5. Elevate role (API/CLI, no available PowerShell).

    Elevate access to manage all Azure subscriptions and management groups | Microsoft Learnissue1

    Global Administrator - Elevate Access - REST API (Azure Authorization) | Microsoft Learn

Issue list in CIAM PP1

  1. Bug 2175335: [Tenant Creation] New-AzResourceGroupDeployment related bugs - Boards (visualstudio.com)
  2. Bug 2175345: [PowerShell] MS Graph Enterprise Applications Deletion - Boards (visualstudio.com)
  3. Bug 2175348: [User Flow] Unstable MS Graph user flow API endpoints - Boards (visualstudio.com)
  4. Bug 2175350: [User Flow PowerShell] Always shows “No user flows found” in the portal - Boards (visualstudio.com)
  5. Bug 2175371: [Portal] Delete button bug in the portal - Boards (visualstudio.com)
  6. Bug 2175385: [Branding] No image removal PowerShell - Boards (visualstudio.com)
  7. Bug 2181319: [Branding PowerShell] API / PowerShell invalid when try to upload the background image - Boards (visualstudio.com)
  8. Bug 2175410: [PowerShell] Currently only APIs no PowerShell command lines - Boards (visualstudio.com)