Request-a-guest Deployment

Request-a-guest is deployed using a PowerShell script to create all the resources the app requires. Once the script has been run there are some manual tasks required to complete the installation.

Table of Contents

• Request-a-guest Deployment
  • Table of Contents
    • Prerequisites
    • Permissions
    • Installation
      • 1. Create Service Account
      • 2. Create or Define Approval Team
      • 3. Define Deployment Variables
      • 4. Run Deployment
      • 5. Import the PowerApp
      • 6. Modify the PowerApp
      • 7. Share the PowerApp
      • 8. Add Guest Approvers
      • 9. Add Guest Approvers
      • 10. Add the App to Teams
    • Appendix
      • Azure Locations
      • Obtain Team and Channel ID
    • Further Reading

Prerequisites

The solution requires an Azure subscription including the following:

• Azure CLI
• PowerShell
• Power Apps Studio
• Azure Subscription
• Service account with Teams, SharePoint and Exchange licences (an Exchange mailbox is required).
• SharePoint
• A Microsoft Team and Channel created to post approval adaptive cards. You will need the Team ID and the Channel ID for the deployment. See the appendix for steps to obtain the Team and Channel ID.
• Add the Service Account as a member of the Microsoft Team used for approvals

On the installation machine install Azure CLI from here:

https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli

Permissions

To install Request-a-guest the following permissions are required.

• Global Administrator of the Microsoft 365 tenant.
• Subscription owner of the Azure AD subscription.

Installation

1. Create Service Account

A service account is required to post Teams adaptive cards and receive notification emails. The account is made a member of the Guest Approvers security group that is created during deployment and is made an Owner of the SharePoint site. The account requires licences for:

• PowerApps
• Exchange Online
• SharePoint Online
• Microsoft Teams

Important - The service account is used to run the DomainCheck script using Azure runbooks. The account may need to be excluded from Conditional Access policies enforcing login restrictions.

2. Create or Define Approval Team

A Microsoft Team and channel is used to post approval requests via an adaptive card, this can be a new or existing Team.

Important - Private channels are not currently supported by the Teams connector

The Team ID and Channel ID are required for the deployment. Steps to obtain these are located in appendix here: Obtain Team and Channel ID

Important - Ensure that the service account that you created is a member of this Team. This is required for the service account to successfully post adaptive cards to the Team.

3. Define Deployment Variables

• Download the whole solution folder from GitHub and extract to your local machine

• Add your environment details in the following file before you start:

request-a-guest-config.json

The file is located in the folder Config

Note: Ensure you do not break the JSON structure, for example by introducing additional whitespaces.

• SubscriptionID - The Azure AD Subscription ID. Find your Azure subscription

• TenantID - The Microsoft 365 tenant ID. Find your tenant ID

• TenantName - The Microsoft 365 tenant name. This is the initial tenant name used to sign up for Microsoft 365. If you are unsure on your tenant name this can be obtained from the Microsoft 365 Admin Centre, Setup, Domains. Find a domain which ends with .onmicrosoft.com. The first part of this domain is the tenant name.

• Location - The location for the Azure Resource Group. See the appendix for valid locations

• AppRegistrationName - The name of the app registration. This is created by the deployment script.

• ResourceGroup - The name for the resource group. This is created by the deployment script.

• ServiceAccountUPN - The UPN of the service account created in step 1

• KeyVaultName - The name of the KeyVault. This name must be globally unique and contain between 3 and 24 characters. This is created by the deployment script.

• AutomationAccountName - The name to give to the automation account. This is created by the deployment script.

• GuestApproverGroup - The Microsoft 365 Group that will be created. Members of this group will be able to approve guest requests. This is created by the deployment script.

• GuestRequestorGroup - The Microsoft 365 Group that will be created. Members of this group will be able to create guest requests. This is created by the deployment script.

• RequestsSiteName - The name for the SharePoint site to host the list of requests. This is created by the deployment script.

• RequestSiteDesc - A description for the SharePoint site.

• ManagedPath - The SharePoint managed path. This is usually 'Sites' but may be customised if you wish to use a different site collection.

• ApprovalTeamGroup ID - The Group ID of the Microsoft Team that will be used for approval requests

• ApprovalChannelID - The Channel ID of the channel within the Team that will be used to post approval requests

4. Run Deployment

After you have defined your deployment variables in the JSON file you are ready to run the deployment. Navigate to the folder where the deployment script and all other config files are located.

Start PowerShell as Administrator, navigate to the script folder and run the following cmdlets.

Firstly to unblock the file run:

Unblock-file .\request-a-guest-deploy.ps1

Then to run the script enter the following command:

.\request-a-guest-deploy.ps1 -AdminUsername [email protected] -mfa $false

Note: You will be asked for two different passwords. The password of the Administrator that runs the script (if MFA is set to $false) and the Service account that you defined in the config file.

During deployment you will be prompted for admin credentials to connect to SharePoint. Please enter the Global Admin credentials

You will then be prompted to provide consent to the API connections within Logic apps. Please log in as the service account specified in the config file. You will be prompted for each api connection (5 connections)

Once deployment has completed you will be presented with the following screen. Take note of the SharePoint URL and the Guest Approvers Group ID as you will need these to complete the installation.

5. Import the PowerApp

• Navigate to Power Apps.

• Click on Apps in the left side pane and click on Import canvas app.

• Upload the package zip file and click Import.

6. Modify the PowerApp

• Click on Open app link when the zip package is successfully imported. You will be redirected to the Power Apps portal.

• The app will request your permission to use all the listed data connections.

• Once the app opens, in the horizontal menu, click on View and select Data sources. **Remove the existing demo SharePoint connection to Guest SharePoint List by clicking on "..." and remove **. This ensure that the dummy SharePoint connection is removed and the app is ready to connect with the SharePoint site.

• Click Add Data, search for SharePoint and select SharePoint as a data source.

• Enter the newly created SharePoint URL in the pop-up window. This was listed in the config JSON file and also provided at the end of the deployment script.

• Tick the "Guests" list and click Connect.

• On app 'OnStart' function, paste the group ID of the guest approvers group created by the deployment script. The group ID was provided at the end of the deployment.

• From the File menu, Save and then Publish the App.

7. Share the PowerApp

In order for users to have access to the PowerApp you need to share the app with them.

• Open https://make.preview.powerapps.com/

• Navigate to the Apps menu in the left menu bar and you will see the app you have imported.

• Click on the 3 dots (Options) for your app and click 'Share'

• Enter either a group of users or 'Everyone' if all users will be allowed to raise requests. Untick 'Send an email invitation to new users' to prevent users from being notified. Click 'Share' once complete

8. Add Guest Approvers

Now that the app has been deployed you must add guest approvers to the Guest Approvers group that was created. This can be done manually through Azure AD.

• Navigate to https://portal.azure.com and access Azure AD, Groups.

• Search for the Guest approvers group that was created as part of the deployment script. The name was provided when you modified the Config file.

• Add users to this group so that they will see the additional "Approve requests" tab and can approve guest requests.

9. Add Guest Approvers

After adding the Approvers to the Guest Approvers Group you need to do the same for the Guest Requestor Group. This also can be done manually through Azure Active Directory.

• Navigate to https://portal.azure.com and access Azure AD, Groups.

• Search for the Guest Requestors group that was created as part of the deployment script. The name was provided when you modified the Config file.

:memo: Note
The deployment will create the group with manual member assignment but you can also use Dynamic Group Membership to add members to the group based on specific expressions.
More details can be found here: Dynamic membership rules for groups in Azure Active Directory

10. Add the App to Teams

Depending on your scenario you may wish to add the app to Microsoft Teams and pin for all users. This can be achieved by following the steps below.

• Open https://make.preview.powerapps.com/

• Navigate to the Apps menu in the left menu bar and you will see the app you have imported.

• Click on the 3 dots (Options) for your app and click on Add to Teams.

• Click on Download App in the popup to download a zip package.

• Extract the contents of the zip file on your computer.

• Edit the manifest.json file and replace the value in the id property with the following id -

  8e58f1ce-ce17-45b5-9f88-835462639011

  The line should read as follows - "id": "8e58f1ce-ce17-45b5-9f88-835462639011",

• Save the file

• Re-zip the extracted files (manifest.json,color.png and outline.png) ensuring they are in the root of the zip file and not inside a subfolder.

• Open Teams admin center: https://admin.teams.microsoft.com/

• Navigate to Teams apps > Manage Apps and click Upload.

• Click Select a file and browse to the zip file

• Navigate to Teams apps > Setup policies and select the policy which applies to users who would need the app pinned.

• Under Pinned apps select Add app.

• Search for the Request-a-guest app, select the app and click Add.

Note: It might take a bit of time until the app setup polices applies to the user.

After that you are ready to create your first request.

Appendix

Azure Locations

Region	Display Name
East Asia	eastasia
Southeast Asia	southeastasia
Central US	centralus
East US	eastus
East US 2	eastus2
West US	westus
North Central US	northcentralus
South Central US	southcentralus
North Europe	northeurope
West Europe	westeurope
Japan West	japanwest
Japan East	japaneast
Brazil South	brazilsouth
Australia East	australiaeast
Australia Southeast	australiasoutheast
South India	southindia
Central India	centralindia
West India	westindia
Canada Central	canadacentral
Canada East	canadaeast
UK South	uksouth
UK West	ukwest
West Central US	westcentralus
West US 2	westus2
Korea Central	koreacentral
Korea South	koreasouth
France Central	francecentral
France South	francesouth
Australia Central	australiacentral
Australia Central 2	australiacentral2
South Africa North	southafricanorth
South Africa West	southafricawest

Obtain Team and Channel ID

To obtain the Team and Channel ID follow the steps below.

1. Open PowerShell as an administrator and run the following commands

   Install-Module MicrosoftTeams

   Connect-MicrosoftTeams

   Get-Team -DisplayName 'Guest Approval team'

2. Copy the 'Group ID' that is returned. This is required for the Config file.

3. Use the Group ID you obtained in the following command to obtain the channel ID

   Get-TeamChannel -GroupID 'ApprovalGroupID'

4. Cope the ID from the above command for use in the config file

Further Reading

Home

Architecture

Cost Estimates

Data Retention

Deployment Guide

Troubleshooting