How to Use PowerShell for containers (QT Operational Team)

User Story

There are various areas where you want isolation of data for Nova users. A few are stated below in a simple list:
  • I only want my level 1 support in Germany to see German based users
  • I want my Business Unit manager to see data from all users in the business unit.
  • I want Business users to only see User data and now Exchange, SharePoint or other data.
  • I want the PII data of users in Germany, Austria and Switzerland to be Masked for my users outside of those countries
What is required is the ability to partition information in a tenant in a logical, virtual and granular fashion.  This provides the isolation required by departments, business units, brands, clients or any other virtual entities.   Organisational boundaries come in many forms and may be defined by business operations, geography/jurisdiction and IT operations.  Subsidiaries, business units, administrative span of control, Teams information barriers, departments, and information barriers erected to protect client confidentiality are all examples of organisational boundaries that require isolation.

 

This is related to the feature called Virtual Business Boundaries. (VBB)

In this article we’ll create a container, add a user to that container, implement some restrictions relating to datasources and other associated activities. The user in this scenario needs to be invited to the tenant, and needs to have logged in.

Required roles and access to run PowerShell on containers

The operations described here, require System Administrator access. The scripts and cmdlets shown use the role ID of system administrator. The people who are put into the virtual business boundaries do not need this level of access.

Syntax Documentation of Powershell

Generally speaking each cmdlet needs:

  • Organization where the cmdlet will be applied
  • System Administrator role ID
  • Token (ie authorisation to run the cmdlet)

The following cmdlets have been implemented to do ‘creation’ activities:

  • New-NovaContainer
  • New-NovaContainerUser
  • New-NovaContainerDatasource

These are the cmdlets to process containers:

  • New-NovaContainer
  • Update-NovaContainer
  • Remove-NovaContainer

 

  • Get-NovaContainers
  • Get-NovaContainer

 

  • New-NovaContainerUser
  • New-NovaContainerDataSource
  • Remove-NovaContainerUser
  • Remove-NovaContainerDataSource

There are, at the moment, several ‘update’ cmdlets which are not yet implemented.

Example of how to create a container

To create a container:

  • Get a Token, the Org ID, and, Role ID (as described below)
  • Execute the following commands:

$containerName = ‘Name of the container you want to create’

New-NovaContainer -token $Token -organizationID $OrgID -name $ContainerName -roleID $RoleID

This will return the Container ID of the newly created container.

Now we’ll add a user to that container:

We must first of all convert the email ID of the user we want to add, to it’s ID in TMS. We do this as follows:

$email = ’email-of-the-user@somedomain.com’

Get-UserFromOrganization -token $Token -organizationID $OrgID -roleID $RoleID -email $email

Now we continue:

$ContainerID = ‘id of container that the create cmdlet returned’

$userID = ‘id of the user that the get-userFromOrganization cmdlet returned’

New-NovaContainerUser -token $Token -organizationID $OrgID -containerID $ContainerID -userID $UserID -roleID $RoleID

Note: You can include an additional parameter: -anonymous $true. If this is set then the data is anonomized.

The next step is to add datasources, scope restrictions and allowed fields to the container.

Notes:

  • An easy way to find out field names and data sources names is to build a report in Nova first with the selection you would like to use. Export that reports definition to a JSON file, and then review the JSON file.
  • If you want to allow all fields ensure you use $AllowedFields = @()
  • Restrictions can include custom attributes, eg $Restrictions = “exchrecipattr2.CustomAttribute1=\’123\'”
  • If you have business managers who wish to see only their direct reports, the restriction can be set to: $Restrictions = “Manager_UPN={CUR_USER_EMAIL}”. With this implemented it means that a business manager who has users with their ‘report to’ field set to him or her will only be able to see himself, and his direct reports.
  • Other restrictions include {CUR_USER_ID} and {CUR_USER_ORG}

$DataSource = “azure_users”

$Restrictions = “Department=Finance”

$AllowFields = @()

 

New-NovaContainerDataSource -token $Token $organizationID $OrgID -containerID $ContainerID $datasource $DataSource -roleID $RoleID -restriction $Restrictions -allowFields $AllowFields

This final step verifies that the container is correctly created:

Get-NovaContainer -token $Token -organizationID $OrgID -containerID $ContainerID -roleID $RoleID

Example of adding a restriction to a container so a manager can see direct reports

A common scenario in large organization is that you would want line managers to only be able to see their direct reports.

To do this, create a new container, as described previously.

Apply the following:

$DataSource = “azure_users”

$Restrictions = “Manager_UPN={CUR_USER_EMAIL}”

$AllowFields = @()

And then execute this cmdlet:

New-NovaContainerDataSource -token $Token $organizationID $OrgID -containerID $ContainerID $datasource $DataSource -roleID $RoleID -restriction $Restrictions -allowFields $AllowFields

Example of how to list existing containers in a tenant

To list the containers:

  • Get a Token, the Org ID, and, Role ID (as described below)
  • Execute the following command:

Get-novaContainers -token $Token -organizationId $OrgID -roleId $RoleID

The output will look similar to this:

Example of how to delete an existing container

To delete a container:

  • Get a Token, the Org ID, and, Role ID (as described below)
  • Execute the following command

Remove-NovaContainer -organizationID $orgID -roleId $roleID -token $token -containerID <id of a container>

You can list the containers first, to obtain the container ID.

Using this feature

Below are the major steps in using this feature.

1

The first step is to get the modules, and import them. This only has be done once, and then repeated from time to time to ensure that the latest versions of the cmdlets are used.

You have to create (one time) a Personal Access Token. To do that go to https://dev.azure.com/quadroteam/ and choose Personal Access Token.

Create a new access token, and ensure it has at least ‘Read’ for ‘Packaging’:

That token can then be used in this script:

# fill this part with your details
$patToken = “YOUR PERSONAL ACCESS TOKEN” | ConvertTo-SecureString -AsPlainText -Force
$credsAzureDevopsServices = New-Object System.Management.Automation.PSCredential(“YOUR EMAIL”, $patToken)

# register PowerShell repository
Register-PSRepository -Name “QT-ADO-PowerShellModules” -SourceLocation “https://pkgs.dev.azure.com/quadroteam/_packaging/PowerShellModules/nuget/v2” `
-PublishLocation “https://pkgs.dev.azure.com/quadroteam/_packaging/PowerShellModules/nuget/v2” -InstallationPolicy Trusted -Credential $credsAzureDevopsServices

# check versions & modules in the repository
Find-Module -Repository “QT-ADO-PowerShellModules”

# get the CMS cmdlets installed as a module to be usable right away
Install-Module -Name “Invoke-NovaRequest” -Repository “QT-ADO-PowerShellModules” -Credential $credsAzureDevopsServices

 

More information available here.

Note: In order to be able to run the import you’ll need to do:

set-executionPolicy -ExecutioPolicy RemoteSigned

2

The next step is to obtain a token, it’s used in all of the cmdlets.

To obtain a token open the Dev Tools for your browser, and locate a request to Nova. Most of them have a token in them.

3

The next step is to obtain the Org ID.

You do this in TMS as it’s part of the URL:

4

Now you need the Role ID for the System Administrator role. It’s the same across all Nova tenants.

5816e978-8df6-4152-ba64-8db785ae33de

5

cmdlets can now be run!

From time to time, depending how long it takes you to prepare the steps you want to perform, you may get an error back from a cmdlet. This usually relates to the token expiring – they’re only valid for 15 minutes.

Here is a link to the OneDrive containing the PowerShell modules described and needed, and, a document which outlines more details about this feature.