Skip to content
This repository has been archived by the owner on Oct 17, 2024. It is now read-only.

Deployment Guide for GCC

Jump to bottom
v-smahaj edited this page Jun 16, 2021 · 1 revision

How to choose the deployment procedure appropriate for your configuration?

Note : This guide is intended for customers requiring the deployment of New Employee Onboarding of Office 365 Government Community Cloud (aka GCC) only - The standard deployment for Azure AD Commercial tenant is located here

Microsoft provides different cloud offering across Office 365, Azure or the Power Platform to meet customers compliance and regulation requirements. While the global Office 365 and Azure flavors, referred as “Commercial” cloud, are the default and most used environments, customers can choose other alternatives that we’ll refer as Microsoft Cloud for Government.

Microsoft Cloud for Government provides a comprehensive cloud platform designed expressly for U.S. Federal, State, and Local Governments to meet the U.S. Government’s thorough security and compliance regulations. Microsoft Cloud for Government meets the standards of many government agencies, including FedRAMP, HIPAA, and CJIS, to name a few.

Depending on the cloud offerings that are used, there are differences to consider in terms of service availability and URLs to access and manage those services. Here is a global representation of these different configuration across Office 365, Azure and Power Platform for Commercial and US Gov cloud offerings.

If you need more information on these offerings for US Sovereign Cloud, please refer to the following article - https://aka.ms/AA632wo

Here are the tests to run to identify you current GCC setup :

Check 1 - Identify your Office 365 configuration.

Lookup Results Mapping
Azure AD Instance: Azure AD Global, Tenant Scope: Not applicable O365 Commercial
Azure AD Instance: Azure AD Global, Tenant Scope: GCC (Moderate) O365 GCC
Azure AD Instance: Azure AD Government,Tenant Scope: GCC High O365 GCC-H

Save this value as the result for Check 1

Check 2a - Identify your Azure configuration (for templates based on Azure resources only)

There are only two options here based on the URL used to access the Azure portal and deploy your resources.

Azure portal URL Mapping
https://portal.azure.com Azure Commercial
https://portal.azure.us Azure Government

Save this value as the result for Check 2a

More info on Azure services and URL patterns for Commercial vs Gov clouds

Compare Azure Government and global Azure - Azure Government | Microsoft Docs

Check 2b - Identify your Power Platform configuration (for templates based on Power Platform only)

Here are the URL patterns for Power Platform to determine the cloud environment.

Power App portal URL Mapping
https://*.powerapps.com Power App Commercial
https://*.gov.powerapps.us Power App GCC
https://*.high.powerapps.us Power App GCC-H
Not supported Power App DoD

Save this value as the result for Check 2b

More info on Power Platform services and URL patterns for Commercial vs Gov clouds

Microsoft Power Apps US Government - Power Platform | Microsoft Docs

Check 3 - Are you running in multi or single-tenancy mode (for templates based on Azure resources only)?

This question is to determine if your Azure subscription is linked to the same Azure AD as the one where your Office 365 users are deployed.

If you use the same domain to access the Azure portal than your O365 services, the answer is single-tenancy. e.g. you use your O365 credentials to access the Azure portal.

Otherwise, the answer is multi-tenancy. e.g. you have different email addresses or use different Azure AD to access O365 and the Azure.

Based on these different checks, you can determine your configuration and which deployment model to use.

Save this value as the result for Check 3

Your Microsoft Teams app templates is based on Azure resources.

Check 1 Check 2a Check 3 Supported Deployment scenario
O365 Commercial Azure Commercial Single Yes Standard
O365 Commercial Azure Commercial Multi Yes Standard (1)
O365 GCC Azure Commercial Single Yes Standard (2)
O365 GCC Azure Commercial Multi Yes Standard (1) (2)
O365 GCC Azure Government Single Not Supported Not Available (3)
O365 GCC Azure Government Multi Yes Hybrid
O365 GCC-H/DoD Any Any Not Supported Not Available (4)

(1) Use the standard deployment procedure – Pay attention to the tenantID provided in the input parameters of the ARM template: you should change the default value (the Azure AD linked to your Azure subscription) to the Azure AD tenantID where your O365 users and services are located.

(2) Use the standard deployment procedure – Microsoft Teams admin portal for GCC now supports “Manage Apps” as well as “App setup policies” – Also, Teams for GCC now supports “Message Extensions” so there is nothing specific to do to deploy on O365 GCC compared to O365 Commercial with Azure Commercial.

(3) By design, O365 GCC and Azure Gov are connected to different Azure AD tenants – It’s not possible to be in a single tenant configuration with this setup.

(4) Most the Microsoft App templates rely on the Azure Bot Service to enable bot / Message Extensions in Teams. Microsoft Teams channel is not yet enabled for Azure Bot Service on Azure Government.

Before deploying a Teams app template to your Azure Government subscription, make sure that all the required services and pre-requisites are met. This means that the list of required Azure services are available and registered on the targeted region. This page explains how to verify that a resource provider is available and how to register it for your subscription -

Resource providers and resource types - Azure Resource Manager | Microsoft Docs

Your Microsoft Teams app templates is based on Power Platform.

Check 1 Check 2b Supported Deployment scenario
O365 Commercial Power Platform Commercial Yes Standard
O365 GCC Power Platform GCC Yes Standard (5) (6)
O365 GCC-H Power Platform GCC-H Yes Standard (5) (6)
O365 DoD Power Platform DoD Not Supported Not Available (7)

(5) Use the standard deployment procedure – Depending on the pre-requisites and services used on the Power Platform, some Teams app template may not be available for O365 GCC/GCC-H. A complete list of O365 and Power Platform services available on Office 365 Gov and service plan is available here -

Office 365 US Government - Service Descriptions | Microsoft Docs

(6) For Teams app templates that require Dataverse for Teams in GCC/GCC-H, you will need an additional stand-alone license for Power Apps. This is a current limit.

(7) Power Platform is not available on O365 DoD and is therefore out of scope.

What is “hybrid deployment”?

In this setup, the Office 365 users and Microsoft Teams service are hosted in a different Azure AD tenant as the Azure resources. Also, both O365 and Azure use a Government Cloud:

  • Office 365 with a GCC Azure AD tenant
  • Azure Government (https://portal.azure.us) associated to its GCC-H Azure AD tenant

To register a bot as an application in Microsoft Teams, the bot needs to be registered on the Azure Bot Service. This Azure Bot Service also needs to be deployed on an Azure subscription that is linked to the Azure AD tenant where your O365 users and Microsoft Teams service are. This is what we call the hybrid deployment.

Here is a high-level representation for the hybrid deployment.

The hybrid deployment guide considers these multiple Azure subscriptions and Azure AD tenant. It also details the sequence and order of deployment of these resources.

Note : Azure Bot Service is only here to register your application as a bot in your Microsoft Teams environment. It is also used to activate SSO when needed, using the same Azure AD tenant where your O365 users are. There is no conversation data or attachments that transit via the Azure Bot Service deployed on Azure Commercial: all communications are in direct transit (https) between your Microsoft Teams service in GCC and the application bot hosted on Azure Government.

Deployment in O365 GCC tenant and Azure Commercial subscription

For O365 GCC deployment and Azure Commercial, the same deployment guide (available on New Employee Onboarding GitHub repo) can be followed. Use O365 GCC tenant for App registration (Step 1 in deployment guide) and Azure commercial subscription for ARM deployment (Step 2 in deployment guide). Make sure tenant Id of O365 GCC tenant is added during ARM deployment.

Deployment in O365 GCC tenant and Azure Government subscription

For hybrid deployment, follow these deployment guide steps.

Prerequisites

To begin, you will need:

  • An Azure Government subscription where you can create the following resources:

    • App Service
    • App Service plan
    • Azure Storage account
    • Application Insights

  • An Azure Commercial subscription where you can create the following resources:

    • Bot Channels Registration

  • A copy of the New Employee Onboarding app GitHub repo (https://github.com/OfficeDev/microsoft-teams-apps-newemployeeonboarding)

  • Estimated deployment time: This depends on you getting the MSIT approval. Installation itself will take about 30 to 45 mins.

  • User roles needed to perform the deployment: IT admin.

Deployment Steps for hybrid mode

Step 1: Register Azure AD application:

Register an Azure AD application in directory where the Team's users are homed (Office 365 GCC + Azure Commercial):

  1. Log in to the Azure Portal for your subscription, and go to the App registrations blade here. Verify that you are on the same Azure AD tenant than your O365 users and where Microsoft Teams is deployed.
  2. Click on New registration, and create an Azure AD application.
    • Name: The name of your Teams app. If you are following the template for a default deployment, we recommend "NewEmployeeOnboarding".
    • Supported account types: Select Accounts in any organizational directory (Any Azure AD directory - Multitenant)
    • For Redirect URL

  1. Select Register.
  2. When the app is registered, you'll be taken to the app's Overview page. Copy the Application (client) ID and Directory (tenant) ID. We recommend that you save these ID's in a text file, using an application like Notepad, so you can easily retrieve them as instructed at a later point in the process.
  3. Verify that the Supported account types is set to Multiple organizations.

  1. In the navigation pane, click Certificates & secrets to create a secret for your application.
    • Under Client secrets section, click on + New client secret.
    • Add a description (Name of the secret) for the secret and select an expiry time (as per the requirement).
    • Click Add
    • Before leaving this page, copy the secret and save it in the text file you created earlier.

At this point you have 3 values saved to be used later:

  • Application (client) ID which will be later used during ARM deployment as Bot Client Id and in manifest files as <<botId>>
  • Client secret for the bot which will be later used during ARM deployment as Bot Client secret
  • Directory (tenant) ID

Step 2: Create a Security Group

If you already have a security group registered in Azure AD, then skip first 4 steps below

  1. Log in to the Azure Portal for your subscription, and go to the Groups blade here.
  2. Click on New Group.

  1. Add members (new hires) to security group.

  1. Click on Create.

  1. Search for security group by group name.

  1. Go to Security Group Overview and copy Object ID and save it in your text file.

Step 3: Configure SharePoint Hub

If your SharePoint hub is already configured, you can skip the steps below, but we recommend saving the values mentioned below. You’ll use them during ARM deployment. Otherwise, get started by clicking SharePoint configuration

  1. SharePoint site name.
  2. SharePoint site new hire check list name.
  3. SharePoint site tenant name.
  4. Complete learning plan URL from SharePoint.
  5. New hire question list name from SharePoint.

Step 4: Deploy bots to your Azure Commercial subscription

  1. Click on the "Deploy to Azure" button below.

Deploy to Azure

  1. When prompted, log in to your Azure Commercial subscription.
  2. Azure will create a Custom deployment based on the ARM template and ask you to fill in the template parameters.
  3. Select a Subscription and Resource group.(We recommend creating a new resource group.)
  4. The resource group location MUST be in a datacenter that supports Application Insights.
  5. Enter a Base Resource Name, which the template uses to generate names for the other resources.
    • Save your selected Base Resource Name in your text file to be used later
  6. Fill in the following IDs in the template:
    • Bot Client ID: The application (client) ID of the Microsoft Teams Bot app.
    • Bot Client Secret: The client secret of the Microsoft Teams Bot app.

Make sure that you’ve pasted the values exactly as-is, with no extra spaces. The template checks that GUIDs are exactly 36 characters.

  1. If you wish to change the app name, description, and icon from the defaults, modify the corresponding template parameters.

  2. Click on "Review+Create" to start the deployment. It will validate the parameters provided in the template .Once the validation is passed, click on create to start the deployment.

  3. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. It can take up to 5 minutes for the deployment to finish.

  4. Search for Bot Service created by ARM template. Name of Bot Service will be base resource name which was provided earlier.

  5. Click on Channels in Settings section of Bot Services and click on "Edit" button for Microsoft Teams Channel. Click on Delete Channel.

  6. Once deleted, click on "Configure Microsoft Teams Channel" icon inside "Add a featured Channel". Select "Microsoft Teams for Government" and click on Save.

Step 5: Deploy remaining resources to your Azure Government subscription

  1. Click on the "Deploy to Azure" button below.

Deploy to Azure

  1. When prompted, log in to your Azure Government subscription.
  2. Azure will create a Custom deployment based on the ARM template and ask you to fill in the template parameters.
  3. Select a Subscription and Resource group.
  4. The resource group location MUST be in a datacenter that supports Application Insights and Storage Account.
  5. Enter and reuse the same Base Resource Name, that you gave for bots deployment in your Azure commercial.
    • The app service names (Base Resource Name) must be Available (not Taken). Otherwise, the deployment will fail with a Conflict error.
    • Save your selected Base Resource Name in your text file to be used later
  6. Fill in the following IDs in the template:
    • Bot Client ID: The application (client) ID of the Microsoft Teams Bot app.
    • Bot Client Secret: The client secret of the Microsoft Teams Bot app.
    • Tenant Id: The tenant ID of your application.
    • Manifest Id : This needs to be same as manifest ID provided in manifest.json file inside Manifest folder.
    • Human Resource Team Link: The url for the Microsot Teams team your Human Rresources department uses (where you want the app to send employee feedback notifications). This URL starts with https://teams.microsoft.com/l/team/.
    • Site Name: New employee onboarding site name.
    • New Hire Check List Name: New hire onboarding checklist name.
    • Site Tenant Name: SharePoint tenant name.
    • Share Feedback Form Url: The URL for the survey new employees will take to share feedback. Go to here to create survey MS Forms and copy the link by clicking on Share button if not created before.
    • Complete Learning Plan Url: Complete learning plan list URL.
    • New Hire Question List Name: New hire question list name from SharePoint Hub.
    • Security Group Object Id: Security group ID (Required for user role).
    • delayInPairUpNotificationInDays: Number of days to delay in pair up notification.
    • newHireRetentionPeriodInDays: Number of days for new hire retention period.

Make sure that you’ve pasted the values exactly as-is, with no extra spaces. The template checks that GUIDs are exactly 36 characters.

  1. Click on "Review+Create" to start the deployment. It will validate the parameters provided in the template .Once the validation is passed, click on create to start the deployment.
  2. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. It can take up to 5 minutes for the deployment to finish.

Step 6: Set up authentication for the app

  1. Go back to the App Registrations page here
  2. Enter the BotId created in Step 1 under Owned applications search box.
  3. Click on the application (this should be the same application registered in step 1)
  4. From the left menu under Manage, select Authentication .
  5. Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) under Supported account types and click +Add a platform.
  6. On the flyout menu, select Web

  1. Add https://[baseresourcename].azurewebsites.us/signin-simple-end under Redirect URLs and select the check boxes Access tokens and ID tokens and then click Configure.

  2. From the left menu under Manage, select Expose an API.

  1. Select the Set link to generate the Application ID URI in the form of api://{BotID}. Insert your app Domain (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://app Domain/{BotID}
  • for e.g.: api://newhireonboarding.azurewebsites.us/c6c1f32b-5e55-4997-881a-753cc1d563b7.
  1. Select the Add a scope button. In the panel that opens, enter access_as_user as the Scope name.
  2. Set Who can consent? to "Admins and users"
  3. Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope. Suggestions:
    • Admin consent display name: New Employee Onboarding
    • Admin consent description: Allows Teams to call the app’s web APIs as the current user.
    • User consent display name: Teams can access your user profile and make requests on your behalf
    • User consent description: Enable Teams to call this app’s APIs with the same rights that you have
    • Ensure that State is set to Enabled
    • Select Add scope

Note: The domain part of the Scope name displayed just below the text field should automatically match the Application ID URI set in the previous step, with /access_as_user appended to the end; for example:

  • api://newhireonboarding.azurewebsites.us/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user
  1. In the same page in below section Authorized client applications, you identify the applications that you want to authorize to your app’s web application. Each of the following IDs needs to be entered. Click "+Add a client application" and copy-paste the below id and select checkbox "Authorized scopes". Repeat the step for second GUID.
  • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
  • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
  1. From the left menu, select API Permissions, and add the follow permissions of Microsoft Graph API :

Delegated Permissions:

  • User.ReadBasic.All
  • User.Read.All
  • Directory.Read.All
  • Directory.AccessAsUser.All
  • Team.ReadBasic.All
  • TeamSettings.Read.All
  • openid
  • profile
  • User.ManageIdentities.All

Application Permission:

  • User.Read.All
  • Sites.Read.All
  • GroupMember.Read.All
  • Group.Read.All
  • TeamsAppInstallation.ReadWriteSelfForUser.All

Note: The detailed guidelines for registering an application for SSO Microsoft Teams tab can be found here

Step 7: Set up authentication for bot

  1. Note the name of the bot that you deployed, which is [BaseResourceName].

  2. Go to azure portal here and search for your bot.

  3. Click on the bot in the application list. Under Settings, click on Configuration, click on Add OAuth Connection Settings.

  4. Fill in the form as follows:

    a. For Name, enter NewHireOnboardingAuth. You'll use it in your bot code.

    b. For Service Provider, select Azure Active Directory. Once you select this, the Azure AD-specific fields will be displayed.

    c. For Client ID, enter the application (client) ID that you recorded earlier.

    d. For Client secret, enter the secret that you created to grant the bot access to the Azure AD app.

    e. For Grant type , enter authorization_code.

    f. For Login URL , enter "https://login.microsoftonline.com". Insert your login URL (without a forward slash "/" appended to the end)

    g. For Tenant ID, enter the directory (tenant) ID that you saved earlier for your AAD app. This is the tenant associated with the users who can be authenticated.

    h. For Resource URL , enter "https://graph.microsoft.com/".

    i. For Scopes, keep it blank.

    j. Click Save.

Step 8: Create the Teams app packages

This step covers the Teams application package creation for teams scope and make it ready to install in Teams.

  1. Open the Manifest\manifest.json file in a text editor.
  2. Change the placeholder fields in the manifest to values appropriate for your organization.
  • developer.name (What's this?)
  • developer.websiteUrl
  • developer.privacyUrl
  • developer.termsOfUseUrl
  1. Change the <<botId>> placeholder to your **Azure AD application's ID ** from above. This is the same GUID that you entered in the template under Bot Client ID.
  2. Change <<SharePointNewHireCheckListUrl>> placeholder with Complete learning plan URL which you have recorded before and also make sure replace <<azurefdurl>> with 'https://[baseresourcename].azurewebsites.us'.
  3. In the validDomains section, replace the <<appDomain>> with your Bot App Service's domain. This will be [BaseResourceName].azurewebsites.us. For example if you chose "newhireonboarding " as the base name, change the placeholder to newhireonboarding.azurewebsites.us.
  4. Note : please make sure to not add https:// in valid domains. Also make sure to add "token.botframework.com" and SharePoint tenant name that you have recorded before in "validDomains" section.
  5. In the webApplicationInfo section, replace the <<botId>> with Bot Client ID of the app created in Step 1. Also replace <<ApplicationIdURI>> with following Application URI appended with bot client id. This will be as follows for example api://newhireonboarding.azurewebsites.us/19c1102a-fffe-46c4-9a85-016bec13e0ab where newhireonboarding is the base resource URL and 19c1102a-fffe-46c4-9a85-016bec13e0ab is the bot client id.
  6. Create a ZIP package with the manifest.json, en-US.json, color.png, and outline.png. The two image files are the icons for your app in Teams.
  7. Make sure that the 4 files are the top level of the ZIP package, with no nested folders.

Step 9: Run the apps in Microsoft Teams

  1. If your tenant has side loading apps enabled, you can install your app by following the instructions here
  2. You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install. See here
  3. We recommend using app permission policies to restrict access to this app to the members of the experts team.
  4. Install the app (the NewHireOnboarding.zip package) to your team in Azure Commercial tenant.

Step 10: Update Teams app Id in configuration

  1. Go to the Teams admin portal, here
  2. Go to Manage app section from side menu bar

  1. Search for New Employee Onboarding

  1. Copy the App ID

  1. Go back to Azure Portal here and search app service by [Base Resource Name] which you have provided during deployment.

  1. Go to Configuration from the side menu bar and double click on App:TeamsAppId, Update its value with app Id and make sure to save the changes after updating.

  1. Restart the app service

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally